升级指南 · Laravel 5.2中文

[TOC] ### **从 5.1 [升级](http://laravelacademy.org/tags/%e5%8d%87%e7%ba%a7 "View all posts in 升级")到 [5.2](http://laravelacademy.org/tags/5-2 "View all posts in 5.2").0** #### **更新依赖** 更新 `composer.json` 文件指向 `laravel/framework 5.2.*`。 > 注：如果你安装的是 [Laravel](http://laravelacademy.org/tags/laravel "View all posts in 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](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` 数组中配置该提供者。更多自定义认证提供者详情，请查看其对应[文档](http://laravel.com/docs/5.2/authentication)。 #### **授权** `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](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](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` 即可。