Stefan Bauer
Developer and Creator of PingPing.io, a simple website monitoring.
Blog Building PingPing About
"Building PingPing" is an open-source project. You can find the sources on GitHub

#004: Upgrading to Laravel 5.6 using Laravel Shift

Published on February 23, 2018

What is Laravel Shift and how does it work?

Automated, instant Laravel upgrade services by an army of thorough bots and friendly humans too.

This is, how Laravel Shift describes itself. Laravel Shift was created by Jason McCreary. How Laravel Shift works, is really easy. It's an awesome tool as I'm gonna show you in the next chapters.

  1. Sign in with Git
  2. Choose your Shift
  3. Review the upgrade

Let's do it together.

1. Sign in with Git

First let's login via Git. Click on the "Get started now"-button. There are three login methods at this time. You can choose between GitHub, Bitbucket or GitLab. In my case I use GitHub.

Sign in with GitHub

Provide your credentials and login. Now it's time to authorize Laravel Shift to get access your VCS, which is GitHub here. Laravel Shift needs access because it needs to know which repository should be upgraded. So just authorize it and you're good to go.

Authorize Laravel Shift

2. Choose your Shift

Now it's time to choose your Shift. You need to know which Laravel version your current project is on and to which version you would like to upgrade. In our case we're currently at the version 5.5.x and want to upgrade to Laravel 5.6. So create a new Shift and choose what you need to.

Choose your Shift

Select your repository

After you chose the shift, you have to tell Laravel Shift which repository you would like to upgrade. How easy is that? Enter your repository details and start shifting.

Laravel Shift repository details

The shift is running

Now it takes some time. What now happens is, that Laravel Shift examines your repository and your code. It upgrades all the stuff, which is necessary to throw you on the current version of the shift. The cool thing about it is, that it doesn't do anything without your permission. It creates a pull request where you can review all the stuff, that Laravel Shift did. After the Shift has finished, it's up to us to decide what we would like to merge and what not. May by there are some more changes we would like to push. But let's check the review in the next chapter.

3. Review the upgrade

When Shift has finished, you should see something like that. Click on the branch symbol. This takes you immediately to the createad pull request.

Laravel Shift Pull Request

You can find the related pull request created here: https://github.com/stefanbauer/pingping/pull/1. So now let's take a look. The most comments what Shift created can be ignored in our case. But there one we should take a closer look at.

  • ⚠ Shift could not upgrade the following project files since they differed from the default Laravel version. You should compare these project files against the default Laravel 5.6 versions and merge any changes: .env.example

If you remember, we renamed the .env.example to .env.dist. That's why Shift did not recognize it. But no problems here, we can do it by our own. Locally I check out this branch shift-6234. There are now two things I'm gonna do.

Updating the .env

If you take a look at the new default .env.example in the Laravel Project Repository, you'll find a handful new properties. These are LOG_CHANNEL, MIX_PUSHER_APP_KEY and MIX_PUSHER_APP_CLUSTER. Easy enough. Just copy them over to our .env (which is not under version control) and our .env.dist. Commit it to the Shift-Branch. Here is the commit.

Installing new dependencies

As you can see, that Laravel Shift updates also the composer.json file to fit the current versions, we have to update these packages in our /vendor directory. Here is, what Shift did with our composer.json. It suggests, that you run composer update.

Here is my opinion: Every single time, when people are running a composer update, I ask them if they are sure and they really know what happens and which versions get be installed. With this command, you updates every single package related to your configuration setting in your composer.json. Be 100% sure, that there are no side effects by updating just blindly every package. I am not a big fan of this approach, because I don't know what happens exactly and why packages get updated and which features/changes/bugfixes are in the latest versions. My advise in general is:

Update carefully and selectively! Update package by package. You can do that with composer update my/package. If you're unsure why a package will or will not be installed, there is always the possibility to use the command composer why or composer why-not to get more information. So for example: If we are interested in, why the package symfony/debug has been installed, we can use the above command.

➜  pingping git:(master) composer why symfony/debug
laravel/framework    v5.6.2  requires  symfony/debug (~4.0)
symfony/http-kernel  v4.0.4  requires  symfony/debug (~3.4|~4.0)

In our case it's fine to a run a composer update, as we have no custom packages pulled in and I know what has been changed in these packages. So give it a run! This updates our composer.lock. Now it's time to commit that too and push it up to the shift branch. The result of this commit you can find here.

Merging back

That's it. We're done. We reviewed everything. We modified everything that was necessary and now the time has come to merge that into our master branch. As you know me, I do everyhing on the CLI because I have more control. Here, I merge it (just for you) in the GitHub UI.

Squash and merge

Some words on that: Laravel Shift created four commits as I remember. We pushed another two commits on that branch. What I hate, even if some other people always saying that this doesn't matter, is a dirty and messy git history. I love clean and simple git histories, that show the progress in a very clean and simple way. Should be readable like a book. So we squash all the commits of the shift branch down to one with a simplified but clear commit message.

Congratulations! We're done! This was the very first time, I've ever tried Laravel Shift. I was surprised how easy it was. I can highly recommend it to everyone who'd like to upgrade Laravel projects without any hassle.

Imprint Cookie Policy Privacy Policy
Proudly hosted with Vultr