Upgrading Laravel
The time is almost upon us… time for another Laravel release! If you’re like me, you’re excited about the new features, but less than enthused about the manual portion of the upgrade process. Upgrading your dependencies is easy, right? Run your composer update and everything’s good to go. It’s those pesky changes in laravel/laravel that are hard to keep in sync!
If you’re willing to pay, Laravel Shift is a great solution to automatically upgrade your applications. If you’re unable or unwilling to pay, though, I’m here today to show you the most efficient way to keep your Laravel applications up to date!
To begin, we’re going to clone the laravel/laravel repository to our local machine. There are multiple ways to do this, but we’ll visit the Laravel Repo on Github and clone it into Github Desktop. On the repository page, click the green button titled “Clone or Download”, and then click “Open in Desktop”. Choose a location on your local machine to save this repository.
If you already have the laravel/laravel repository cloned to your local machine, make sure it is synced with the upstream repository. There are a couple of options to do this, but I personally like rebasing my fork off of the upstream.
cd ~/code/forks/laravel/laravel
git fetch upstream
git rebase upstream/master
Great! We’re one step closer to making some changes to our application. Before we dive straight in, let’s be good developers and create a branch of our application that we can apply these changes to. I’ll use Github Desktop to make a new branch called laravel-upgrade.
Now that we have our source of truth downloaded (the laravel/laravel repository) and our application branched, we are going to use our IDE to compare our application to the upstream repository. My IDE of choice is PHPStorm, but most IDEs should have similar functionality.
Open up your local laravel/laravel project in your IDE.
Select the top level folder of this project. In the menu, select “View” and then “Compare With…”.
Navigate to the project you would like to upgrade, and select the top level application directory.
Depending on the size of your project (and if it finds the black hole known as node_modules) this could take a minute. Once it’s finished, you’ll notice there are A LOT of differences, so we’ll want to make one small tweak to reduce the noise. At the top, there will be 4 colorful arrows and equal signs. These are toggles that let us adjust which files we show. The blue Right Arrow shows files that exist in the left project (the upstream repo) but not the right project (our application). We want to show these, because these are most likely new files added to the laravel/laravel repo since we first started our project. Next is a red Not Equal Sign we also want selected, which shows files that exist in both projects, but have differences within.
The grey Equal Sign and the green Left Arrow should be deselected. These show identical files, and files that exist in our project but not the upstream repository, respectively. These files are fine, as is, and we do not need to worry about reviewing them.
Great, now we’ve got a succinct list of all the difference we’ll need to address. For me, I had about 60 files total to analyze. There will be some files you expect to have differences, such as service providers and routes. While you should look through every file, the places I traditionally find a lot of these miscellaneous updates are in the /config path, the /resources/lang path, app/Http/Middleware, and occasionally the root of the project.
If we are looking at a file that only exists in our upstream repository, PHPStorm will show the file name on the left, and an empty line on the right. To copy the new file to your project, select the appropriate line, and then click the “Synchronize Selected” button at the top, which looks like a green play button. Now we have the new file in our project as well!
If we are looking at differences within a file, PHPStorm will show the contents of the files side by side when the line is selected. It uses highlighting to show you which lines exist only on one side, or are slightly different from side to side. You will be presented with 2 sets of double arrows between the two files, which allows you to copy code from one side to the other. We will not use the double arrows pointing left, because that would copy our application code to our laravel/laravel repository. However, if you come across some code that exists in the upstream repository, but is not in your application and you would like it to be, click the double right arrows to copy it over. In the image below, you can see some additional hashing options that have been added to the framework, that we will add to our application.
There you have it, a simple way to compare the laravel/laravel repository to your application code. This process is great when used in conjunction with the Laravel Upgrade Guide, and helps you quickly and effectively catch all of those hard-to-document changes in the framework.
Got any other tips and tricks for upgrading your Laravel apps? Hit me up in the comments.
Thanks for reading!
