- Upgrading To 5.1.11
- Upgrading To 5.1.0
- Upgrading To 5.0.16
- Upgrading To 5.0 From 4.2
- Upgrading To 4.2 From 4.1
- Upgrading To 4.1.29 From <= 4.1.x
- Upgrading To 4.1.26 From <= 4.1.25
- Upgrading To 4.1 From 4.0
Laravel 5.1.11 includes support for authorization and policies. Incorporating these new features into your existing Laravel 5.1 applications is simple.
Note: These upgrades are optional, and ignoring them will not affect your application.
First, create an empty app/Policies directory within your application.
Create a AuthServiceProvider within your app/Providers directory. You may copy the contents of the default provider from GitHub. Remember to change the provider's namespace if your application is using a custom namespace. After creating the provider, be sure to register it in your app.php configuration file's providers array.
Also, you should register the Gate facade in your app.php configuration file's aliases array:
'Gate' => Illuminate\Support\Facades\Gate::class,
Secondly, use the Illuminate\Foundation\Auth\Access\Authorizable trait and Illuminate\Contracts\Auth\Access\Authorizable contract on your App\User model:
<?php
namespace App;
use Illuminate\Auth\Authenticatable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Auth\Passwords\CanResetPassword;
use Illuminate\Foundation\Auth\Access\Authorizable;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;
use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;
class User extends Model implements AuthenticatableContract,
AuthorizableContract,
CanResetPasswordContract
{
use Authenticatable, Authorizable, CanResetPassword;
}
Next, update your base App\Http\Controllers\Controller controller to use the Illuminate\Foundation\Auth\Access\AuthorizesRequests trait:
<?php
namespace App\Http\Controllers;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
abstract class Controller extends BaseController
{
use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}
Update the $compiledPath variable in bootstrap/autoload.php to the following:
$compiledPath = __DIR__.'/cache/compiled.php';
Within your bootstrap directory, create a cache directory (bootstrap/cache). Place a .gitignore file in this directory with the following contents:
*
!.gitignore
This directory should be writable, and will be used by the framework to store temporary optimization files like compiled.php, routes.php, config.php, and services.json.
Within your config/app.php configuration file, add Illuminate\Broadcasting\BroadcastServiceProvider to the providers array.
If you are using the provided AuthController which uses the AuthenticatesAndRegistersUsers trait, you will need to make a few changes to how new users are validated and created.
First, you no longer need to pass the Guard and Registrar instances to the base constructor. You can remove these dependencies entirely from your controller's constructor.
Secondly, the App\Services\Registrar class used in Laravel 5.0 is no longer needed. You can simply copy and paste your validator and create method from this class directly into your AuthController. No other changes should need to be made to these methods; however, you should be sure to import the Validator facade and your User model at the top of your AuthController.
The included PasswordController no longer requires any dependencies in its constructor. You may remove both of the dependencies that were required under 5.0.
If you are overriding the formatValidationErrors method on your base controller class, you should now type-hint the Illuminate\Contracts\Validation\Validator contract instead of the concrete Illuminate\Validation\Validator instance.
Likewise, if you are overriding the formatErrors method on the base form request class, you should now type-hint Illuminate\Contracts\Validation\Validator contract instead of the concrete Illuminate\Validation\Validator instance.
Eloquent's create method can now be called without any parameters. If you are overriding the create method in your own models, set the default value of the $attributes parameter to an array:
public static function create(array $attributes = [])
{
// Your custom implementation
}
If you are overriding the find method in your own models and calling parent::find() within your custom method, you should now change it to call the find method on the Eloquent query builder:
public static function find($id, $columns = ['*'])
{
$model = static::query()->find($id, $columns);
// ...
return $model;
}
The lists method now returns a Collection instance instead of a plain array for Eloquent queries. If you would like to convert the Collection into a plain array, use the all method:
User::lists('id')->all();
Be aware that the Query Builder lists method still returns an array.
Previously, the storage format for Eloquent date fields could be modified by overriding the getDateFormat method on your model. This is still possible; however, for convenience you may simply specify a $dateFormat property on the model instead of overriding the method.
The date format is also now applied when serializing a model to an array or JSON. This may change the format of your JSON serialized date fields when migrating from Laravel 5.0 to 5.1. To set a specific date format for serialized models, you may override the serializeDate(DateTime $date) method on your model. This method allows you to have granular control over the formatting of serialized Eloquent date fields without changing their storage format.
The sortBy method now returns a fresh collection instance instead of modifying the existing collection:
$collection = $collection->sortBy('name');
The groupBy method now returns Collection instances for each item in the parent Collection. If you would like to convert all of the items back to plain arrays, you may map over them:
$collection->groupBy('type')->map(function($item)
{
return $item->all();
});
The lists method now returns a Collection instance instead of a plain array. If you would like to convert the Collection into a plain array, use the all method:
$collection->lists('id')->all();
The app/Commands directory has been renamed to app/Jobs. However, you are not required to move all of your commands to the new location, and you may continue using the make:command and handler:command Artisan commands to generate your classes.
Likewise, the app/Handlers directory has been renamed to app/Listeners and now only contains event listeners. However, you are not required to move or rename your existing command and event handlers, and you may continue to use the handler:event command to generate event handlers.
By providing backwards compatibility for the Laravel 5.0 folder structure, you may upgrade your applications to Laravel 5.1 and slowly upgrade your events and commands to their new locations when it is convenient for you or your team.
The createMatcher, createOpenMatcher, and createPlainMatcher methods have been removed from the Blade compiler. Use the new directive method to create custom directives for Blade in Laravel 5.1. Consult the extending blade documentation for more information.
Add the protected $baseUrl property to the tests/TestCase.php file:
protected $baseUrl = 'http://localhost';
The default directory for published language files for vendor packages has been moved. Move any vendor package language files from resources/lang/packages/{locale}/{namespace} to resources/lang/vendor/{namespace}/{locale} directory. For example, Acme/Anvil package's acme/anvil::foo namespaced English language file would be moved from resources/lang/packages/en/acme/anvil/foo.php to resources/lang/vendor/acme/anvil/en/foo.php.
If you are using the AWS SQS queue driver or the AWS SES e-mail driver, you should update your installed AWS PHP SDK to version 3.0.
If you are using the Amazon S3 filesystem driver, you will need to update the corresponding Flysystem package via Composer:
- Amazon S3:
league/flysystem-aws-s3-v3 ~1.0
The following Laravel features have been deprecated and will be removed entirely with the release of Laravel 5.2 in December 2015:
In your bootstrap/autoload.php file, update the $compiledPath variable to:
$compiledPath = __DIR__.'/../vendor/compiled.php';
The recommended method of upgrading is to create a new Laravel 5.0 install and then to copy your 4.2 site's unique application files into the new application. This would include controllers, routes, Eloquent models, Artisan commands, assets, and other code specific files to your application.
To start, install a new Laravel 5.0 application into a fresh directory in your local environment. Do not install any versions newer than 5.0 yet, since we need to complete the migration steps for 5.0 first. We'll discuss each piece of the migration process in further detail below.
Don't forget to copy any additional Composer dependencies into your 5.0 application. This includes third-party code such as SDKs.
Some Laravel-specific packages may not be compatible with Laravel 5 on initial release. Check with your package's maintainer to determine the proper version of the package for Laravel 5. Once you have added any additional Composer dependencies your application needs, run composer update.
By default, Laravel 4 applications did not utilize namespacing within your application code. So, for example, all Eloquent models and controllers simply lived in the "global" namespace. For a quicker migration, you can simply leave these classes in the global namespace in Laravel 5 as well.
Copy the new .env.example file to .env, which is the 5.0 equivalent of the old .env.php file. Set any appropriate values there, like your APP_ENV and APP_KEY (your encryption key), your database credentials, and your cache and session drivers.
Additionally, copy any custom values you had in your old .env.php file and place them in both .env (the real value for your local environment) and .env.example (a sample instructional value for other team members).
For more information on environment configuration, view the full documentation.
Note: You will need to place the appropriate
.envfile and values on your production server before deploying your Laravel 5 application.
Laravel 5.0 no longer uses app/config/{environmentName}/ directories to provide specific configuration files for a given environment. Instead, move any configuration values that vary by environment into .env, and then access them in your configuration files using env('key', 'default value'). You will see examples of this in the config/database.php configuration file.
Set the config files in the config/ directory to represent either the values that are consistent across all of your environments, or set them to use env() to load values that vary by environment.
Remember, if you add more keys to .env file, add sample values to the .env.example file as well. This will help your other team members create their own .env files.
Copy and paste your old routes.php file into your new app/Http/routes.php.
Next, move all of your controllers into the app/Http/Controllers directory. Since we are not going to migrate to full namespacing in this guide, add the app/Http/Controllers directory to the classmap directive of your composer.json file. Next, you can remove the namespace from the abstract app/Http/Controllers/Controller.php base class. Verify that your migrated controllers are extending this base class.
In your app/Providers/RouteServiceProvider.php file, set the namespace property to null.
Copy your filter bindings from app/filters.php and place them into the boot() method of app/Providers/RouteServiceProvider.php. Add use Illuminate\Support\Facades\Route; in the app/Providers/RouteServiceProvider.php in order to continue using the Route Facade.
You do not need to move over any of the default Laravel 4.0 filters such as auth and csrf; they're all here, but as middleware. Edit any routes or controllers that reference the old default filters (e.g. ['before' => 'auth']) and change them to reference the new middleware (e.g. ['middleware' => 'auth'].)
Filters are not removed in Laravel 5. You can still bind and use your own custom filters using before and after.
By default, CSRF protection is enabled on all routes. If you'd like to disable this, or only manually enable it on certain routes, remove this line from App\Http\Kernel's middleware array:
'App\Http\Middleware\VerifyCsrfToken',
If you want to use it elsewhere, add this line to $routeMiddleware:
'csrf' => 'App\Http\Middleware\VerifyCsrfToken',
Now you can add the middleware to individual routes / controllers using ['middleware' => 'csrf'] on the route. For more information on middleware, consult the full documentation.
Feel free to create a new app/Models directory to house your Eloquent models. Again, add this directory to the classmap directive of your composer.json file.
Update any models using SoftDeletingTrait to use Illuminate\Database\Eloquent\SoftDeletes.
Eloquent no longer provides the remember method for caching queries. You now are responsible for caching your queries manually using the Cache::remember function. For more information on caching, consult the full documentation.
To upgrade your User model for Laravel 5's authentication system, follow these instructions:
Delete the following from your use block:
use Illuminate\Auth\UserInterface;
use Illuminate\Auth\Reminders\RemindableInterface;Add the following to your use block:
use Illuminate\Auth\Authenticatable;
use Illuminate\Auth\Passwords\CanResetPassword;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;Remove the UserInterface and RemindableInterface interfaces.
Mark the class as implementing the following interfaces:
implements AuthenticatableContract, CanResetPasswordContractInclude the following traits within the class declaration:
use Authenticatable, CanResetPassword;If you used them, remove Illuminate\Auth\Reminders\RemindableTrait and Illuminate\Auth\UserTrait from your use block and your class declaration.
The name of the trait and interface used by Laravel Cashier has changed. Instead of using BillableTrait, use the Laravel\Cashier\Billable trait. And, instead of Laravel\Cashier\BillableInterface implement the Laravel\Cashier\Contracts\Billable interface instead. No other method changes are required.
Move all of your command classes from your old app/commands directory to the new app/Console/Commands directory. Next, add the app/Console/Commands directory to the classmap directive of your composer.json file.
Then, copy your list of Artisan commands from start/artisan.php into the command array of the app/Console/Kernel.php file.
Delete the two migrations included with Laravel 5.0, since you should already have the users table in your database.
Move all of your migration classes from the old app/database/migrations directory to the new database/migrations. All of your seeds should be moved from app/database/seeds to database/seeds.
If you have any service container bindings in start/global.php, move them all to the register method of the app/Providers/AppServiceProvider.php file. You may need to import the App facade.
Optionally, you may break these bindings up into separate service providers by category.
Move your views from app/views to the new resources/views directory.
For better security by default, Laravel 5.0 escapes all output from both the {{ }} and {{{ }}} Blade directives. A new {!! !!} directive has been introduced to display raw, unescaped output. The most secure option when upgrading your application is to only use the new {!! !!} directive when you are certain that it is safe to display raw output.
However, if you must use the old Blade syntax, add the following lines at the bottom of AppServiceProvider@register:
\Blade::setRawTags('{{', '}}');
\Blade::setContentTags('{{{', '}}}');
\Blade::setEscapedContentTags('{{{', '}}}');This should not be done lightly, and may make your application more vulnerable to XSS exploits. Also, comments with {{-- will no longer work.
Move your language files from app/lang to the new resources/lang directory.
Copy your application's public assets from your 4.2 application's public directory to your new application's public directory. Be sure to keep the 5.0 version of index.php.
Move your tests from app/tests to the new tests directory.
Copy in any other files in your project. For example, .scrutinizer.yml, bower.json and other similar tooling configuration files.
You may move your Sass, Less, or CoffeeScript to any location you wish. The resources/assets directory could be a good default location.
If you're using Form or HTML helpers, you will see an error stating class 'Form' not found or class 'Html' not found. The Form and HTML helpers have been deprecated in Laravel 5.0; however, there are community-driven replacements such as those maintained by the Laravel Collective.
For example, you may add "laravelcollective/html": "~5.0" to your composer.json file's require section.
You'll also need to add the Form and HTML facades and service provider. Edit config/app.php and add this line to the 'providers' array:
'Collective\Html\HtmlServiceProvider',
Next, add these lines to the 'aliases' array:
'Form' => 'Collective\Html\FormFacade',
'Html' => 'Collective\Html\HtmlFacade',
If your application code was injecting Illuminate\Cache\CacheManager to get a non-Facade version of Laravel's cache, inject Illuminate\Contracts\Cache\Repository instead.
Replace any calls to $paginator->links() with $paginator->render().
Replace any calls to $paginator->getFrom() and $paginator->getTo() with $paginator->firstItem() and $paginator->lastItem() respectively.
Remove the "get" prefix from calls to $paginator->getPerPage(), $paginator->getCurrentPage(), $paginator->getLastPage() and $paginator->getTotal() (e.g. $paginator->perPage()).
Laravel 5.0 now requires "pda/pheanstalk": "~3.0" instead of "pda/pheanstalk": "~2.1".
The Remote component has been deprecated.
The Workbench component has been deprecated.
Laravel 4.2 requires PHP 5.4.0 or greater.
Add a new cipher option in your app/config/app.php configuration file. The value of this option should be MCRYPT_RIJNDAEL_256.
'cipher' => MCRYPT_RIJNDAEL_256
This setting may be used to control the default cipher used by the Laravel encryption facilities.
Note: In Laravel 4.2, the default cipher is
MCRYPT_RIJNDAEL_128(AES), which is considered to be the most secure cipher. Changing the cipher back toMCRYPT_RIJNDAEL_256is required to decrypt cookies/values that were encrypted in Laravel <= 4.1
If you are using soft deleting models, the softDeletes property has been removed. You must now use the SoftDeletingTrait like so:
use Illuminate\Database\Eloquent\SoftDeletingTrait;
class User extends Eloquent
{
use SoftDeletingTrait;
}
You must also manually add the deleted_at column to your dates property:
class User extends Eloquent
{
use SoftDeletingTrait;
protected $dates = ['deleted_at'];
}
The API for all soft delete operations remains the same.
Note: The
SoftDeletingTraitcan not be applied on a base model. It must be used on an actual model class.
If you are directly referencing the Illuminate\View\Environment class or Illuminate\Pagination\Environment class, update your code to reference Illuminate\View\Factory and Illuminate\Pagination\Factory instead. These two classes have been renamed to better reflect their function.
If you are extending the Illuminate\Pagination\Presenter class, the abstract method getPageLinkWrapper signature has changed to add the rel argument:
abstract public function getPageLinkWrapper($url, $page, $rel = null);
If you are using the Iron.io queue driver, you will need to add a new encrypt option to your queue configuration file:
'encrypt' => true
Laravel 4.1.29 improves the column quoting for all database drivers. This protects your application from some mass assignment vulnerabilities when not using the fillable property on models. If you are using the fillable property on your models to protect against mass assignment, your application is not vulnerable. However, if you are using guarded and are passing a user controlled array into an "update" or "save" type function, you should upgrade to 4.1.29 immediately as your application may be at risk of mass assignment.
To upgrade to Laravel 4.1.29, simply composer update. No breaking changes are introduced in this release.
Laravel 4.1.26 introduces security improvements for "remember me" cookies. Before this update, if a remember cookie was hijacked by another malicious user, the cookie would remain valid for a long period of time, even after the true owner of the account reset their password, logged out, etc.
This change requires the addition of a new remember_token column to your users (or equivalent) database table. After this change, a fresh token will be assigned to the user each time they login to your application. The token will also be refreshed when the user logs out of the application. The implications of this change are: if a "remember me" cookie is hijacked, simply logging out of the application will invalidate the cookie.
First, add a new, nullable remember_token of VARCHAR(100), TEXT, or equivalent to your users table.
Next, if you are using the Eloquent authentication driver, update your User class with the following three methods:
public function getRememberToken()
{
return $this->remember_token;
}
public function setRememberToken($value)
{
$this->remember_token = $value;
}
public function getRememberTokenName()
{
return 'remember_token';
}
Note: All existing "remember me" sessions will be invalidated by this change, so all users will be forced to re-authenticate with your application.
Two new methods were added to the Illuminate\Auth\UserProviderInterface interface. Sample implementations may be found in the default drivers:
public function retrieveByToken($identifier, $token);
public function updateRememberToken(UserInterface $user, $token);
The Illuminate\Auth\UserInterface also received the three new methods described in the "Upgrade Path".
To upgrade your application to Laravel 4.1, change your laravel/framework version to 4.1.* in your composer.json file.
Replace your public/index.php file with this fresh copy from the repository.
Replace your artisan file with this fresh copy from the repository.
Update your aliases and providers arrays in your app/config/app.php configuration file. The updated values for these arrays can be found in this file. Be sure to add your custom and package service providers / aliases back to the arrays.
Add the new app/config/remote.php file from the repository.
Add the new expire_on_close configuration option to your app/config/session.php file. The default value should be false.
Add the new failed configuration section to your app/config/queue.php file. Here are the default values for the section:
'failed' => [
'database' => 'mysql', 'table' => 'failed_jobs',
],
(Optional) Update the pagination configuration option in your app/config/view.php file to pagination::slider-3.
If app/controllers/BaseController.php has a use statement at the top, change use Illuminate\Routing\Controllers\Controller; to use Illuminate\Routing\Controller;.
Password reminders have been overhauled for greater flexibility. You may examine the new stub controller by running the php artisan auth:reminders-controller Artisan command. You may also browse the updated documentation and update your application accordingly.
Update your app/lang/en/reminders.php language file to match this updated file.
For security reasons, URL domains may no longer be used to detect your application environment. These values are easily spoofable and allow attackers to modify the environment for a request. You should convert your environment detection to use machine host names (hostname command on Mac, Linux, and Windows).
Laravel now generates a single log file: app/storage/logs/laravel.log. However, you may still configure this behavior in your app/start/global.php file.
In your bootstrap/start.php file, remove the call to $app->redirectIfTrailingSlash(). This method is no longer needed as this functionality is now handled by the .htaccess file included with the framework.
Next, replace your Apache .htaccess file with this new one that handles trailing slashes.
The current route is now accessed via Route::current() instead of Route::getCurrentRoute().
Once you have completed the changes above, you can run the composer update function to update your core application files! If you receive class load errors, try running the update command with the --no-scripts option enabled like so: composer update --no-scripts.
The wildcard event listeners no longer append the event to your handler functions parameters. If you require finding the event that was fired you should use Event::firing().