Overview

The intent of this guide is to try to replicate as much of a fresh 5.4 install as possible.

This guide and series of articles is meant for existing Laravel installations looking to upgrade from 5.3 to 5.4. Many people perform an upgrade where one might preserve some previous version's setup, such as keeping Elixir instead of Mix. The intent of this guide is to try to replicate as much of a fresh 5.4 install as possible.

I've broken down my Laravel 5.4 upgrade strategy into several separate articles and subject areas. In this one we start with file changes based on the structure built out when using the Laravel installer.

COMPARISON REFERENCE

Visit this Github branch comparison. Make sure you're in the tab labeled “Files Changed.” From here we will compare all changes to the framework's structure — leave this open as we will need it throughout this article.

Laravel Structure

Here we will compare different sections of a fresh install of Laravel against your existing 5.3 installation, and update accordingly.

Tinker

If you want to keep the artisan tinker command, it has now been separated into its own package. You'll have to include it in composer.json and config/app.php as discussed in the notes below.

Database Default Collation

The default character set and collation for SQL databases has been changed from utf8 to utf8mb4. You don't have to change it, but in this guide I will advise you do and explain how and what to note in the Configuration Files section later in this post.

THIS WILL AFFECT YOUR ALLOWABLE MAXIMUM STRING LENGTH IN MIGRATIONS.

During database migrations, your default $table->string('blah') max length is 255 characters. (This converts to VARCHAR(255) in MySQL and MariaDB.) Because of how much physical space utf8mb4 takes up, you are now reduced to a maximum of 191 characters, effectively making a MySQL compatible data type definition of VARCHAR(191):

public function up()
{
    Schema::create('my_table', function (Blueprint $table) {
        $table->increments('id');
        // From a maximum of 255 characters in what turns into VARCHAR(255)
        $table->string('name', 255);
        // To a maximum of 191 characters in what turns into VARCHAR(191)
        $table->string('new_name', 191);
    });
}

Remember, if you need to create new migrations in order to change existing columns, you will have to install the following library:

composer require doctrine/dbal

Read this documentation for more information.

Environment & Dependencies Files

Again, below we'll go over what needs to be changed, but refer to the Github branch comparison as linked to above for the exact changes.

.env.example

For .env.example, there's a couple of key changes related to PUSHER_*.

If you are using Amazon Web Services (AWS), the data previously hard-coded in config/filesystems.php has been extracted into environment variables, i.e. AWS_*.

Remember to update your local .env files accordingly, also.

composer.json

For composer.json, obviously one has to change the Laravel version constraint from 5.3.* to 5.4.*. In addition, they've now separated the tinker artisan command into a separate package. If you want to keep it, you'll have to add the following line:

"laravel/tinker": "~1.0",

If you use Barry's IDE Helper, you'll have to update the minimum version constraint:

"barryvdh/laravel-ide-helper": "^2.2.3"

Tests are now set up under a PSR-4 autoloader.

.gitignore

This is simple to update, just follow the diff.

bootstrap/autoload.php

Several lines have been removed here.

Config Files

First we'll jump back and forth between the Github diff list we've loaded. Compare and update the files in the config/ folder. There's a few files in here you'll have to update, keeping in mind to preserve the changes that are already in there as per the requirements of your app.

config/compile.php has been removed completely.

Tinker

If you plan on keeping the artisan tinker command, and have remembered to include that new library in composer.json, you'll also have to remember to add it to the providers array in config/app.php.

TinkerServiceProvider::class,

config/broadcasting.php

As discussed, the PUSHER_* key name changes in the .env file are used in the updated broadcasting config.

config/cache.php

The file driver path has changed to a data/ subdirectory.

'file' => [
    /* From... */
    'path' => storage_path('framework/cache'),
    /* To... */
    'path' => storage_path('framework/cache/data'),
/* ... */

config/database.php

As mentioned, this is where you would change the database character set and collation from utf8 to utf8mb4.

/* From... */
'charset' => 'utf8',
'collation' => 'utf8_unicode_ci',
/* To... */
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',

config/filesystems.php

If you are using Amazon Web Services (AWS), the data has now been extracted to environment variables instead of hard-coded into the config file.

config/mail.php

There's been a little bit of rearranging near the end of this config. There's also a new markdown entry at the bottom since L5.4 introduced built-in Markdown support for their Mailables.

Middleware Changes

Scrolling back to the top of the branch comparison list, there is a new middleware to add to the user space (and a few added to the Illuminate package) and a change to Http/Kernel.php to reflect it.

Http/Kernel.php

Update the $middleware array accordingly as per the diff, and you'll notice that you'll have to create a new middleware in App\Http\Middleware called TrimStrings.

Middleware/TrimStrings.php

Remember to add this middleware. Its function is to just perform the PHP trim() function on all passed items to the Request, minus any exceptions given to the $except array.

Providers

BroadcastServiceProvider.php

The changes here reflect that L5.4 has now extracted Broadcast channel definitions to a routes/channels.php file.

RouteServiceProvider.php

Here there are changes to the Route “Facade” API but there are no changes to the structure of these routes ‐ same prefix, same namespace, same middleware.

Routes

The routes/api.php file is a pretty straight-forward diff.

routes/channels.php

The config/broadcasting.php definitions have been extracted into a “broadcast routes” file, which is this one.

Views

Some of the views appear in this diff listing. You may or may not want to even keep these views, they're basically placeholders until you build your app for the most part anyway.

See Also

The areas mentioned below are just quick summaries and have their own respective articles in the series that go into more detail.

From Elixir to Mix

I've saved this for a separate article because it'll go easy for you or it'll be a hassle. I haven't yet found an in-between.

Jeffrey Way and Taylor Otwell have replaced Laravel Mix — which was based on Gulp — a general task runner. The replacement is Webpack which is less a task runner and more a module bundler: it does things like compile assets, convert ES2015 to JS, SASS/SCSS/LESS to CSS, etc. You most likely won't be negatively affected by this change.

As far as file changes in the framework structure, you will delete your gulpfile.js and replace it with webpack.mix.js in the root directory of your application.

Please read the article in this series for detailed information.

Testing Structure

The structure of the tests/ directory has changed some. We'll cover this in a separate article.