[ Laravel 5.5 文档 ] 序言 —— 升级指南

注：从 Laravel 5.4 升级到 Laravel 5.5 预计时间 1 小时左右。

更新依赖

更新 composer.json 文件中的 laravel/framework 依赖版本为 5.5.*。此外，你还需要更新 phpunit/phpunit 依赖版本到 ~6.0。

注：如果你通常通过 laravel new 使用 Laravel 安装器，还需要使用 composer global update 命令更新 Laravel 安装器。

Laravel Dusk

Laravel Dusk 2.0.0 已经发布以兼容 Laravel 5.5。

Pusher

Pusher 事件广播驱动现在需要 ~3.0 版本的 Pusher SDK。

Artisan

fire 方法

Artisan 命令中的所有 fire 需要被重命名为 handle。

optimize 命令

随着近期 PHP opcode 缓存的优化，optimize 命令不再需要，你应该从部署脚本中移除对该命令的引用，因为在以后的版本中将不再提供该命令。

授权

authorizeResource 控制器方法

当传递一个包含多个单词的模型名到 authorizeResource 方法时，结果路由片段将会是短划线风格（snake），以匹配资源控制器的行为。比如模型名是 UserPost，则对应结果路由片段是 user_post。

before 策略方法

如果策略类不包含一个与检查权限名相匹配的方法名，则该策略类的 before 方法将不会被调用。

缓存

数据库驱动

如果你的应用中使用了数据库缓存驱动，则需要在第一次部署升级后的 Laravel 5.5 版本应用时运行 php artisan cache:clear。

Eloquent

belongsToMany 方法

如果你在 Eloquent 模型中重写了 belongsToMany 方法，则需要修改方法签名来反映新增的参数：

/**
 * Define a many-to-many relationship.
 *
 * @param  string  $related
 * @param  string  $table
 * @param  string  $foreignPivotKey
 * @param  string  $relatedPivotKey
 * @param  string  $parentKey
 * @param  string  $relatedKey
 * @param  string  $relation
 * @return \Illuminate\Database\Eloquent\Relations\BelongsToMany
 */
public function belongsToMany($related, $table = null, $foreignPivotKey = null,
                              $relatedPivotKey = null, $parentKey = null,
                              $relatedKey = null, $relation = null)
{
    //
}

模型 is 方法

如果你重写了 Eloquent 模型的 is 方法，需要从该方法中移除 Model 类型提示，因为该方法可以接收 null 作为参数了：

/**
 * Determine if two models have the same ID and belong to the same table.
 *
 * @param  \Illuminate\Database\Eloquent\Model|null  $model
 * @return bool
 */
public function is($model)
{
    //
}

模型 $events 属性

模型中的 $events 属性需要被重命名为 $dispatchesEvents，做出这一改变的原因是很多用户需要定义 $events 关联关系，这样就会和原来的属性名冲突。

Pivot $parent 属性

Illuminate\Database\Eloquent\Relations\Pivot 中的受保护属性 $parent 被重命名为 $pivotParent。

关联关系的 create 方法

BelongsToMany、HasOneOrMany 和 MorphOneOrMany 的 create 方法都已经被调整成为 $attributes 参数提供一个默认值，如果你重写了这些方法，需要更新方法签名以匹配这个新定义：

public function create(array $attributes = [])
{
    //
}

软删除的模型

当删除一个被"软删除"的模型时，模型上的 exists 属性会返回 true。

withCount 字段格式

使用别名时，withCount 方法不再自动追加 _count 到结果字段名，例如，在 Laravel 5.4 中，下面的查询将会添加一个 bar_count 字段到查询结果：

$users = User::withCount('foo as bar')->get();

不过，在 Laravel 5.5 中，这个别名将直接使用给定的别名，如果你想要追加 _append 到结果字段，必须在定义别名时进行指定：

$users = User::withCount('foo as bar_count')->get();

异常格式

在 Laravel 5.5 中，所有异常，包括验证异常，都会通过异常处理器被转化为 HTTP 响应。此外，验证错误的默认 JSON 格式也被调整了，新的格式遵循以下约定：

{
    "message": "The given data was invalid.",
    "errors": {
        "field-1": [
            "Error 1",
            "Error 2"
        ],
        "field-2": [
            "Error 1",
            "Error 2"
        ],
    }
}

不过，如果你想要维持 Laravel 5.4 中的 JSON 错误格式，可以添加以下方法到 App\Exceptions\Handler 类：

use Illuminate\Validation\ValidationException;

/**
 * Convert a validation exception into a JSON response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Illuminate\Validation\ValidationException  $exception
 * @return \Illuminate\Http\JsonResponse
 */
protected function invalidJson($request, ValidationException $exception)
{
    return response()->json($exception->errors(), $exception->status);
}

JSON 登录尝试

这一改变也会影响验证错误格式，针对的是登录尝试返回的 JSON 格式，在 Laravel 5.5 中，登录失败返回的 JSON 错误消息遵循上面描述的新的格式约定。

表单请求注意点

如果你为独立表单请求自定义了响应格式，需要重写那个表单请求中的 failedValidation 方法，并抛出包含自定义响应的 HttpResponseException 实例：

use Illuminate\Http\Exceptions\HttpResponseException;

/**
 * Handle a failed validation attempt.
 *
 * @param  \Illuminate\Contracts\Validation\Validator  $validator
 * @return void
 *
 * @throws \Illuminate\Validation\ValidationException
 */
protected function failedValidation(Validator $validator)
{
    throw new HttpResponseException(response()->json(..., 422));
}

文件系统

files 方法

Illuminate\Filesystem\Filesystem 类的 files 方法将其方法签名修改为新增了一个 $hidden 参数并返回 SplFileInfo 对象数组，和 allFiles 方法类似。在之前的版本中，files 方法返回一个字符串路径名称数组，新的方法签名如下：

public function files($directory, $hidden = false)

邮件

未使用的参数

未使用的 $data 和 $callback 参数已经从 Illuminate\Contracts\Mail\MailQueue 契约的 queue 和 later 方法中移除：

/**
 * Queue a new e-mail message for sending.
 *
 * @param  string|array|MailableContract  $view
 * @param  string  $queue
 * @return mixed
 */
public function queue($view, $queue = null);

/**
 * Queue a new e-mail message for sending after (n) seconds.
 *
 * @param  \DateTimeInterface|\DateInterval|int  $delay
 * @param  string|array|MailableContract  $view
 * @param  string  $queue
 * @return mixed
 */
public function later($delay, $view, $queue = null);

请求

all 方法

如果你重写了 Illuminate\Http\Request 类的 all 方法，需要修改该方法签名以体现新增的 $keys 参数：

/**
 * Get all of the input and files for the request.
 *
 * @param  array|mixed  $keys
 * @return array
 */
public function all($keys = null)
{
    //
}

has 方法

$request->has 方法现在返回 true，即使输入值是空字符串或 null，一个新的 $request->filled 方法被添加来替代之前 has 方法提供的功能。

intersect 方法

intersect 方法已经被移除，你可以通过在 $request->only 上调用 array_filter 方法来完成相同的功能：

return array_filter($request->only('foo'));

only 方法

only 方法现在只返回请求负载中出现的属性，如果你想要维持之前的 only 方法功能，可以使用 all 方法来替代：

return $request->all('foo');

request() 辅助函数

request 辅助函数不再接收嵌套 keys，如果需要的话，你可以使用使用请求的 input 方法来完成这一功能：

return request()->input('filters.date');

测试

认证断言

对一些认证断言进行了重命名以便和框架其他断言在命名上保持更好的一致性：

• seeIsAuthenticated 被重命名为 assertAuthenticated

• dontSeeIsAuthenticated 被重命名为 assertGuest

• seeIsAuthenticatedAs 被重命名为 assertAuthenticatedAs

• seeCredentials 被重命名为 assertCredentials

• dontSeeCredentials 被重命名为 assertInvalidCredentials

邮件伪造

如果你在使用 Mail 伪造来判定一个邮件对象在请求阶段是否被推送到队列，现在需要使用 Mail::assertQueued 来替代 Mail::assertSent。这一区分的差别在于你可以明确断言该邮件被推送到队列通过后台任务发送而不是在请求过程中被发送。

翻译

LoaderInterface

Illuminate\Translation\LoaderInterface 接口被移动到 Illuminate\Contracts\Translation\Loader 下。

验证

验证器方法

所有验证器方法现在修饰符都是 public 而不是 protected。

视图

动态变量名

当我们允许动态 __call 方法通过视图共享变量时，这些变量自动使用驼峰风格，例如：

return view('pool')->withMaximumVotes(100);

maximumVotes 变量可以在模板中通过如下方式访问：

{{ $maximumVotes }}

其他

我们还鼓励你在 laravel/laravel Github 仓库中去浏览这些调整和修改，尽管很多修改是不需要的，你可能希望在应用中保持这些文件的同步。有些文件会在这次升级中被覆盖，但是其它文件，例如配置文件或注释的调整，则不会，你可以轻松通过 Github 比较工具 查看这些变更然后选择那些对你来说比较重要的更新。