Release Notes

Versioning Scheme

Laravel's versioning scheme maintains the following convention: paradigm.major.minor. Major framework releases are released every six months (February and August), while minor releases may be released as often as every week. Minor releases should never contain breaking changes.

When referencing the Laravel framework or its components from your application or package, you should always use a version constraint such as 5.5.*, since major releases of Laravel do include breaking changes. However, we strive to always ensure you may update to a new major release in one day or less.

Paradigm shifting releases are separated by many years and represent fundamental shifts in the framework's architecture and conventions. Currently, there is no paradigm shifting release under development.

Why Doesn't Laravel Use Semantic Versioning?

On one hand, all optional components of Laravel (Cashier, Dusk, Valet, Socialite, etc.) do use semantic versioning. However, the Laravel framework itself does not. The reason for this is because semantic versioning is a "reductionist" way of determining if two pieces of code are compatible. Even when using semantic versioning, you still must install the upgraded package and run your automated test suite to know if anything is actually incompatible with your code base.

So, instead, the Laravel framework uses a versioning scheme that is more communicative of the actual scope of the release. Furthermore, since minor releases never contain intentional breaking changes, you should never receive a breaking change as long as your version constraints follow the paradigm.major.* convention.

Support Policy

For LTS releases, such as Laravel 5.5, bug fixes are provided for 2 years and security fixes are provided for 3 years. These releases provide the longest window of support and maintenance. For general releases, bug fixes are provided for 6 months and security fixes are provided for 1 year.

Package Discovery

{video} There is a free video tutorial for this feature available on Laracasts.

In previous versions of Laravel, installing a package typically required several additional steps such as adding the service provider to your app configuration file and registering any relevant facades. However, beginning with Laravel 5.5, Laravel can automatically detect and register service providers and facades for you.

For example, you can experience this by installing the popular barryvdh/laravel-debugbar package into your Laravel application. Once the package is installed via Composer, the debug bar will be available to your application with no additional configuration:

composer require barryvdh/laravel-debugbar

Package developers only need to add their service providers and facades to their package's composer.json file:

For more information on updating your packages to use service provider and facade discovery, check out the full documentation on package development.

API Resources

When building an API, you may need a transformation layer that sits between your Eloquent models and the JSON responses that are actually returned to your application's users. Laravel's resource classes allow you to expressively and easily transform your models and model collections into JSON.

A resource class represents a single model that needs to be transformed into a JSON structure. For example, here is a simple UserResource class:

Of course, this is only the most basic example of an API resource. Laravel also provides a variety of methods to help you when building your resources and resource collections. For more information, check out the full documentation on API resources.

Console Command Auto-Registration

{video} There is a free video tutorial for this feature available on Laracasts.

When creating new console commands, you no longer are required to manually list them in the $commands property of your Console kernel. Instead, a new load method is called from the commands method of your kernel, which will scan the given directory for any console commands and register them automatically:

New Frontend Presets

{video} There is a free video tutorial for this feature available on Laracasts.

While the basic Vue scaffolding is still included in Laravel 5.5, several new frontend preset options are now available. In a fresh Laravel application, you can swap the Vue scaffolding for React scaffolding using the preset command:

php artisan preset react

Or, you can remove the JavaScript and CSS framework scaffolding entirely using the none preset. This preset will leave your application with a plain Sass file and a few simple JavaScript utilities:

php artisan preset none

These commands are only intended to be run on fresh Laravel installations. They should not be used on existing applications.

Queued Job Chaining

Job chaining allows you to specify a list of queued jobs that should be run in sequence. If one job in the sequence fails, the rest of the jobs will not be run. To execute a queued job chain, you may use the withChain method on any of your dispatchable jobs:

ProvisionServer::withChain([
new InstallNginx,
new InstallPhp
])->dispatch();

Queued Job Rate Limiting

If your application interacts with Redis, you may now throttle your queued jobs by time or concurrency. This feature can be of assistance when your queued jobs are interacting with APIs that are also rate limited. For example, you may throttle a given type of job to only run 10 times every 60 seconds:

In the example above, the key may be any string that uniquely identifies the type of job you would like to rate limit. For example, you may wish to construct the key based on the class name of the job and the IDs of the Eloquent models it operates on.

Alternatively, you may specify the maximum number of workers that may simultaneously process a given job. This can be helpful when a queued job is modifying a resource that should only be modified by one job at a time. For example, we may limit jobs of a given type to only be processed by one worker at a time:

Time Based Job Attempts

As an alternative to defining how many times a job may be attempted before it fails, you may now define a time at which the job should timeout. This allows a job to be attempted any number of times within a given time frame. To define the time at which a job should timeout, add a retryUntil method to your job class:

/**
* Determine the time at which the job should timeout.
*
* @return \DateTime
*/
public function retryUntil()
{
return now()->addSeconds(5);
}

You may also define a retryUntil method on your queued event listeners.

Validation Rule Objects

{video} There is a free video tutorial for this feature available on Laracasts.

Validation rule objects provide a new, compact way of adding custom validation rules to your application. In previous versions of Laravel, the Validator::extend method was used to add custom validation rules via Closures. However, this can grow cumbersome. In Laravel 5.5, a new make:rule Artisan command will generate a new validation rule in the app/Rules directory:

php artisan make:rule ValidName

A rule object only has two methods: passes and message. The passes method receives the attribute value and name, and should return true or false depending on whether the attribute value is valid or not. The message method should return the validation error message that should be used when validation fails:

Trusted Proxy Integration

When running applications behind a load balancer that terminates TLS / SSL certificates, you may notice your application sometimes does not generate HTTPS links. Typically this is because your application is being forwarded traffic from your load balancer on port 80 and does not know it should generate secure links.

To solve this, many Laravel users install the Trusted Proxies package by Chris Fidao. Since this is such a common use case, Chris' package now ships with Laravel 5.5 by default.

A new App\Http\Middleware\TrustProxies middleware is included in the default Laravel 5.5 application. This middleware allows you to quickly customize the proxies that should be trusted by your application:

On-Demand Notifications

Sometimes you may need to send a notification to someone who is not stored as a "user" of your application. Using the new Notification::route method, you may specify ad-hoc notification routing information before sending the notification:

Renderable & Reportable Exceptions

{video} There is a free video tutorial for this feature available on Laracasts.

In previous versions of Laravel, you may have had to resort to "type checking" in your exception handler in order to render a custom response for a given exception. For instance, you may have written code like this in your exception handler's render method:

In Laravel 5.5, you may now define a render method directly on your exceptions. This allows you to place the custom response rendering logic directly on the exception, which helps avoid conditional logic accumulation in your exception handler. If you would like to also customize the reporting logic for the exception, you may define a report method on the class:

Consistent Exception Handling

Validation exception handling is now consistent throughout the framework. Previously, there were multiple locations in the framework that required customization to change the default format for JSON validation error responses. In addition, the default format for JSON validation responses in Laravel 5.5 now adheres to the following convention:

All JSON validation error formatting can be controlled by defining a single method on your App\Exceptions\Handler class. For example, the following customization will format JSON validation responses using the Laravel 5.4 convention.

Cache Locks

The Redis and Memcached cache drivers now have support for obtaining and releasing atomic "locks". This provides a simple method of obtaining arbitrary locks without worrying about race conditions. For example, before performing a task, you may wish to obtain a lock so no other processes attempt the same task that is already in progress:

if (Cache::lock('lock-name', 60)->block(10)) {
// Wait for a maximum of 10 seconds for the lock to become available...
}

Blade Improvements

{video} There is a free video tutorial for this feature available on Laracasts.

Programming a custom directive is sometimes more complex than necessary when defining simple, custom conditional statements. For that reason, Blade now provides a Blade::if method which allows you to quickly define custom conditional directives using Closures. For example, let's define a custom conditional that checks the current application environment. We may do this in the boot method of our AppServiceProvider:

Once the custom conditional has been defined, we can easily use it on our templates:

@env('local')
// The application is in the local environment...
@else
// The application is not in the local environment...
@endenv

In addition to the ability to easily define custom Blade conditional directives, new shortcuts have been added to quickly check the authentication status of the current user:

@auth
// The user is authenticated...
@endauth
@guest
// The user is not authenticated...
@endguest

New Routing Methods

{video} There is a free video tutorial for this feature available on Laracasts.

If you are defining a route that redirects to another URI, you may now use the Route::redirect method. This method provides a convenient shortcut so that you do not have to define a full route or controller for performing a simple redirect:

Route::redirect('/here', '/there', 301);

If your route only needs to return a view, you may now use the Route::view method. Like the redirect method, this method provides a simple shortcut so that you do not have to define a full route or controller. The view method accepts a URI as its first argument and a view name as its second argument. In addition, you may provide an array of data to pass to the view as an optional third argument:

The sticky option is an optional value that can be used to allow the immediate reading of records that have been written to the database during the current request cycle. If the sticky option is enabled and a "write" operation has been performed against the database during the current request cycle, any further "read" operations will use the "write" connection. This ensures that any data written during the request cycle can be immediately read back from the database during that same request. It is up to you to decide if this is the desired behavior for your application.