{note}我们尽量记录每一个可能的破坏性变化。但因为其中一些不兼容变更只存在于框架很不起眼的地方,事实上只有一小部分可能会影响到你的应用程序。
在 composer.json
文件中将 laravel/framework
更新为 5.5.*
。 此外,你还应该将 phpunit/phpunit
依赖关系更新到 ~6.0
。
{tip} 如果你是通过使用
laravel new
来安装 Laravel 程序,则应该使用命令composer global update
来更新 Laravel 安装程序包。
Laravel Dusk 2.0.0
已经发布,该版本同时兼容 Laravel 5.5 和 Chrome 的 headless 模式测试。
Pusher 事件广播驱动现在需要 ~3.0
版本的 Pusher SDK。
fire
方法该方法已重命名为 handle
方法。
optimize
命令随着对 PHP 操作码缓存的最新改进,不再需要优化 Artisan 命令。你应该从部署脚本中删除对此命令的任何引用,因为它在未来的 Laravel 版本中会被删除。
authorizeResouce
控制器方法当将一个大驼峰命名的模型名称传递给 authorizeResource
方法时,为了和资源控制器的行为相匹配,生成的路由会用蛇形命名法来命名。
before
策略方法如果类中不包含与给定名称相匹配的方法,则不会调用策略类的 before
方法。
如果你正在使用数据库缓存驱动,那在你第一次部署升级至 Laravel 5.5时,应该先运行 php artisan cache:clear
命令。
belongsToMany
方法如果你在 Eloquent 模型中重写了 belongsToMany
方法,应该更新方法签名来映射新增的参数:
/**
* 定义多对多关系。
*
* @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
的类型提示。这将允许 is
方法接受 null
作为参数。
/**
* 确定两个模型是否具有相同的ID并且属于同一个表。
*
* @param \Illuminate\Database\Eloquent\Model|null $model
* @return bool
*/
public function is($model)
{
//
}
$events
属性模型上的 $events
属性应该重命名为 $dispatchesEvents
。由于大量用户需要定义事件关系,导致与旧属性名称的冲突,因此进行了更改。
$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 中,别名将严格按照给定的方式使用。如果要将 _count
追加到结果列,则必须在定义别名时指定该后缀:
$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;
/**
* 将验证异常转换成 JSON 响应
*
* @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 进行的身份验证尝试的验证错误返回的格式。在 Laravel 5.5 中,身份验证失败的 JSON 将按照上述新的格式约定返回错误消息。
现在自定义了单个表单请求的响应格式,应重写该表单请求的 failedValidation
方法 ,并抛出一个包含自定义响应的 HttpResponseException
实例。
use Illuminate\Http\Exceptions\HttpResponseException;
/**
* 处理失败的验证尝试。
*
* @param \Illuminate\Contracts\Validation\Validator $validator
* @return void
*
* @throws \Illuminate\Validation\ValidationException
*/
protected function failedValidation(Validator $validator)
{
throw new HttpResponseException(response()->json(..., 422));
}
files
方法files
方法与 allFiles
方法类似,会返回一个 SqlFileInfo
对象的数组。之前的 files
方法会返回一个字符串路径名的数组。
未使用的 $data
和 $callback
参数已从 Illuminate\Contracts\Mail\MailQueue
契约的 queue
和 later
方法中删除
/**
* 在队列中发送新的电子邮件
*
* @param string|array|MailableContract $view
* @param string $queue
* @return mixed
*/
public function queue($view, $queue = null);
/**
* n 秒后在队列中发送新的电子邮件
*
* @param \DateTimeInterface|\DateInterval|int $delay
* @param string|array|MailableContract $view
* @param string $queue
* @return mixed
*/
public function later($delay, $view, $queue = null);
has
方法$request->has
方法现在对于空字符串和 null
将返回 true
。新添加的 $request->filled
方法提供了之前的 has
方法的行为。
intersect
方法intersect
方法已被移除。你只需在调用 $request->only
时使用 array_filter
来代替该方法:
return array_filter($request->only('foo'));
only
方法only
方法现在只会返回请求中实际存在的属性。如果你想保留该方法的旧功能,可以使用 all
方法来替代。
return $request->all('foo');
request()
辅助函数 request
将不再检索嵌套的键。如果有需要,你可以使用 request
中的 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
。
所有的验证器的验证方法已由 protected
改为 public
。
当允许动态的 __call
方法与视图共享变量时,该变量将会自动使用驼峰式命名。举例如下:
return view('pool')->withMaximumVotes(100);
maximumVotes
变量可以在模板中访问,如下所示:
{{ $maximumVotes }}
你还可以查看 laravel/laravel
在 GitHub 中的更改。虽然这些更改不是必需的,但你可能希望将这些文件与应用程序保持同步。本升级指南中将介绍其中一些更改,而其他的则不会被介绍,例如更改配置文件或注释。你可以使用 GitHub 的比较工具 轻松查看你在意的变更的内容。