升级指南 - Laravel 5.2 序言 - [ Laravel 5.2 ]

从 5.1 升级到 5.2.0

更新依赖

更新 composer.json 文件指向 laravel/framework 5.2.*。

注：如果你安装的是 Laravel 5.2 的 beta 版本，还要添加 "minimum-stability": "beta" 到 composer.json 文件。

添加 symfony/dom-crawler ~3.0 和 symfony/css-selector ~3.0 到 composer.json 的 require-dev 部分。

认证

配置文件

更新 config/auth.php 文件内容如下：

https://github.com/laravel/laravel/blob/develop/config/auth.php

更新完成后，基于原来的配置设置认证选项，如果不做改动，认证服务将基于 Laravel 5.1。

在新的 auth.php 配置文件中，要特别注意 passwords.users.email 配置项，由于在 Laravel 5.2 对 email 视图路径有所改动，因此要确保该视图路径与应用实际的路径相匹配，如果不匹配的话要更新该配置值。

Contracts

如果你实现了 Illuminate\Contracts\Auth\Authenticatable 契约但没有使用 Authenticatable trait，那么需要添加一个新的 getAuthIdentifierName 方法到该契约实现类。通常，该方法返回认证实体的主键字段名，如：id。

这对你的应用没有什么影响，除非你手动实现了 Illuminate\Contracts\Auth\Authenticatable。

自定义驱动

如果你使用了 Auth::extend 方法自定义获取用户的方法，现在需要使用 Auth::provider 来自定义用户提供者。一旦你自定义了提供者，就要在新的 auth.php 配置文件中的 providers 数组中配置该提供者。

更多自定义认证提供者详情，请查看其对应文档。

授权

Illuminate\Auth\Access\UnauthorizedException 被重命名为 Illuminate\Auth\Access\AuthorizationException。如果你没有手动捕获该异常那么这一改变对之前代码没有什么影响。

集合

Eloquent集合基类

调用 Eloquent 集合实例的 pluck, keys, zip, collapse, flatten, flip 方法现在会返回集合基类。

保留键名

slice、chunk 和 reverse 方法现在会保留集合的键名，如果你不想这些方法保留键名，使用集合实例的 values 方法即可。

Composer类

Illuminate\Foundation\Support\Composer 类现在被移动到 Illuminate\Support\Composer，如果你没有在代码中使用该类那么这一改变对程序没有影响。

命令和处理器

自处理命令

在创建任务/命令时你不再需要实现 SelfHandling 契约，所有任务现在默认都是自处理的，因此你可以在自己的类中移除该接口。

独立的命令&处理器

Laravel 5.2 命令现在只支持自处理命令，不再支持独立的命令和处理器。

如果你想要继续使用独立的命令和处理器，可以安装提供向后兼容支持的 Laravel Collective 包：https://github.com/LaravelCollective/bus

配置

开发环境

添加一个 env 配置项到配置文件 app.php 中：

'env' => env('APP_ENV', 'production'),

缓存和环境

如果你在开发过程中使用 config:cache 命令，必须保证只是在配置文件中调用了 env 函数，而不是在应用程序的其它地方。

如果你在应用程序中调用了 env 函数，强烈建议添加适当的配置值到配置文件，然后在该位置调用 env，从而允许你将 env 调用改为 config 调用。

CSRF验证

在单元测试中不再支持自动进行 CSRF 验证，当然这一改变对你的应用程序代码没什么影响。

Elixir

PHP 的 elixir 方法现在返回一个完整 URL 而不是相对 URL，这对应用程序没有什么影响，除非你曾经手动将这些 URL 转化成完整 URL。

Eloquent

日期转化

当调用模型或模型集合的 toArray 方法时，任何添加到 $casts 的属性，如 date 或 datetime，现在都会被转化为字符串。这使得在 $dates 数组中制定的日期转化变得简单方便。

全局作用域

我们重写了全局作用域的实现以便于使用，全局作用域不再需要 remove 方法，因此可以在所有你使用到该方法的地方将其移除。

如果你曾经在 Eloquent 查询构建器上调用过了 getQuery 方法以获取底层查询构建器实例，现在应该改为调用 toBase 方法。

如果你因为某种原因直接调用了 remove 方法，需要将其改成 $eloquentBuilder->withoutGlobalScope($scope) 这种方式来调用。

在 Eloquent 查询构建器中新增了 withoutGlobalScope 和 withoutGlobalScopes 方法，任何调用 $model->removeGlobalScopes($builder) 的地方现在都要改成 $builder->withoutGlobalScopes()。

事件

核心事件对象

Laravel 的一些核心事件触发现在使用事件对象取代之前的事件名称以及动态参数，下面是原来的事件名称与现在的事件对象对应关系：

Old	New
`auth.attempting`	`Illuminate\Auth\Events\Attempting`
`auth.login`	`Illuminate\Auth\Events\Login`
`auth.logout`	`Illuminate\Auth\Events\Logout`
`cache.missed`	`Illuminate\Cache\Events\CacheMissed`
`cache.hit`	`Illuminate\Cache\Events\CacheHit`
`cache.write`	`Illuminate\Cache\Events\KeyWritten`
`cache.delete`	`Illuminate\Cache\Events\KeyForgotten`
`connection.{name}.beginTransaction`	`Illuminate\Database\Events\TransactionBeginning`
`connection.{name}.committed`	`Illuminate\Database\Events\TransactionCommitted`
`connection.{name}.rollingBack`	`Illuminate\Database\Events\TransactionRolledBack`
`illuminate.query`	`Illuminate\Database\Events\QueryExecuted`
`illuminate.queue.after`	`Illuminate\Queue\Events\JobProcessed`
`illuminate.queue.failed`	`Illuminate\Queue\Events\JobFailed`
`illuminate.queue.stopping`	`Illuminate\Queue\Events\WorkerStopping`
`mailer.sending`	`Illuminate\Mail\Events\MessageSending`
`router.matched`	`Illuminate\Routing\Events\RouteMatched`

这些事件对象传入参数和 Laravel 5.1 的事件处理器一样，例如，如果你在 Laravel 5.1 中使用了 DB:listen 事件，在 5.2 中更新代码如下：

DB::listen(function ($event) {
    dump($event->sql);
    dump($event->bindings);
});

你可以去检查每个事件对象类去查看它们的公有属性。

异常处理

App\Exceptions\Handler 类的 $dontReport 属性应该被更新为至少包含以下异常类型的其中一个：

use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Database\Eloquent\ModelNotFoundException;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Illuminate\Foundation\Validation\ValidationException;

/**
 * A list of the exception types that should not be reported.
 *
 * @var array
 */
protected $dontReport = [
    AuthorizationException::class,
    HttpException::class,
    ModelNotFoundException::class,
    ValidationException::class,
];

隐式模型绑定

Laravel 5.2 支持“隐式模型绑定”，以便在路由和控制器中基于 URI 标识符自动注入模型实例。然而，这也改变了路由和控制器中类型提示模型实例这一行为。

如果你之前在路由或控制器中类型提示了模型实例，并且希望注入一个空的模型实例，那么现在应该移除这个类型提示然后在路由或控制器中直接创建一个新的模型实例；否则，Laravel 将会基于路由 URI 的标识符试图从数据库获取一个已存在的模型实例。

IronMQ

IronMQ 队列驱动被移动到自己的扩展包中，不再被框架核心支持：http://github.com/LaravelCollective/iron-queue

任务/队列

php artisan make:job 命令现在默认会创建一个队列任务类，如果你想要创建一个同步任务（非队列），在使用该命令时加上 --sync 选项。

邮件

邮件配置中移除了 pretend 选项，取而代之的，使用 log 邮件驱动执行和 pretend 同样的功能，并且将邮件信息记录到日志中。

分页

为了与框架生成的其它 URL 保持一致，分页 URL 不再包含斜杠，这一改变对应用代码不产生任何影响。

服务提供者

Illuminate\Foundation\Providers\ArtisanServiceProvider 从配置文件 app.php 的服务提供者列表中移除。

Illuminate\Routing\ControllerServiceProvider 从配置文件 app.php 的服务提供者列表中移除。

Session

数据库Session驱动

我们为框架编写了新的 database Session 驱动，该驱动包含更多的用户信息，例如用户 ID、IP 地址以及用户代理，如果你想要继续使用之前的 database 驱动，需要在配置文件 session.php 中指定 legacy-database 驱动。

如果你想要使用新的驱动，还需要添加 user_id (nullable integer)、ip_address (nullable string) 以及 user_agent (text) 列到存放 Session 的数据表中。

Stringy

框架不再内置 Stringy 库，如果要在应用中使用，你需要通过 Composer 手动安装。

验证

ValidatesRequests trait 现在会抛出 Illuminate\Foundation\Validation\ValidationException 异常以取代之前的 Illuminate\Http\Exception\HttpResponseException。如果你没有手动捕获该异常，那么这对之前的代码没有影响。

废弃

下面这些功能在 Laravel 5.2 中被废弃，在 Laravel 5.3 中会被彻底移除：

Illuminate\Contracts\Bus\SelfHandling 契约
集合的 lists 方法被重命名为 pluck 方法。
隐式控制器路由 Route::controller 被废弃。在路由文件中请使用明确的路由注册。
Laravel 5.1 的 database Session驱动被重命名为 legacy-database。
Str::randomBytes 方法被废弃，直接使用 PHP 的 random_bytes 即可。
Str::equals 方法被废弃，直接使用 PHP 的 hash_equals 方法即可。
Illuminate\View\Expression 被废弃，使用 Illuminate\Support\HtmlString 即可。