My Laravel Upgrade Flow

If you work with Laravel PHP framework like me, you have surely done an upgrade to a newer version of Laravel. In this article I want to share an upgrade workflow that I usually do when I upgrade some Laravel app.

The steps that I present here can ensure that you have considered all the customization in your current app, while also taking into account all the modifications that are introduced in the new Laravel version.

Let’s say that we have an app that is currently run on Laravel 5.5.* and that we want to bump it to Laravel 7.*.

Just to note, my dev setup is:

Windows with WSL (Linux Subsystem)
Docker (Debian, Apache, PHP)
PHPStorm
Git

Steps for upgrade from Laravel 5.5.* to Laravel 7.*

Git

The first thing I do is create the following:

in the current app repository create a new Git branch from ‘master’ branch. It can be called something like ‘laravel-7-upgrade’. This branch is used to do all code modifications regarding upgrade process, in the current app. When we are ready at the end, we will merge it with the ‘master’ branch. The sample command to do this is:

cd ~/projects/app
git checkout master
git checkout -b laravel-7-upgrade

create a new app which will hold a Laravel 7 base installation. When I say ‘base installation’, I mean installation of Laravel without any custom modifications. We will use this new app to check and sync code between Laravel 5.5.* app and Laravel 7.* app. The result we want is to have our current app and a Laravel 7 app in sync. To create a new Laravel 7 app, create a new Laravel project (of course in a separate directory):

cd ..
composer create-project --prefer-dist laravel/laravel:7.* laravel-7-base-installation

create a new app which will hold a Laravel 5.5.* base installation. We will use this app to check the differences between our production Laravel 5.5.* app and a basic Laravel 5.5.* installation. This way we can be sure about all the custom things that we have introduced in the current app.

composer create-project --prefer-dist laravel/laravel:5.5.* laravel-55-base-installation

Comparing Code

The next step is to compare the code in the current app to the Laravel 7 base installation, and sync all the changes. While we do this we can also reference the Laravel 5 base installation, so we can be sure about our custom modifications in the current app. Let me show you what I mean.

To do code comparison I use an app called WinMerge. It is an Open Source differencing and merging tool for Windows. It can compare both folders and files, presenting differences in a visual text format that is easy to understand and handle.

Let’s compare our current app with the Laravel 7 installation.

In another WinMerge window, I’ll also do a comparison for current app and a Laravel 5.5 base installation.

Now, let’s take a look in comparison results for Laravel 7 base installation. Note the marked ‘Left only’ result.

The ‘Left only’ means that those two folders exist only in our current app. I will copy those two folders to the Laravel 7 installation, so we can keep track of all the changes we have made when comparing our current installation with Laravel 7 installation. Remember, the final result we want is that the current app and a Laravel 7 app are in sync (that it has same content). To copy selected directories we can use button ‘Copy right’:

This action will place marked directories in the Laravel 7 app. If we refresh the comparison results (press F5 or click refresh button), we will see that they are now marked as ‘Identical’.

Let’s take a look at the next example. We have a ‘Kernel.php’ file with different text.

When we open it, we see the next difference.

The only difference is in one comment. We can safely use the version from Laravel 7, since it is newer. To do this, first we mark the difference and then click on the ‘Copy left’ button.

This will bring the change from Laravel 7 app to the current app. When we save and refresh comparison results, we will again see the Kernel.php file marked as ‘Identical’.

Next case, let’s check out Handler.php file.

Right at the top we see a difference in the ‘use’ statements. The question now is which lines are our custom modifications that we have made in the current app, and which changes are introduced in the Laravel 7 version.

To check our custom modifications, we can compare current app with the Laravel 5.5 base installation. Let’s see a comparison result for the Handler.php file in Laravel 5.5 base installation.

As we can see, our custom modification is that we have used ‘AuthenticationException’ and ‘ValidationException’, so we know that those two lines must stay. Other lines correspond to the Laravel 5.5 base installation, so we can consider changing them.

The sync procedure now is this. I copy right to the Laravel 7 app all custom code. I copy left to the current app all newly introduced code if it doesn’t conflict with current code.

For example, in the new Laravel 7 app, it now has the line ‘use Throwable’ instead of ‘use Exception’. After a brief look at the code, I see that the report() method signature is changed and that it now uses Throwable. The Exception class is never used anymore in this file, so I can be sure to replace ‘use Exception’ with ‘use Throwable’. The result for this difference would be this:

Let’s move down and take a look at other difference in the same file. We have a method report() which now has a different signature.

As we mentioned, it now accepts Throwable parameter instead of Exception. Let’s take a look at the comparison with Laravel 5.5 so we can be sure about our modifications that we have introduced in this file regarding this method.

We can see that the only change is in the body of the method. This means that we have to take the new signature from Laravel 7, and also use our custom code in the method. In this case, despite the new signature, the custom code will still work, since Exception is Throwable. The result for this difference is:

There are still some differences in this file, but to solve them the concept is the same as mentioned in the previous example. Let’s take a look at the next case.

The marked files (new config files) are only available in Laravel 7 app, so we can safely copy them to our current app (copy left).

When it comes to cache files, it actually doesn’t matter which version we choose to keep, since those are generated files.

They will actually be cleared in the end of the procedure, so we can use left or right version just to have them in sync, so they don’t get in our way.

Refreshing Composer and Node packages

Regarding Composer, when it comes to ‘composer.json’ file, in essence you should replace all the packages with the newer version from Laravel 7, and keep all the custom packages in your current app. File ‘composer.lock’ can be deleted, as well as ‘vendor’ directory.

Similar thing is with the file ‘packages.json’ – use newer version packages, and keep custom packages. Directory ‘node_modules’ can be deleted.

After the configuration of composer.json and packages.json file, we can enter the following commands to refresh all the newly included and kept packages. Commands are entered for current app:

composer install
npm install

File ‘composer.lock’ can now be copied right to the Laravel 7 app, just to have it in sync. Folders ‘vendor’ and ‘node_modules’ can be copied also, or the above-mentioned commands can be run in the Laravel 7 folder.

To clear all the auto generated files in Laravel, we can now enter the following command in the current app:

php artisan optimize:clear

We can also sync this with the Laravel 7, just to have it in sync.

At the end of the procedure of comparing current app with Laravel 7 app, we should have all the folders and files in sync, like this.

Check Laravel upgrade guides

Laravel documentation is good at covering all the changes a new version brings. When upgrading, we should read all the upgrade guides from the version we are upgrading from to the version we are upgrading to.

For example, in our case, we have regularly used ‘str_’ helper functions which were available in Laravel 5.5 https://laravel.com/docs/5.5/helpers#available-methods, and which are now replaced with ‘Illuminate\Support\Str’ class https://laravel.com/docs/7.x/helpers#available-methods. This means we must search for all occurrences of ‘str_’ functions in our code and replace them with corresponding methods available in ‘Str’ class.

PHP version

If you didn’t already run your Laravel 5.5.* application on higher PHP version, upgrading from Laravel 5.5.* to Laravel 7.* also means upgrading from PHP 7.0 to PHP 7.2 or higher. If this is the case, this means that we should also check upgrade guides for PHP:

Save production state and git commit 🙂

When you have made sure that your app works, you can make your commit for the upgrade. When upgrading, I like to have as few commits as possible, preferably only one 🙂 (as if everything works from single commit :P).

git commit -m "Upgrade to Laravel 7"
git push -u origin laravel-7-upgrade

If you remember, we are on a new branch used for upgrade only. We still have our production state available on the ‘master’ branch. Let’s just keep current production state in a new branch, so we have it available for quick checkout.

git checkout master
git checkout -b pre-laravel-7-upgrade
git checkout master

At this point, since everything works, we can merge the upgrade branch with master and push it to repository.

git merge laravel-7-upgrade
git push