Upgrading this site (mikeclassic.ca) was pretty straightforward. Following the official Upgrade Guide was easy and less challenging than previous upgrades I’ve done in older Laravel projects.

I go through two major “phases” for these upgrades.

Phase I: Following The Upgrade Guide

In the first phase, I simply follow the official upgrade guide. Do this, do that, change this, change that.

It’s very common that you will skip certain steps in the guide depending on whether you’ve customized or extended different parts of the framework. Rarely, if ever, have I had to perform every single change in the given list.

Phase II: Changing Files Against The Laravel/Laravel Repo

This part, which I haven’t seen mentioned until this 5.5 guide, is comparing changes in your project against the updated laravel/laravel repo. The way I do it, and the way they’ve started to recommend doing it, is to use the Github comparison tool and run through these changes.

I wrote a long, detailed article for the 5.4 upgrade about this part six months ago which I won’t do this time. Basically just go through that comparison of all file changes and apply as needed.

Caveats

There are plenty more caveats to be aware of, but here I’ve documented the ones that directly affected this particular upgrade. These may come in handy for you, even if some of these have been documented elsewhere.

Database Testing Traits

I highly recommend backing up your database before starting. As will be explained below, I accidentally wiped all data on my dev instance during the process.

When I was going through the second phase and updating my tests, one of the changes in the example tests was that they removed the DatabaseTransactions and DatabaseMigrations imports and replaced it with a new one called RefreshDatabase.

RefreshDatabase runs the artisan migrate:fresh command, which is why my data got wiped out. The point of this trait is to reset your test database which you then fill with model factory data. Unfortunately, that’s not the way I had set up my tests. Instead of seeding my entire database with test data, I only seeded specific parts of my database.

DatabaseTransactions, on the other hand, preserves your original data, to which you can add generated data (which I did using model factories). When the tests are done, it then rolls back all the transactions that were performed while running the tests.

Storage, utf8mb4 & You

You may have already gone through the utf8mb4 changeover during the 5.4 upgrade, but I thought it best to note it again, as it tripped me up during this upgrade. Before switching to utf8mb4, default maximum string length for VARCHAR columns was 255. Because utf8mb4 takes up more space per character, changes in string length have to be accounted for. The new maximum string length for VARCHAR becomes 191.

You can set the maximum string length in your AppServiceProvider class. Of course, this will only account for future migrations. Any existing ones you’ll have to account for by creating new migrations to change those columns or handle it manually.

app/Providers/AppServiceProvider.php:

use Illuminate\Support\Facades\Schema;
use Illuminate\Support\ServiceProvider;
/* ... */
class AppServiceProvider extends ServiceProvider
{
    /* ... */
    public function boot()
    {
        Schema::defaultStringLength(191);
    }
    /* ... */
}

Important Links

I linked these in the word salad that is this post, but here are the two things you should follow to apply changes as needed.

1. Official Upgrade Guide
2. 5.4 to 5.5 Files Comparison On Github