Laravel 5.7 中文文档

简体中文

English

简体中文

English

主题

升级指南 ​

从 5.6 升级到 5.7.0 ​

预计升级时间：10 - 15 分钟 ​

exclamation

我们尝试记录每一个可能的重大变更。由于其中一些变更位于框架的偏僻部分，只有一部分变更可能会实际影响到您的应用程序。

更新依赖 ​

在您的 composer.json 文件中，将 laravel/framework 依赖更新为 5.7.*。

如果您使用 Laravel Passport，您应该在 composer.json 文件中将 laravel/passport 依赖更新为 ^7.0。

接下来，检查您的应用程序使用的任何第三方包，并验证您是否使用了支持 Laravel 5.7 的正确版本。

应用程序 ​

register 方法 ​

影响可能性：非常低

Illuminate\Foundation\Application 类的 register 方法中未使用的 options 参数已被移除。如果您重写了此方法，您应该更新方法的签名：

php
/**
 * 在应用程序中注册服务提供者。
 *
 * @param  \Illuminate\Support\ServiceProvider|string  $provider
 * @param  bool   $force
 * @return \Illuminate\Support\ServiceProvider
 */
public function register($provider, $force = false);

Artisan ​

调度作业连接和队列 ​

影响可能性：低

$schedule->job 方法现在会尊重作业类中的 queue 和 connection 属性，如果在 job 方法中没有显式传递连接/作业。

通常，这应该被视为一个错误修复；然而，出于谨慎考虑，它被列为一个重大变更。如果您遇到与此变更相关的问题，请告知我们。

资源 ​

资源目录扁平化 ​

影响可能性：无

对于新的 Laravel 5.7 应用程序，包含脚本和样式的资源目录已被扁平化到 resources 目录中。这不会影响现有应用程序，也不需要对现有应用程序进行更改。

然而，如果您希望进行此更改，您应该将所有文件从 resources/assets/* 目录上移一级：

  • 从 resources/assets/js/* 到 resources/js/*
  • 从 resources/assets/sass/* 到 resources/sass/*

然后，在您的 webpack.mix.js 文件中更新对旧目录的引用：

php
mix.js('resources/js/app.js', 'public/js')
   .sass('resources/sass/app.scss', 'public/css');

svg 目录添加 ​

影响可能性：非常高

在 public 目录中添加了一个新的 svg 目录。它包含四个 svg 文件：403.svg、404.svg、500.svg 和 503.svg，这些文件显示在各自的错误页面上。

您可以从 GitHub 获取这些文件。

认证 ​

Authenticate 中间件 ​

影响可能性：低

Illuminate\Auth\Middleware\Authenticate 中间件的 authenticate 方法已更新为接受传入的 $request 作为其第一个参数。如果您在自己的 Authenticate 中间件中重写了此方法，您应该更新中间件的方法签名：

php
/**
 * 确定用户是否登录到任何给定的守卫。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  array  $guards
 * @return void
 *
 * @throws \Illuminate\Auth\AuthenticationException
 */
protected function authenticate($request, array $guards)

ResetsPasswords Trait ​

影响可能性：低

ResetsPasswords trait 的受保护 sendResetResponse 方法现在接受传入的 Illuminate\Http\Request 作为其第一个参数。如果您重写了此方法，您应该更新方法的签名：

php
/**
 * 获取成功密码重置的响应。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  string  $response
 * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
 */
protected function sendResetResponse(Request $request, $response)

SendsPasswordResetEmails Trait ​

影响可能性：低

SendsPasswordResetEmails trait 的受保护 sendResetLinkResponse 方法现在接受传入的 Illuminate\Http\Request 作为其第一个参数。如果您重写了此方法，您应该更新方法的签名：

php
/**
 * 获取成功密码重置链接的响应。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  string  $response
 * @return \Illuminate\Http\RedirectResponse|\Illuminate\Http\JsonResponse
 */
protected function sendResetLinkResponse(Request $request, $response)

授权 ​

Gate 合约 ​

影响可能性：非常低

raw 方法的可见性从 protected 更改为 public。此外，它被添加到 Illuminate\Contracts\Auth\Access\Gate 合约中：

php
/**
 * 从授权回调中获取原始结果。
 *
 * @param  string  $ability
 * @param  array|mixed  $arguments
 * @return mixed
 */
public function raw($ability, $arguments = []);

如果您正在实现此接口，您应该将此方法添加到您的实现中。

Login 事件 ​

影响可能性：非常低

Illuminate\Auth\Events\Login 事件的 __construct 方法有一个新的 $guard 参数：

php
/**
 * 创建一个新的事件实例。
 *
 * @param  string  $guard
 * @param  \Illuminate\Contracts\Auth\Authenticatable  $user
 * @param  bool  $remember
 * @return void
 */
public function __construct($guard, $user, $remember)

如果您在应用程序中手动调度此事件，您需要将此新参数传递给事件的构造函数。以下示例将默认框架守卫传递给 Login 事件：

php
use Illuminate\Auth\Events\Login;

event(new Login(config('auth.defaults.guard'), $user, $remember))

Blade ​

or 操作符 ​

影响可能性：高

Blade 的 "or" 操作符已被移除，取而代之的是 PHP 内置的 ?? "null coalesce" 操作符，它具有相同的目的和功能：

php
// Laravel 5.6...
{{ $foo or 'default' }}

// Laravel 5.7...
{{ $foo ?? 'default' }}

缓存 ​

影响可能性：非常高

在 storage/framework/cache 中添加了一个新的 data 目录。您应该在自己的应用程序中创建此目录：

php
mkdir -p storage/framework/cache/data

然后，将一个 .gitignore 文件添加到新创建的 data 目录中：

php
cp storage/framework/cache/.gitignore storage/framework/cache/data/.gitignore

最后，确保 storage/framework/cache/.gitignore 文件更新如下：

php
*
!data/
!.gitignore

Carbon ​

影响可能性：非常低

Carbon "宏" 现在由 Carbon 库直接处理，而不是 Laravel 对库的扩展。我们不期望这会破坏您的代码；然而，如果您遇到与此变更相关的问题，请告知我们。

集合 ​

split 方法 ​

影响可能性：低

split 方法已更新为始终返回请求的 "组" 数量，除非原始集合中的项目总数少于请求的集合数。通常，这应该被视为一个错误修复；然而，出于谨慎考虑，它被列为一个重大变更。

Factory 合约方法签名 ​

影响可能性：非常低

Illuminate\Contracts\Cookie\Factory 接口的 make 和 forever 方法的签名已更改。如果您正在实现此接口，您应该在实现中更新这些方法。

数据库 ​

softDeletesTz 迁移方法 ​

影响可能性：低

架构表构建器的 softDeletesTz 方法现在接受列名作为其第一个参数，而 $precision 已移至第二个参数位置：

php
/**
 * 为表添加一个 "deleted at" timestampTz。
 *
 * @param  string  $column
 * @param  int  $precision
 * @return \Illuminate\Support\Fluent
 */
public function softDeletesTz($column = 'deleted_at', $precision = 0)

ConnectionInterface 合约 ​

影响可能性：非常低

Illuminate\Database\ConnectionInterface 合约的 select 和 selectOne 方法签名已更新以适应新的 $useReadPdo 参数：

php
/**
 * 运行一个选择语句并返回单个结果。
 *
 * @param  string  $query
 * @param  array   $bindings
 * @param  bool  $useReadPdo
 * @return mixed
 */
public function selectOne($query, $bindings = [], $useReadPdo = true);

/**
 * 在数据库上运行一个选择语句。
 *
 * @param  string  $query
 * @param  array   $bindings
 * @param  bool  $useReadPdo
 * @return array
 */
public function select($query, $bindings = [], $useReadPdo = true);

此外，cursor 方法已添加到合约中：

php
/**
 * 在数据库上运行一个选择语句并返回一个生成器。
 *
 * @param  string  $query
 * @param  array  $bindings
 * @param  bool  $useReadPdo
 * @return \Generator
 */
public function cursor($query, $bindings = [], $useReadPdo = true);

如果您正在实现此接口，您应该将此方法添加到您的实现中。

whereDate 方法 ​

影响可能性：低

查询构建器的 whereDate 方法现在将 DateTime 实例转换为 Y-m-d 格式：

php
// 之前的行为 - SELECT * FROM `table` WHERE `created_at` > '2018-08-01 13:00:00'
$query->whereDate('created_at', '>', Carbon::parse('2018-08-01 13:00:00'));

// 当前行为 - SELECT * FROM `table` WHERE `created_at` > '2018-08-01'
$query->whereDate('created_at', '>', Carbon::parse('2018-08-01 13:00:00'));

迁移命令输出 ​

影响可能性：非常低

核心迁移命令已更新以在迁移器类上设置输出实例。如果您重写或扩展了迁移命令，您应该删除对 $this->migrator->getNotes() 的引用，并使用 $this->migrator->setOutput($this->output)。

SQL Server 驱动优先级 ​

影响可能性：低

在 Laravel 5.7 之前，PDO_DBLIB 驱动被用作默认的 SQL Server PDO 驱动。此驱动被 Microsoft 视为已弃用。从 Laravel 5.7 开始，如果可用，将使用 PDO_SQLSRV 作为默认驱动。或者，您可以选择使用 PDO_ODBC 驱动：

php
'sqlsrv' => [
    // ...
    'odbc' => true,
    'odbc_datasource_name' => 'your-odbc-dsn',
],

如果这些驱动都不可用，Laravel 将使用 PDO_DBLIB 驱动。

SQLite 外键 ​

影响可能性：中等

SQLite 不支持删除外键。因此，在表上使用 dropForeign 方法现在会抛出异常。通常，这应该被视为一个错误修复；然而，出于谨慎考虑，它被列为一个重大变更。

如果您在多种类型的数据库上运行迁移，请考虑在迁移中使用 DB::getDriverName() 来跳过 SQLite 不支持的外键方法。

调试 ​

Dumper 类 ​

影响可能性：非常低

Illuminate\Support\Debug\Dumper 和 Illuminate\Support\Debug\HtmlDumper 类已被移除，取而代之的是使用 Symfony 的原生变量转储器：Symfony\Component\VarDumper\VarDumper 和 Symfony\Component\VarDumper\Dumper\HtmlDumper。

Eloquent ​

latest / oldest 方法 ​

影响可能性：低

Eloquent 查询构建器的 latest 和 oldest 方法已更新为尊重可以在您的 Eloquent 模型上指定的自定义 "created at" 时间戳列。通常，这应该被视为一个错误修复；然而，出于谨慎考虑，它被列为一个重大变更。

wasChanged 方法 ​

影响可能性：非常低

Eloquent 模型的更改现在在触发 updated 模型事件之前可用于 wasChanged 方法。通常，这应该被视为一个错误修复；然而，出于谨慎考虑，它被列为一个重大变更。如果您遇到与此变更相关的问题，请告知我们。

PostgreSQL 特殊浮点值 ​

影响可能性：低

PostgreSQL 支持浮点值 Infinity、-Infinity 和 NaN。在 Laravel 5.7 之前，当列的 Eloquent 转换类型为 float、double 或 real 时，这些值被转换为 0。

从 Laravel 5.7 开始，这些值将被转换为相应的 PHP 常量 INF、-INF 和 NAN。

邮件验证 ​

影响可能性：可选

如果您选择使用 Laravel 的新邮件验证服务，您将需要向您的应用程序添加额外的脚手架。首先，将 VerificationController 添加到您的应用程序：App\Http\Controllers\Auth\VerificationController。

您还需要修改您的 App\User 模型以实现 MustVerifyEmail 合约：

php
<?php

namespace App;

use Illuminate\Notifications\Notifiable;
use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements MustVerifyEmail
{
    use Notifiable;

    // ...
}

为了使用 verified 中间件，以便只有经过验证的用户才能访问给定的路由，您需要更新 app/Http/Kernel.php 文件的 $routeMiddleware 属性以包含新的 verified 和 signed 中间件：

php
// 在 App\Http\Kernel 类中...

protected $routeMiddleware = [
    'auth' => \Illuminate\Auth\Middleware\Authenticate::class,
    'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
    'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,
    'can' => \Illuminate\Auth\Middleware\Authorize::class,
    'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
    'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
    'signed' => \Illuminate\Routing\Middleware\ValidateSignature::class,
    'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
];

您还需要验证视图存根。此视图应放置在 resources/views/auth/verify.blade.php。您可以在 GitHub 上获取视图的内容。

接下来，您的用户表必须包含一个 email_verified_at 列，以存储电子邮件地址验证的日期和时间：

php
$table->timestamp('email_verified_at')->nullable();

为了在用户注册时发送电子邮件，您应该在 App\Providers\EventServiceProvider 类中注册以下事件和监听器：

php
use Illuminate\Auth\Events\Registered;
use Illuminate\Auth\Listeners\SendEmailVerificationNotification;

/**
 * 应用程序的事件监听器映射。
 *
 * @var array
 */
protected $listen = [
    Registered::class => [
        SendEmailVerificationNotification::class,
    ],
];

最后，在调用 Auth::routes 方法时，您应该将 verify 选项传递给该方法：

php
Auth::routes(['verify' => true]);

文件系统 ​

Filesystem 合约方法 ​

影响可能性：低

readStream 和 writeStream 方法已添加到 Illuminate\Contracts\Filesystem\Filesystem 合约中。如果您正在实现此接口，您应该将这些方法添加到您的实现中。

哈希 ​

Hash::check 方法 ​

影响可能性：无

check 方法现在可选地检查哈希的算法是否与配置的算法匹配。

邮件 ​

可邮寄动态变量命名 ​

影响可能性：低

动态传递给可邮寄视图的变量现在会自动 "驼峰化"，这使得可邮寄动态变量行为与动态视图变量一致。动态可邮寄变量不是 Laravel 的文档化功能，因此对您的应用程序的影响可能性较低。

模板主题 ​

影响可能性：中等

如果您自定义了用于 Markdown 可邮寄模板的默认主题样式，您将需要重新发布并重新进行自定义。按钮颜色类已从 'blue'、'green' 和 'red' 重命名为 'primary'、'success' 和 'error'。

队列 ​

QUEUE_DRIVER 环境变量 ​

影响可能性：非常低

QUEUE_DRIVER 环境变量已重命名为 QUEUE_CONNECTION。这不应影响您正在升级的现有应用程序，除非您有意修改 config/queue.php 配置文件以匹配 Laravel 5.7。

WorkCommand 选项 ​

影响可能性：非常低

stop-when-empty 选项已添加到 WorkCommand。如果您扩展此命令，您需要将 stop-when-empty 添加到类的 $signature 属性中。

路由 ​

Route::redirect 方法 ​

影响可能性：高

Route::redirect 方法现在返回 302 HTTP 状态码重定向。permanentRedirect 方法已添加以允许 301 重定向。

php
// 返回 302 重定向...
Route::redirect('/foo', '/bar');

// 返回 301 重定向...
Route::redirect('/foo', '/bar', 301);

// 返回 301 重定向...
Route::permanentRedirect('/foo', '/bar');

addRoute 方法 ​

影响可能性：低

Illuminate\Routing\Router 类的 addRoute 方法已从 protected 更改为 public。

验证 ​

嵌套验证数据 ​

影响可能性：中等

在 Laravel 的早期版本中，validate 方法未返回嵌套验证规则的正确数据。这在 Laravel 5.7 中已得到纠正：

php
$data = Validator::make([
    'person' => [
        'name' => 'Taylor',
        'job' => 'Developer'
    ]
], ['person.name' => 'required'])->validate();

dump($data);

// 之前的行为...
['person' => ['name' => 'Taylor', 'job' => 'Developer']]

// 新行为...
['person' => ['name' => 'Taylor']]

Validator 合约 ​

影响可能性：非常低

validate 方法已添加到 Illuminate\Contracts\Validation\Validator 合约中：

php
/**
 * 根据其数据运行验证器的规则。
 *
 * @return array
 */
public function validate();

如果您正在实现此接口，您应该将此方法添加到您的实现中。

测试 ​

影响可能性：中等

Laravel 5.7 为 Artisan 命令引入了改进的测试工具。默认情况下，Artisan 命令输出现在被模拟。如果您依赖 artisan 方法作为测试的一部分运行命令，您应该使用 Artisan::call 或在测试类中定义 public $mockConsoleOutput = false 属性。

杂项 ​

我们还鼓励您查看 laravel/laravel GitHub 仓库 中的更改。虽然这些更改中的许多不是必需的，但您可能希望将这些文件与您的应用程序保持同步。这些更改中的一些将在本升级指南中介绍，但其他更改，例如配置文件或注释的更改，将不会介绍。您可以使用 GitHub 比较工具 轻松查看更改，并选择哪些更新对您来说是重要的。

版权所有 © 2024-2025 laravel.wiki