Laravel 5.4 Upgrade Guide

Upgrading To 5.4.0 From 5.3

Estimated Upgrade Time: 1-2 Hours

Note: note We attempt to document every possible breaking change. Since some of these breaking changes are in obscure parts of the framework only a portion of these changes may actually affect your application.

Updating Dependencies

Update your laravel/framework dependency to 5.4.* in your composer.json file. In addition, you should update your phpunit/phpunit dependency to ~5.7.

Removing Compiled Services File

If it exists, you may delete the bootstrap/cache/compiled.php file. It is no longer used by the framework.

Flushing The Cache

After upgrading all packages, you should run php artisan view:clear to avoid Blade errors related to the removal of Illuminate\View\Factory::getFirstLoop(). In addition, you may need to run php artisan route:clear to flush the route cache.

Laravel Cashier

Laravel Cashier is already compatible with Laravel 5.4.

Laravel Passport

Laravel Passport 2.0.0 has been released to provide compatibility with Laravel 5.4 and the Axios JavaScript library. If you are upgrading from Laravel 5.3 and using the pre-built Passport Vue components, you should make sure the Axios library is globally available to your application as axios.

Laravel Scout

Laravel Scout 3.0.0 has been released to provide compatibility with Laravel 5.4.

Laravel Socialite

Laravel Socialite 3.0.0 has been released to provide compatibility with Laravel 5.4.

Laravel Tinker

In order to continue using the tinker Artisan command, you should also install the laravel/tinker package:

composer require laravel/tinker

Once the package has been installed, you should add Laravel\Tinker\TinkerServiceProvider::class to the providers array in your config/app.php configuration file.

Guzzle

Laravel 5.4 requires Guzzle 6.0 or greater.

Authorization

The getPolicyFor Method

Previous, when calling the Gate::getPolicyFor($class) method, an exception was thrown if no policy could be found. Now, the method will return null if no policy is found for the given class. If you call this method directly, make sure you refactor your code to check for null:

$policy = Gate::getPolicyFor($class);

if ($policy) {
    // code that was previously in the try block
} else {
    // code that was previously in the catch block
}

Blade

@section Escaping

In Laravel 5.4, inline content passed to a section is automatically escaped:

@section('title', $content)

If you would like to render unescaped content in a section, you must declare the section using the traditional "long form" style:

@section('title')
    {!! $content !!}
@stop

Bootstrappers

If you are manually overriding the $bootstrappers array on your HTTP or Console kernel, you should rename the DetectEnvironment entry to LoadEnvironmentVariables and remove ConfigureLogging.

Broadcasting

Channel Model Binding

When defining channel name placeholders in Laravel 5.3, the * character is used. In Laravel 5.4, you should define these placeholders using {foo} style placeholders, like routes:

Broadcast::channel('App.User.{userId}', function ($user, $userId) {
    return (int) $user->id === (int) $userId;
});

Collections

The every Method

The behavior of the every method has been moved to the nth method to match the method name defined by Lodash.

The random Method

Calling $collection->random(1) will now return a new collection instance with one item. Previously, this would return a single object. This method will only return a single object if no arguments are supplied.

Container

Aliasing Via bind / instance

In previous Laravel releases, you could pass an array as the first parameter to the bind or instance methods to register an alias:

$container->bind(['foo' => FooContract::class], function () {
    return 'foo';
});

However, this behavior has been removed in Laravel 5.4. To register an alias, you should now use the alias method:

$container->alias(FooContract::class, 'foo');

Binding Classes With Leading Slashes

Binding classes into the container with leading slashes is no longer supported. This feature required a significant amount of string formatting calls to be made within the container. Instead, simply register your bindings without a leading slash:

$container->bind('Class\Name', function () {
    //
});

$container->bind(ClassName::class, function () {
    //
});

make Method Parameters

The container's make method no longer accepts a second array of parameters. This feature typically indicates a code smell. Typically, you can always construct the object in another way that is more intuitive.

Resolving Callbacks

The container's resolving and afterResolving method now must be provided a class name or binding key as the first argument to the method:

$container->resolving('Class\Name', function ($instance) {
    //
});

$container->afterResolving('Class\Name', function ($instance) {
    //
});

share Method Removed

The share method has been removed from the container. This was a legacy method that has not been documented in several years. If you are using this method, you should begin using the singleton method instead:

$container->singleton('foo', function () {
    return 'foo';
});

Console

The Illuminate\Console\AppNamespaceDetectorTrait Trait

If you are directly referencing the Illuminate\Console\AppNamespaceDetectorTrait trait, update your code to reference Illuminate\Console\DetectsApplicationNamespace instead.

Database

Custom Connections

If you were previously binding a service container binding for a db.connection.{driver-name} key in order to resolve a custom database connection instance, you should now use the Illuminate\Database\Connection::resolverFor method in the register method of your AppServiceProvider:

use Illuminate\Database\Connection;

Connection::resolverFor('driver-name', function ($connection, $database, $prefix, $config) {
    //
});

Fetch Mode

Laravel no longer includes the ability to customize the PDO "fetch mode" from your configuration files. Instead, PDO::FETCH_OBJ is always used. If you would still like to customize the fetch mode for your application you may listen for the new Illuminate\Database\Events\StatementPrepared event:

Event::listen(StatementPrepared::class, function ($event) {
    $event->statement->setFetchMode(...);
});

Eloquent

Date Casts

The date cast now converts the column to a Carbon object and calls the startOfDay method on the object. If you would like to preserve the time portion of the date, you should use the datetime cast.

Foreign Key Conventions

If the foreign key is not explicitly specified when defining a relationship, Eloquent will now use the table name and primary key name for the related model to build the foreign key. For the vast majority of applications, this is not a change of behavior. For example:

public function user()
{
    return $this->belongsTo(User::class);
}

Just like previous Laravel releases, this relationship will typically use user_id as the foreign key. However, the behavior could be different from previous releases if you are overriding the getKeyName method of the User model. For example:

public function getKeyName()
{
    return 'key';
}

When this is the case, Laravel will now respect your customization and determine the foreign key column name is user_key instead of user_id.

BelongsToMany setJoin

The setJoin method has been renamed to performJoin.

Has One / Many createMany

The createMany method of a hasOne or hasMany relationship now returns a collection object instead of an array.

Related Model Connections

Related models will now use the same connection as the parent model. For example, if you execute a query like:

User::on('example')->with('posts');

Eloquent will query the posts table on the example connection instead of the default database connection. If you want to read the posts relationship from the default connection, you should to explicitly set the model's connection to your application's default connection.

The chunk Method

The query builder chunk method now requires an orderBy clause, which provides consistency with the each method. An exception will be thrown if an orderBy clause is not supplied. For example:

DB::table('users')->orderBy('id')->chunk(100, function ($users) {
    foreach ($users as $user) {
        //
    }
});

The Eloquent query builder chunk method will automatically apply an orderBy clause on the model's primary key if one is not supplied.

The create & forceCreate Methods

The Model::create & Model::forceCreate methods have been moved to the Illuminate\Database\Eloquent\Builder class in order to provide better support for creating models on multiple connections. However, if you are extending these methods in your own models, you will need to modify your implementation to call the create method on the builder. For example:

public static function create(array $attributes = [])
{
    $model = static::query()->create($attributes);

    // ...

    return $model;
}

The hydrate Method

If you are currently passing a custom connection name to this method, you should now use the on method:

User::on('connection')->hydrate($records);

hydrateRaw Method

The Model::hydrateRaw method has been renamed to fromQuery. If you are passing a custom connection name to this method, you should now use the on method:

User::on('connection')->fromQuery('...');

The whereKey Method

The whereKey($id) method will now add a "where" clause for the given primary key value. Previously, this would fall into the dynamic "where" clause builder and add a "where" clause for the "key" column. If you used the whereKey method to dynamically add a condition for the key column you should now use where('key', ...) instead.

The factory Helper

Calling factory(User::class, 1)->make() or factory(User::class, 1)->create() will now return a collection with one item. Previously, this would return a single model. This method will only return a single model if the amount is not supplied.

Events

Contract Changes

If you are manually implementing the Illuminate\Contracts\Events\Dispatcher interface in your application or package, you should rename the fire method to dispatch.

Event Priority

Support for event handler "priorities" has been removed. This undocumented feature typically indicates an abuse of the event feature. Instead, consider using a series of synchronous method calls. Alternatively, you may dispatch a new event from within the handler of another event in order to ensure that a given event's handler fires after an unrelated handler.

Wildcard Event Handler Signatures

Wildcard event handlers now receive the event name as their first argument and the array of event data as their second argument. The Event::firing method has been removed:

Event::listen('*', function ($eventName, array $data) {
    //
});

The kernel.handled Event

The kernel.handled event is now an object based event using the Illuminate\Foundation\Http\Events\RequestHandled class.

The locale.changed Event

The locale.changed event is now an object based event using the Illuminate\Foundation\Events\LocaleUpdated class.

The illuminate.log Event

The illuminate.log event is now an object based event using the Illuminate\Log\Events\MessageLogged class.

Exceptions

The Illuminate\Http\Exception\HttpResponseException has been renamed to Illuminate\Http\Exceptions\HttpResponseException. Note that Exceptions is now plural. Likewise, the Illuminate\Http\Exception\PostTooLargeException has been renamed to Illuminate\Http\Exceptions\PostTooLargeException.

Mail

Class@method Syntax

Sending mail using Class@method syntax is no longer supported. For example:

Mail::send('view.name', $data, 'Class@send');

If you are sending mail in this way you should convert these calls to mailables.

New Configuration Options

In order to provide support for Laravel 5.4's new Markdown mail components, you should add the following block of configuration to the bottom of your mail configuration file:

'markdown' => [
    'theme' => 'default',

    'paths' => [
        resource_path('views/vendor/mail'),
    ],
],

Queueing Mail With Closures

In order to queue mail, you now must use a mailable. Queuing mail using the Mail::queue and Mail::later methods no longer supports using Closures to configure the mail message. This feature required the use of special libraries to serialize Closures since PHP does not natively support this feature.

Queue

Failed Jobs Table

If your application contains a failed_jobs table, you should add an exception column to the table:

$table->longText('exception')->after('payload');

Redis

Improved Clustering Support

Laravel 5.4 introduces improved Redis cluster support. If you are using Redis clusters, you should place your cluster connections inside of a clusters configuration option in the Redis portion of your config/database.php configuration file:

'redis' => [

    'client' => 'predis',

    'options' => [
        'cluster' => 'redis',
    ],

    'clusters' => [
        'default' => [
            [
                'host' => env('REDIS_HOST', '127.0.0.1'),
                'password' => env('REDIS_PASSWORD', null),
                'port' => env('REDIS_PORT', 6379),
                'database' => 0,
            ],
        ],
    ],

],

Routing

Post Size Middleware

The class Illuminate\Foundation\Http\Middleware\VerifyPostSize has been renamed to Illuminate\Foundation\Http\Middleware\ValidatePostSize.

The middleware Method

The middleware method of the Illuminate\Routing\Router class has been renamed to aliasMiddleware(). It is likely that most applications never call this method manually, as it is typically only called by the HTTP kernel to register route-level middleware defined in the $routeMiddleware array.

Route Methods

The getUri method of the Illuminate\Routing\Route class has been removed. You should use the uri method instead.

The getMethods method of the Illuminate\Routing\Route class has been removed. You should use the methods method instead.

The getParameter method of the Illuminate\Routing\Route class has been removed. You should use the parameter method instead.

The getPath method of the Illuminate\Routing\Route class has been removed. You should use the uri method instead.

Sessions

Symfony Compatibility

Laravel's session handlers no longer implements Symfony's SessionInterface. Implementing this interface required us to implement extraneous features that were not needed by the framework. Instead, a new Illuminate\Contracts\Session\Session interface has been defined and may be used instead. The following code changes should also be applied:

All calls to the ->set() method should be changed to ->put(). Typically, Laravel applications would never call the set method since it has never been documented within the Laravel documentation. However, it is included here out of caution.

All calls to the ->getToken() method should be changed to ->token().

All calls to the $request->setSession() method should be changed to setLaravelSession().

Testing

Laravel 5.4's testing layer has been re-written to be simpler and lighter out of the box. If you would like to continue using the testing layer present in Laravel 5.3, you may install the laravel/browser-kit-testing package into your application. This package provides full compatibility with the Laravel 5.3 testing layer. In fact, you can run the Laravel 5.4 testing layer side-by-side with the Laravel 5.3 testing layer.

In order to allow Laravel to autoload any new tests you generate using the Laravel 5.4 test generators, you should add the Tests namespace to your composer.json file's autoload-dev block:

"psr-4": {
    "Tests\\": "tests/"
}

Running Laravel 5.3 & 5.4 Tests In A Single Application

First install the laravel/browser-kit-testing package:

composer require laravel/browser-kit-testing="1.*" --dev

Once the package has been installed, create a copy of your tests/TestCase.php file and save it to your tests directory as BrowserKitTestCase.php. Then, modify the file to extend the Laravel\BrowserKitTesting\TestCase class. Once you have done this, you should have two base test classes in your tests directory: TestCase.php and BrowserKitTestCase.php. In order for your BrowserKitTestCase class to be properly loaded, you may need to add it to your composer.json file:

"autoload-dev": {
    "classmap": [
        "tests/TestCase.php",
        "tests/BrowserKitTestCase.php"
    ]
},

Tests written on Laravel 5.3 will extend the BrowserKitTestCase class while any new tests that use the Laravel 5.4 testing layer will extend the TestCase class. Your BrowserKitTestCase class should look like the following:

<?php

use Illuminate\Contracts\Console\Kernel;
use Laravel\BrowserKitTesting\TestCase as BaseTestCase;

abstract class BrowserKitTestCase extends BaseTestCase
{
    /**
     * The base URL of the application.
     *
     * @var string
     */
    public $baseUrl = 'http://localhost';

    /**
     * Creates the application.
     *
     * @return \Illuminate\Foundation\Application
     */
    public function createApplication()
    {
        $app = require __DIR__.'/../bootstrap/app.php';

        $app->make(Kernel::class)->bootstrap();

        return $app;
    }
}

Once you have created this class, make sure to update all of your tests to extend your new BrowserKitTestCase class. This will allow all of your tests written on Laravel 5.3 to continue running on Laravel 5.4. If you choose, you can slowly begin to port them over to the new Laravel 5.4 test syntax or Laravel Dusk.

Note: note If you are writing new tests and want them to use the Laravel 5.4 testing layer, make sure to extend the TestCase class.

Installing Dusk In An Upgraded Application

If you would like to install Laravel Dusk into an application that has been upgraded from Laravel 5.3, first install it via Composer:

composer require laravel/dusk

Next, you will need to create a CreatesApplication trait in your tests directory. This trait is responsible for creating fresh application instances for test cases. The trait should look like the following:

<?php

use Illuminate\Contracts\Console\Kernel;

trait CreatesApplication
{
    /**
     * Creates the application.
     *
     * @return \Illuminate\Foundation\Application
     */
    public function createApplication()
    {
        $app = require __DIR__.'/../bootstrap/app.php';

        $app->make(Kernel::class)->bootstrap();

        return $app;
    }
}

Note: note If you have namespaced your tests and are using the PSR-4 autoloading standard to load your tests directory, you should place the CreatesApplication trait under the appropriate namespace.

Once you have completed these preparatory steps, you can follow the normal Dusk installation instructions.

Environment

The Laravel 5.4 test class no longer manually forces putenv('APP_ENV=testing') for each test. Instead, the framework utilizes the APP_ENV variable from the loaded .env file.

Event Fake

The Event fake's assertFired method should be updated to assertDispatched, and the assertNotFired method should be updated to assertNotDispatched. The method's signatures have not been changed.

Mail Fake

The Mail fake has been greatly simplified for the Laravel 5.4 release. Instead of using the assertSentTo method, you should now simply use the assertSent method and utilize the hasTo, hasCc, etc. helper methods within your callback:

Mail::assertSent(MailableName::class, function ($mailable) {
    return $mailable->hasTo('email@example.com');
});

Translation

{Inf} Placeholder

If you are using the {Inf} placeholder for pluralizing your translation strings, you should update your translation strings to use the * character instead:

{0} First Message|{1,*} Second Message

The trans Helpers

The trans helper signature has been updated to remove the unnecessary $domain argument. The new signature is as follows:

/**
 * Translate the given message.
 *
 * @param  string  $id
 * @param  array   $replace
 * @param  string  $locale
 * @return \Illuminate\Contracts\Translation\Translator|string|array|null
 */
function trans($id = null, $replace = [], $locale = null);

In addition, the trans_choice helper has been updated:

/**
 * Translates the given message based on a count.
 *
 * @param  string  $id
 * @param  int|array|\Countable  $number
 * @param  array   $replace
 * @param  string  $locale
 * @return string
 */
function trans_choice($id, $number, array $replace = [], $locale = null);

URL Generation

The forceSchema Method

The forceSchema method of the Illuminate\Routing\UrlGenerator class has been renamed to forceScheme.

Validation

Date Format Validation

Date format validation is now more strict and supports the placeholders present within the documentation for the PHP date function. In previous releases of Laravel, the timezone placeholder P would accept all timezone formats; however, in Laravel 5.4 each timezone format has a unique placeholder as per the PHP documentation.

Method Names

The addError method has been renamed to addFailure. In addition, the doReplacements method has been renamed to makeReplacements. Typically, these changes will only be relevant if you are extending the Validator class.

Miscellaneous

We also encourage you to view the changes in the laravel/laravel GitHub repository. While many of these changes are not required, you may wish to keep these files in sync with your application. Some of these changes will be covered in this upgrade guide, but others, such as changes to configuration files or comments, will not be. You can easily view the changes with the GitHub comparison tool and choose which updates are important to you.