Laravel 5.3 中文文档

简体中文

English

简体中文

English

主题

升级指南 ​

从 5.2 升级到 5.3.0 ​

预计升级时间：2-3 小时 ​

exclamation

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

更新依赖 ​

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

您还应该在 composer.json 文件的 require-dev 部分中将 symfony/css-selector 和 symfony/dom-crawler 依赖更新为 3.1.*。

PHP & HHVM ​

Laravel 5.3 需要 PHP 5.6.4 或更高版本。HHVM 不再被官方支持，因为它不包含与 PHP 5.6+ 相同的语言特性。

弃用 ​

在 Laravel 5.2 升级指南 中列出的所有弃用功能已从框架中移除。您应该查看此列表以确认您不再使用这些弃用的功能。

应用程序服务提供者 ​

您可以从 EventServiceProvider、RouteServiceProvider 和 AuthServiceProvider 类的 boot 方法中移除参数。对给定参数的任何调用可以转换为使用等效的 facade 代替。例如，您可以直接调用 Event facade，而不是调用 $dispatcher 参数上的方法。同样，您可以调用 Route facade，而不是调用 $router 参数上的方法；您可以调用 Gate facade，而不是调用 $gate 参数上的方法。

exclamation

在将方法调用转换为 facades 时，请确保将 facade 类导入到您的服务提供者中。

数组 ​

键/值顺序变更 ​

Arr 类上的 first、last 和 where 方法，以及它们相关的全局辅助函数，现在将 "value" 作为第一个参数传递给给定的回调闭包。例如：

php
Arr::first($array, function ($value, $key) {
    return ! is_null($value);
});

在 Laravel 的早期版本中，$key 是第一个传递的参数。由于大多数用例只对 $value 感兴趣，因此现在将其作为第一个参数传递。您应该在应用程序中进行 "全局查找"，以确认您期望 $value 作为闭包的第一个参数传递。

Artisan ​

make:console 命令 ​

make:console 命令已重命名为 make:command。

认证 ​

认证脚手架 ​

框架提供的两个默认认证控制器已拆分为四个较小的控制器。此更改默认提供了更清晰、更专注的认证控制器。升级应用程序到新的认证控制器的最简单方法是从 GitHub 获取每个控制器的新副本 并将它们放入您的应用程序中。

您还应该确保在 routes/web.php 文件中调用 Auth::routes() 方法。此方法将为新的认证控制器注册适当的路由。

一旦这些控制器被放入您的应用程序中，您可能需要重新实现对这些控制器所做的任何自定义。例如，如果您正在自定义用于认证的认证守卫，您可能需要重写控制器的 guard 方法。您可以检查每个认证控制器的 trait 以确定要重写的方法。

lightbulb

如果您没有自定义认证控制器，您应该能够直接从 GitHub 中放入控制器的新副本，并确认您在 routes/web.php 文件中调用了 Auth::routes 方法。

密码重置邮件 ​

密码重置邮件现在使用新的 Laravel 通知功能。如果您想自定义发送密码重置链接时发送的通知，您应该重写 Illuminate\Auth\Passwords\CanResetPassword trait 的 sendPasswordResetNotification 方法。

您的 User 模型 必须 使用新的 Illuminate\Notifications\Notifiable trait，以便密码重置链接邮件能够被发送：

php
<?php

namespace App;

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

class User extends Authenticatable
{
    use Notifiable;
}
exclamation

不要忘记在 config/app.php 配置文件的 providers 数组中注册 Illuminate\Notifications\NotificationServiceProvider。

POST 退出 ​

Auth::routes 方法现在为 /logout 注册了一个 POST 路由，而不是 GET 路由。这可以防止其他 Web 应用程序将您的用户从您的应用程序中注销。要升级，您应该将退出请求转换为使用 POST 动词，或者为 /logout URI 注册您自己的 GET 路由：

php
Route::get('/logout', 'Auth\LoginController@logout');

授权 ​

使用类名调用策略方法 ​

某些策略方法只接收当前认证的用户，而不接收它们授权的模型实例。这种情况最常见于授权 create 操作。例如，如果您正在创建一个博客，您可能希望检查用户是否被授权创建任何帖子。

在定义不会接收模型实例的策略方法时，例如 create 方法，类名将不再作为第二个参数传递给方法。您的方法应该只期望认证的用户实例：

php
/**
 * 确定给定用户是否可以创建帖子。
 *
 * @param  \App\User  $user
 * @return bool
 */
public function create(User $user)
{
    //
}

AuthorizesResources Trait ​

AuthorizesResources trait 已与 AuthorizesRequests trait 合并。您应该从 app/Http/Controllers/Controller.php 文件中移除 AuthorizesResources trait。

Blade ​

自定义指令 ​

在 Laravel 的早期版本中，当使用 directive 方法注册自定义 Blade 指令时，传递给指令回调的 $expression 包含最外层的括号。在 Laravel 5.3 中，这些最外层的括号不再包含在传递给指令回调的表达式中。请务必查看 Blade 扩展 文档，并验证您的自定义 Blade 指令是否仍然正常工作。

广播 ​

服务提供者 ​

Laravel 5.3 包含对 事件广播 的重大改进。您应该通过 从 GitHub 获取源代码的新副本 将新的 BroadcastServiceProvider 添加到您的 app/Providers 目录中。一旦您定义了新的服务提供者，您应该将其添加到 config/app.php 配置文件的 providers 数组中。

接下来，通过 从 GitHub 获取源代码的新副本 将新的 broadcasting.php 配置文件添加到您的 app/config 目录中。

缓存 ​

扩展闭包绑定 & $this ​

当使用闭包调用 Cache::extend 方法时，$this 将绑定到 CacheManager 实例，允许您从扩展闭包中调用其方法：

php
Cache::extend('memcached', function ($app, $config) {
    try {
        return $this->createMemcachedDriver($config);
    } catch (Exception $e) {
        return $this->createNullDriver($config);
    }
});

Cashier ​

如果您正在使用 Cashier，您应该将 laravel/cashier 包升级到 ~7.0 版本。此版本的 Cashier 仅升级了一些内部方法以与 Laravel 5.3 兼容，并不是一个重大变更。

集合 ​

键/值顺序变更 ​

first、last 和 contains 集合方法都将 "value" 作为第一个参数传递给它们的给定回调闭包。例如：

php
$collection->first(function ($value, $key) {
    return ! is_null($value);
});

在 Laravel 的早期版本中，$key 是第一个传递的参数。由于大多数用例只对 $value 感兴趣，因此现在将其作为第一个参数传递。您应该在应用程序中进行 "全局查找"，以确认您期望 $value 作为闭包的第一个参数传递。

集合 where 比较方法默认是 "宽松" 的 ​

集合的 where 方法现在默认执行 "宽松" 比较，而不是严格比较。如果您想执行严格比较，可以使用 whereStrict 方法。

由于此更改，whereLoose 方法已从集合类中移除。

where 方法也不再接受第三个参数来指示 "严格性"。您应该根据应用程序的需要显式调用 where 或 whereStrict。

配置 ​

应用程序名称 ​

在 config/app.php 配置文件中，添加以下配置选项：

php
'name' => 'Your Application Name',

控制器 ​

构造函数中的会话 ​

在 Laravel 的早期版本中，您可以在控制器的构造函数中访问会话变量或认证用户。这从来不是框架的显式功能。在 Laravel 5.3 中，您无法在控制器的构造函数中访问会话或认证用户，因为中间件尚未运行。

作为替代方案，您可以直接在控制器的构造函数中定义基于闭包的中间件。在使用此功能之前，请确保您的应用程序正在运行 Laravel 5.3.4 或更高版本：

php
<?php

namespace App\Http\Controllers;

use App\User;
use Illuminate\Support\Facades\Auth;
use App\Http\Controllers\Controller;

class ProjectController extends Controller
{
    /**
     * 当前用户的所有项目。
     */
    protected $projects;

    /**
     * 创建一个新的控制器实例。
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware(function ($request, $next) {
            $this->projects = Auth::user()->projects;

            return $next($request);
        });
    }
}

当然，您也可以通过在控制器操作中类型提示 Illuminate\Http\Request 类来访问请求会话数据或认证用户：

php
/**
 * 显示当前用户的所有项目。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return Response
 */
public function index(Request $request)
{
    $projects = $request->user()->projects;

    $value = $request->session()->get('key');

    //
}

数据库 ​

集合 ​

流畅的查询构建器 现在返回 Illuminate\Support\Collection 实例，而不是普通数组。这为流畅的查询构建器和 Eloquent 返回的结果类型带来了统一性。

如果您不想将查询构建器结果迁移到 Collection 实例，您可以将 all 方法链接到查询构建器的 get 或 pluck 方法上。这将返回结果的普通 PHP 数组，允许您保持向后兼容性：

php
$users = DB::table('users')->get()->all();

$usersIds = DB::table('users')->pluck('id')->all();

Eloquent getRelation 方法 ​

Eloquent getRelation 方法不再抛出 BadMethodCallException，如果关系无法加载。相反，它将抛出 Illuminate\Database\Eloquent\RelationNotFoundException。此更改仅会影响您的应用程序，如果您手动捕获 BadMethodCallException。

Eloquent $morphClass 属性 ​

可以在 Eloquent 模型上定义的 $morphClass 属性已被移除，取而代之的是定义 "morph map"。定义 morph map 提供了对预加载的支持，并解决了多态关系的其他错误。如果您之前依赖于 $morphClass 属性，您应该使用以下语法迁移到 morphMap：

php
Relation::morphMap([
    'YourCustomMorphName' => YourModel::class,
]);

例如，如果您之前定义了以下 $morphClass：

php
class User extends Model
{
    protected $morphClass = 'user'
}

您应该在 AppServiceProvider 的 boot 方法中定义以下 morphMap：

php
use Illuminate\Database\Eloquent\Relations\Relation;

Relation::morphMap([
    'user' => User::class,
]);

Eloquent 作用域 ​

Eloquent 作用域现在尊重作用域约束的前导布尔值。例如，如果您以 orWhere 约束开始作用域，它将不再被转换为普通 where。如果您依赖于此功能（例如在循环中添加多个 orWhere 约束），您应该验证第一个条件是普通 where，以避免任何布尔逻辑问题。

如果您的作用域以 where 约束开始，则无需采取任何行动。请记住，您可以使用查询的 toSql 方法验证您的查询 SQL：

php
User::where('foo', 'bar')->toSql();

Join 子句 ​

JoinClause 类已重写，以统一其语法与查询构建器。on 子句的可选 $where 参数已被移除。要添加 "where" 条件，您应该显式使用 查询构建器 提供的 where 方法之一：

php
$query->join('table', function ($join) {
    $join->on('foo', 'bar')->where('bar', 'baz');
});

on 子句的操作符现在经过验证，不能再包含无效值。如果您依赖于此功能（例如 $join->on('foo', 'in', DB::raw('("bar")'))），您应该使用适当的 where 子句重写条件：

php
$join->whereIn('foo', ['bar']);

$bindings 属性也被移除。要直接操作 join 绑定，您可以使用 addBinding 方法：

php
$query->join(DB::raw('('.$subquery->toSql().') table'), function ($join) use ($subquery) {
    $join->addBinding($subquery->getBindings(), 'join');
});

加密 ​

Mcrypt 加密器已被移除 ​

Mcrypt 加密器在 2015 年 6 月的 Laravel 5.1.0 版本中被弃用。此加密器已在 5.3.0 版本中完全移除，取而代之的是基于 OpenSSL 的新加密实现，自 Laravel 5.1.0 以来一直是默认的加密方案。

如果您仍在使用 Mcrypt 基于 cipher 的 config/app.php 配置文件，您应该将密码更新为 AES-256-CBC，并将密钥设置为一个随机的 32 字节字符串，可以使用 php artisan key:generate 安全生成。

如果您在数据库中存储使用 Mcrypt 加密器加密的数据，您可以安装 laravel/legacy-encrypter 包，其中包含旧的 Mcrypt 加密器实现。您应该使用此包解密加密的数据，并使用新的 OpenSSL 加密器重新加密。例如，您可以在 自定义 Artisan 命令 中执行以下操作：

php
$legacy = new McryptEncrypter($encryptionKey);

foreach ($records as $record) {
    $record->encrypted = encrypt(
        $legacy->decrypt($record->encrypted)
    );

    $record->save();
}

异常处理程序 ​

构造函数 ​

基础异常处理程序类现在需要将 Illuminate\Container\Container 实例传递给其构造函数。此更改仅会影响您的应用程序，如果您在 app/Exceptions/Handler.php 文件中定义了自定义 __construct 方法。如果您这样做了，您应该将容器实例传递给 parent::__construct 方法：

php
parent::__construct(app());

未认证方法 ​

您应该将 unauthenticated 方法添加到您的 App\Exceptions\Handler 类中。此方法将认证异常转换为 HTTP 响应：

php
/**
 * 将认证异常转换为未认证响应。
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Illuminate\Auth\AuthenticationException  $exception
 * @return \Illuminate\Http\Response
 */
protected function unauthenticated($request, AuthenticationException $exception)
{
    if ($request->expectsJson()) {
        return response()->json(['error' => 'Unauthenticated.'], 401);
    }

    return redirect()->guest('login');
}

中间件 ​

can 中间件命名空间更改 ​

HTTP 内核的 $routeMiddleware 属性中列出的 can 中间件应更新为以下类：

php
'can' => \Illuminate\Auth\Middleware\Authorize::class,

can 中间件认证异常 ​

如果用户未认证，can 中间件现在将抛出 Illuminate\Auth\AuthenticationException 实例。如果您手动捕获了不同的异常类型，您应该更新您的应用程序以捕获此异常。在大多数情况下，此更改不会影响您的应用程序。

绑定替换中间件 ​

路由模型绑定现在通过中间件完成。所有应用程序都应在 app/Http/Kernel.php 文件的 web 中间件组中添加 Illuminate\Routing\Middleware\SubstituteBindings：

php
\Illuminate\Routing\Middleware\SubstituteBindings::class,

您还应该在 HTTP 内核的 $routeMiddleware 属性中注册一个路由中间件用于绑定替换：

php
'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,

一旦注册了此路由中间件，您应该将其添加到 api 中间件组中：

php
'api' => [
    'throttle:60,1',
    'bindings',
],

通知 ​

安装 ​

Laravel 5.3 包含一个新的、基于驱动的通知系统。您应该在 config/app.php 配置文件的 providers 数组中注册 Illuminate\Notifications\NotificationServiceProvider。

您还应该在 config/app.php 配置文件的 aliases 数组中添加 Illuminate\Support\Facades\Notification facade。

最后，您可以在您的 User 模型或任何其他希望接收通知的模型上使用 Illuminate\Notifications\Notifiable trait。

分页 ​

自定义 ​

与之前的 Laravel 5.x 版本相比，自定义分页器生成的 HTML 在 Laravel 5.3 中变得更加容易。您只需定义一个简单的 Blade 模板，而不是定义一个 "Presenter" 类。自定义分页视图的最简单方法是使用 vendor:publish 命令将它们导出到您的 resources/views/vendor 目录：

php
php artisan vendor:publish --tag=laravel-pagination

此命令将在 resources/views/vendor/pagination 目录中放置视图。此目录中的 default.blade.php 文件对应于默认分页视图。只需编辑此文件即可修改分页 HTML。

请务必查看完整的 分页文档 以获取更多信息。

队列 ​

配置 ​

在您的队列配置中，所有 expire 配置项应重命名为 retry_after。同样，Beanstalk 配置的 ttr 项应重命名为 retry_after。此名称更改为此配置选项的目的提供了更多的清晰性。

闭包 ​

不再支持队列闭包。如果您在应用程序中排队一个闭包，您应该将闭包转换为一个类并排队类的实例：

php
dispatch(new ProcessPodcast($podcast));

集合序列化 ​

Illuminate\Queue\SerializesModels trait 现在可以正确序列化 Illuminate\Database\Eloquent\Collection 的实例。这对于绝大多数应用程序来说可能不是一个重大变更；但是，如果您的应用程序绝对依赖于集合不被队列作业重新从数据库中检索，您应该验证此更改不会对您的应用程序产生负面影响。

守护进程工作者 ​

在调用 queue:work Artisan 命令时不再需要指定 --daemon 选项。运行 php artisan queue:work 命令将自动假定您希望以守护进程模式运行工作者。如果您想处理单个作业，可以在命令上使用 --once 选项：

php
// 启动一个守护进程队列工作者...
php artisan queue:work

// 处理单个作业...
php artisan queue:work --once

失败作业表 ​

如果您的应用程序包含一个 failed_jobs 表，您应该在表中添加一个 exception 列：

php
$table->longText('exception')->after('payload');

数据库驱动更改 ​

如果您使用 database 驱动存储您的队列作业，您应该删除 jobs_queue_reserved_reserved_at_index 索引，然后从 jobs 表中删除 reserved 列。使用 database 驱动时不再需要此列。完成这些更改后，您应该在 queue 和 reserved_at 列上添加一个新的复合索引。

下面是一个示例迁移，您可以使用它来执行必要的更改：

php
public function up()
{
    Schema::table('jobs', function (Blueprint $table) {
        $table->dropIndex('jobs_queue_reserved_reserved_at_index');
        $table->dropColumn('reserved');
        $table->index(['queue', 'reserved_at']);
    });

    Schema::table('failed_jobs', function (Blueprint $table) {
        $table->longText('exception')->after('payload');
    });
}

public function down()
{
    Schema::table('jobs', function (Blueprint $table) {
        $table->tinyInteger('reserved')->unsigned();
        $table->index(['queue', 'reserved', 'reserved_at']);
        $table->dropIndex('jobs_queue_reserved_at_index');
    });

    Schema::table('failed_jobs', function (Blueprint $table) {
        $table->dropColumn('exception');
    });
}

事件数据更改 ​

各种队列作业事件（如 JobProcessing 和 JobProcessed）不再包含 $data 属性。您应该更新您的应用程序以调用 $event->job->payload() 以获取等效数据。

失败作业事件 ​

如果您在 AppServiceProvider 中调用 Queue::failing 方法，您应该将方法签名更新为以下内容：

php
use Illuminate\Queue\Events\JobFailed;

Queue::failing(function (JobFailed $event) {
    // $event->connectionName
    // $event->job
    // $event->exception
});

进程控制扩展 ​

如果您的应用程序使用 --timeout 选项用于队列工作者，您需要验证 pcntl 扩展 是否已安装。

在旧式队列作业上序列化模型 ​

通常，Laravel 中的作业通过将新作业实例传递给 Queue::push 方法来排队。然而，一些应用程序可能使用以下旧式语法排队作业：

php
Queue::push('ClassName@method');

如果您使用此语法排队作业，Eloquent 模型将不再自动序列化并由队列重新检索。如果您希望您的 Eloquent 模型由队列自动序列化，您应该在作业类上使用 Illuminate\Queue\SerializesModels trait，并使用新的 push 语法排队作业：

php
Queue::push(new ClassName);

路由 ​

资源参数默认是单数 ​

在 Laravel 的早期版本中，使用 Route::resource 注册的路由参数不是 "单数化" 的。这可能导致在注册路由模型绑定时出现一些意外行为。例如，给定以下 Route::resource 调用：

php
Route::resource('photos', 'PhotoController');

show 路由的 URI 将定义如下：

php
/photos/{photos}

在 Laravel 5.3 中，所有资源路由参数默认是单数化的。因此，相同的 Route::resource 调用将注册以下 URI：

php
/photos/{photo}

如果您希望保持以前的行为，而不是自动单数化资源路由参数，您可以在 AppServiceProvider 中调用 singularResourceParameters 方法：

php
use Illuminate\Support\Facades\Route;

Route::singularResourceParameters(false);

资源路由名称不再受前缀影响 ​

URL 前缀不再影响使用 Route::resource 时分配给路由的路由名称，因为此行为破坏了使用路由名称的整个目的。

如果您的应用程序在指定 prefix 选项的 Route::group 调用中使用 Route::resource，您应该检查所有 route 助手和 UrlGenerator::route 调用，以验证您不再将此 URI 前缀附加到路由名称。

如果此更改导致您有两个具有相同名称的路由，您有两个选项。首先，您可以在调用 Route::resource 时使用 names 选项为给定路由指定自定义名称。有关更多信息，请参阅 资源路由文档。或者，您可以在路由组上添加 as 选项：

php
Route::group(['as' => 'admin.', 'prefix' => 'admin'], function () {
    //
});

验证 ​

表单请求异常 ​

如果表单请求的验证失败，Laravel 现在将抛出 Illuminate\Validation\ValidationException 实例，而不是 HttpException 实例。如果您手动捕获表单请求抛出的 HttpException 实例，您应该更新您的 catch 块以捕获 ValidationException。

消息包 ​

如果您之前使用 has 方法来确定 Illuminate\Support\MessageBag 实例是否包含任何消息，您应该改用 count 方法。has 方法现在需要一个参数，并且仅确定消息包中是否存在特定键。

可为空的原始类型 ​

在验证数组、布尔值、整数、数字和字符串时，除非规则集中包含新的 nullable 规则，否则 null 将不再被视为有效值：

php
Validator::make($request->all(), [
    'field' => 'nullable|max:5',
]);

从 5.1 升级到 5.2.0 ​

预计升级时间：少于 1 小时 ​

exclamation

我们尝试提供一个非常全面的列表，列出框架中每一个可能的重大变更。然而，许多这些变更可能不适用于您自己的应用程序。

更新依赖 ​

将您的 composer.json 文件更新为指向 laravel/framework 5.2.*。

在 composer.json 文件的 require-dev 部分中添加 "symfony/dom-crawler": "~3.0" 和 "symfony/css-selector": "~3.0"。

认证 ​

配置文件 ​

您应该使用以下内容更新您的 config/auth.php 配置文件：https://github.com/laravel/laravel/blob/5.2/config/auth.php

一旦您使用新副本更新了文件，请根据旧配置文件设置您的认证配置选项的期望值。如果您在 Laravel 5.1 中使用了典型的基于 Eloquent 的认证服务，大多数值应该保持不变。

特别注意新 auth.php 配置文件中的 passwords.users.email 配置选项，并验证视图路径是否与您的应用程序的实际视图路径匹配，因为在 Laravel 5.2 中此视图的默认路径已更改。如果新配置文件中的默认值与现有视图不匹配，请更新配置选项。

合同 ​

如果您正在实现 Illuminate\Contracts\Auth\Authenticatable 合同但 未 使用 Authenticatable trait，您应该在合同实现中添加一个新的 getAuthIdentifierName 方法。通常，此方法将返回可认证实体的 "主键" 的列名。例如：id。

除非您手动实现此接口，否则这不太可能影响您的应用程序。

自定义驱动 ​

如果您使用 Auth::extend 方法定义自定义用户检索方法，您现在应该使用 Auth::provider 定义自定义用户提供者。一旦您定义了自定义提供者，您可以在新的 auth.php 配置文件的 providers 数组中配置它。

有关自定义认证提供者的更多信息，请查阅 完整的认证文档。

重定向 ​

Illuminate\Foundation\Auth\AuthenticatesUsers 中的 loginPath() 方法已被移除，因此在您的 AuthController 中放置 $loginPath 变量不再需要。默认情况下，trait 将始终在认证错误时将用户重定向回其先前的位置。

授权 ​

Illuminate\Auth\Access\UnauthorizedException 已重命名为 Illuminate\Auth\Access\AuthorizationException。除非您手动捕获此异常，否则这不太可能影响您的应用程序。

集合 ​

Eloquent 基础集合 ​

Eloquent 集合实例现在返回基础集合（Illuminate\Support\Collection）用于以下方法：pluck、keys、zip、collapse、flatten、flip。

键保留 ​

slice、chunk 和 reverse 方法现在在集合上保留键。如果您不希望这些方法保留键，请在 Collection 实例上使用 values 方法。

Composer 类 ​

Illuminate\Foundation\Composer 类已移至 Illuminate\Support\Composer。除非您手动使用此类，否则这不太可能影响您的应用程序。

命令和处理程序 ​

自处理命令 ​

您不再需要在作业/命令上实现 SelfHandling 合同。所有作业现在默认是自处理的，因此您可以从类中移除此接口。

分离命令和处理程序 ​

Laravel 5.2 命令总线现在仅支持自处理命令，不再支持分离命令和处理程序。

如果您希望继续使用分离命令和处理程序，您可以安装一个 Laravel Collective 包，该包提供向后兼容支持：https://github.com/LaravelCollective/bus

配置 ​

环境值 ​

在您的 app.php 配置文件中添加一个 env 配置选项，如下所示：

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

缓存和环境 ​

如果您在部署期间使用 config:cache 命令，您 必须 确保仅在配置文件中调用 env 函数，而不是在应用程序的其他地方调用。

如果您在应用程序中调用 env，强烈建议您将适当的配置值添加到配置文件中，并从该位置调用 env，以便您可以将 env 调用转换为 config 调用。

编译类 ​

如果存在，请从 config/compile.php 中的 files 数组中删除以下行：

php
realpath(__DIR__.'/../app/Providers/BusServiceProvider.php'),
realpath(__DIR__.'/../app/Providers/ConfigServiceProvider.php'),

如果此处列出的服务提供者不存在，未执行此操作可能会在运行 php artisan optimize 时触发错误。

CSRF 验证 ​

在运行单元测试时不再自动执行 CSRF 验证。这不太可能影响您的应用程序。

数据库 ​

MySQL 日期 ​

从 MySQL 5.7 开始，0000-00-00 00:00:00 不再被视为有效日期，因为默认启用了 strict 模式。在将记录插入数据库时，所有时间戳列都应接收有效的默认值。您可以在迁移中使用 useCurrent 方法将时间戳列默认设置为当前时间戳，或者可以使时间戳 nullable 以允许 null 值：

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

$table->timestamp('foo')->useCurrent();

$table->nullableTimestamps();

MySQL JSON 列类型 ​

json 列类型现在在 MySQL 驱动程序中创建实际的 JSON 列。如果您未运行 MySQL 5.7 或更高版本，则此列类型将不可用。相反，请在迁移中使用 text 列类型。

填充 ​

在运行数据库填充时，所有 Eloquent 模型现在默认不受保护。以前需要调用 Model::unguard()。如果您希望在填充期间保护模型，可以在 DatabaseSeeder 类的顶部调用 Model::reguard()。

Eloquent ​

日期转换 ​

任何已添加到您的 $casts 属性中的 date 或 datetime 属性现在在调用 toArray 时将转换为字符串。这使得日期转换与 $dates 数组中指定的日期转换一致。

全局作用域 ​

全局作用域实现已重写，使其更易于使用。您的全局作用域不再需要 remove 方法，因此可以从您编写的任何全局作用域中移除。

如果您在 Eloquent 查询构建器上调用 getQuery 以访问底层查询构建器实例，您现在应该调用 toBase。

如果您出于任何原因直接调用 remove 方法，您应该将此调用更改为 $eloquentBuilder->withoutGlobalScope($scope)。

新的方法 withoutGlobalScope 和 withoutGlobalScopes 已添加到 Eloquent 查询构建器。任何对 $model->removeGlobalScopes($builder) 的调用都可以更改为简单的 $builder->withoutGlobalScopes()。

主键 ​

默认情况下，Eloquent 假定您的主键是整数，并将其自动转换为整数。对于任何不是整数的主键，您应该在 Eloquent 模型上将 $incrementing 属性重写为 false：

php
/**
 * 指示 ID 是否是自动递增的。
 *
 * @var bool
 */
public $incrementing = true;

事件 ​

核心事件对象 ​

Laravel 触发的一些核心事件现在使用事件对象，而不是字符串事件名称和动态参数。以下是旧事件名称及其新的基于对象的对应项的列表：

旧新
artisan.startIlluminate\Console\Events\ArtisanStarting
auth.attemptingIlluminate\Auth\Events\Attempting
auth.loginIlluminate\Auth\Events\Login
auth.logoutIlluminate\Auth\Events\Logout
cache.missedIlluminate\Cache\Events\CacheMissed
cache.hitIlluminate\Cache\Events\CacheHit
cache.writeIlluminate\Cache\Events\KeyWritten
cache.deleteIlluminate\Cache\Events\KeyForgotten
connection.{name}.beginTransactionIlluminate\Database\Events\TransactionBeginning
connection.{name}.committedIlluminate\Database\Events\TransactionCommitted
connection.{name}.rollingBackIlluminate\Database\Events\TransactionRolledBack
illuminate.queryIlluminate\Database\Events\QueryExecuted
illuminate.queue.beforeIlluminate\Queue\Events\JobProcessing
illuminate.queue.afterIlluminate\Queue\Events\JobProcessed
illuminate.queue.failedIlluminate\Queue\Events\JobFailed
illuminate.queue.stoppingIlluminate\Queue\Events\WorkerStopping
mailer.sendingIlluminate\Mail\Events\MessageSending
router.matchedIlluminate\Routing\Events\RouteMatched

这些事件对象中的每一个都包含与 Laravel 5.1 中传递给事件处理程序的参数 完全相同 的参数。例如，如果您在 5.1.* 中使用 DB::listen，您可以像这样更新您的代码以适应 5.2.*：

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

您可以查看每个新的事件对象类以查看其公共属性。

异常处理 ​

您的 App\Exceptions\Handler 类的 $dontReport 属性应更新为至少包含以下异常类型：

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

/**
 * 不应报告的异常类型列表。
 *
 * @var array
 */
protected $dontReport = [
    AuthorizationException::class,
    HttpException::class,
    ModelNotFoundException::class,
    ValidationException::class,
];

辅助函数 ​

url() 辅助函数现在在未提供路径时返回 Illuminate\Routing\UrlGenerator 实例。

隐式模型绑定 ​

Laravel 5.2 包含 "隐式模型绑定"，这是一项方便的新功能，可以根据 URI 中存在的标识符自动将模型实例注入到路由和控制器中。然而，这确实改变了类型提示模型实例的路由和控制器的行为。

如果您在路由或控制器中类型提示模型实例，并期望注入一个 空 模型实例，您应该移除此类型提示，并直接在路由或控制器中创建一个空模型实例；否则，Laravel 将尝试根据路由 URI 中存在的标识符从数据库中检索现有模型实例。

IronMQ ​

IronMQ 队列驱动程序已移至其自己的包中，不再与核心框架一起提供。

https://github.com/LaravelCollective/iron-queue

作业/队列 ​

php artisan make:job 命令现在默认创建一个 "queued" 作业类定义。如果您想创建一个 "sync" 作业，请在发出命令时使用 --sync 选项。

邮件 ​

pretend 邮件配置选项已被移除。相反，请使用 log 邮件驱动程序，该驱动程序执行与 pretend 相同的功能，并记录有关邮件消息的更多信息。

分页 ​

为了与框架生成的其他 URL 保持一致，分页器 URL 不再包含尾随斜杠。这不太可能影响您的应用程序。

服务提供者 ​

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

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

会话 ​

由于认证系统的更改，升级到 Laravel 5.2 时，任何现有会话都将失效。

数据库会话驱动 ​

框架为其编写了一个新的 database 会话驱动，其中包含有关用户的更多信息，例如其用户 ID、IP 地址和用户代理。如果您希望继续使用旧驱动程序，可以在 session.php 配置文件中指定 legacy-database 驱动。

如果您希望使用新驱动程序，您应该在会话数据库表中添加 user_id (nullable integer)、ip_address (nullable string) 和 user_agent (text) 列。

Stringy ​

"Stringy" 库不再包含在框架中。如果您希望在应用程序中使用它，可以通过 Composer 手动安装。

验证 ​

异常类型 ​

ValidatesRequests trait 现在抛出 Illuminate\Foundation\Validation\ValidationException 实例，而不是抛出 Illuminate\Http\Exception\HttpResponseException 实例。除非您手动捕获此异常，否则这不太可能影响您的应用程序。

弃用 ​

以下功能在 5.2 中被弃用，并将在 2016 年 6 月的 5.3 版本中移除：

  • Illuminate\Contracts\Bus\SelfHandling 合同。可以从作业中移除。
  • 集合、查询构建器和 Eloquent 查询构建器对象上的 lists 方法已重命名为 pluck。方法签名保持不变。
  • 使用 Route::controller 的隐式控制器路由已被弃用。请在路由文件中使用显式路由注册。这可能会被提取到一个包中。
  • get、post 和其他路由助手函数已被移除。您可以使用 Route facade 代替。
  • 来自 5.1 的 database 会话驱动已重命名为 legacy-database，并将被移除。有关更多信息，请查阅上面的 "数据库会话驱动" 说明。
  • Str::randomBytes 函数已被弃用，取而代之的是 random_bytes 原生 PHP 函数。
  • Str::equals 函数已被弃用，取而代之的是 hash_equals 原生 PHP 函数。
  • Illuminate\View\Expression 已被弃用，取而代之的是 Illuminate\Support\HtmlString。
  • WincacheStore 缓存驱动已被移除。

升级到 5.1.11 ​

Laravel 5.1.11 包含对 授权 和 策略 的支持。将这些新功能合并到现有的 Laravel 5.1 应用程序中非常简单。

exclamation

这些升级是 可选的，忽略它们不会影响您的应用程序。

创建策略目录 ​

首先，在您的应用程序中创建一个空的 app/Policies 目录。

创建/注册 AuthServiceProvider 和 Gate Facade ​

在您的 app/Providers 目录中创建一个 AuthServiceProvider。您可以从 GitHub 获取默认提供者的内容。请记住，如果您的应用程序使用自定义命名空间，请更改提供者的命名空间。创建提供者后，请务必在 app.php 配置文件的 providers 数组中注册它。

此外，您应该在 app.php 配置文件的 aliases 数组中注册 Gate facade：

php
'Gate' => Illuminate\Support\Facades\Gate::class,

更新用户模型 ​

其次，在您的 App\User 模型上使用 Illuminate\Foundation\Auth\Access\Authorizable trait 和 Illuminate\Contracts\Auth\Access\Authorizable 合同：

php
<?php

namespace App;

use Illuminate\Auth\Authenticatable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Auth\Passwords\CanResetPassword;
use Illuminate\Foundation\Auth\Access\Authorizable;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;
use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;

class User extends Model implements AuthenticatableContract,
                                    AuthorizableContract,
                                    CanResetPasswordContract
{
    use Authenticatable, Authorizable, CanResetPassword;
}

更新基础控制器 ​

接下来，更新您的基础 App\Http\Controllers\Controller 控制器以使用 Illuminate\Foundation\Auth\Access\AuthorizesRequests trait：

php
<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

abstract class Controller extends BaseController
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}

升级到 5.1.0 ​

预计升级时间：少于 1 小时 ​

更新 bootstrap/autoload.php ​

将 bootstrap/autoload.php 中的 $compiledPath 变量更新为以下内容：

php
$compiledPath = __DIR__.'/cache/compiled.php';

创建 bootstrap/cache 目录 ​

在您的 bootstrap 目录中创建一个 cache 目录（bootstrap/cache）。在此目录中放置一个 .gitignore 文件，内容如下：

php
*
!.gitignore

此目录应可写，并将由框架用于存储临时优化文件，如 compiled.php、routes.php、config.php 和 services.json。

添加 BroadcastServiceProvider 提供者 ​

在您的 config/app.php 配置文件中，将 Illuminate\Broadcasting\BroadcastServiceProvider 添加到 providers 数组中。

认证 ​

如果您正在使用使用 AuthenticatesAndRegistersUsers trait 的 AuthController，您需要对新用户的验证和创建方式进行一些更改。

首先，您不再需要将 Guard 和 Registrar 实例传递给基础构造函数。您可以完全从控制器的构造函数中移除这些依赖项。

其次，不再需要在 Laravel 5.0 中使用的 App\Services\Registrar 类。您可以简单地将此类中的 validator 和 create 方法直接复制粘贴到您的 AuthController 中。无需对这些方法进行其他更改；但是，您应该确保在 AuthController 的顶部导入 Validator facade 和您的 User 模型。

密码控制器 ​

包含的 PasswordController 不再需要其构造函数中的任何依赖项。您可以移除 5.0 下所需的两个依赖项。

验证 ​

如果您在基础控制器类上重写 formatValidationErrors 方法，您现在应该类型提示 Illuminate\Contracts\Validation\Validator 合同，而不是具体的 Illuminate\Validation\Validator 实例。

同样，如果您在基础表单请求类上重写 formatErrors 方法，您现在应该类型提示 Illuminate\Contracts\Validation\Validator 合同，而不是具体的 Illuminate\Validation\Validator 实例。

迁移 ​

如果您有任何重命名列的迁移或从 SQLite 数据库中删除列的迁移，您需要将 doctrine/dbal 依赖项添加到您的 composer.json 文件中，并在终端中运行 composer update 命令以安装库。

Eloquent ​

create 方法 ​

Eloquent 的 create 方法现在可以在没有任何参数的情况下调用。如果您在自己的模型中重写 create 方法，请将 $attributes 参数的默认值设置为一个数组：

php
public static function create(array $attributes = [])
{
    // 您的自定义实现
}

find 方法 ​

如果您在自己的模型中重写 find 方法，并在自定义方法中调用 parent::find()，您现在应该更改为调用 Eloquent 查询构建器上的 find 方法：

php
public static function find($id, $columns = ['*'])
{
    $model = static::query()->find($id, $columns);

    // ...

    return $model;
}

lists 方法 ​

lists 方法现在返回一个 Collection 实例，而不是 Eloquent 查询的普通数组。如果您想将 Collection 转换为普通数组，请使用 all 方法：

php
User::lists('id')->all();

请注意，查询构建器的 lists 方法仍然返回一个数组。

日期格式化 ​

以前，可以通过在模型上重写 getDateFormat 方法来修改 Eloquent 日期字段的存储格式。这仍然是可能的；但是，为了方便起见，您可以简单地在模型上指定一个 $dateFormat 属性，而不是重写方法。

在将模型序列化为 array 或 JSON 时，也会应用日期格式。这可能会在从 Laravel 5.0 迁移到 5.1 时更改 JSON 序列化日期字段的格式。要为序列化模型设置特定的日期格式，您可以在模型上重写 serializeDate(DateTime $date) 方法。此方法允许您在不更改存储格式的情况下对序列化的 Eloquent 日期字段进行细粒度控制。

集合类 ​

sort 方法 ​

sort 方法现在返回一个新的集合实例，而不是修改现有集合：

php
$collection = $collection->sort($callback);

sortBy 方法 ​

sortBy 方法现在返回一个新的集合实例，而不是修改现有集合：

php
$collection = $collection->sortBy('name');

groupBy 方法 ​

groupBy 方法现在为父 Collection 中的每个项目返回 Collection 实例。如果您想将所有项目转换回普通数组，可以 map 它们：

php
$collection->groupBy('type')->map(function ($item)
{
    return $item->all();
});

lists 方法 ​

lists 方法现在返回一个 Collection 实例，而不是普通数组。如果您想将 Collection 转换为普通数组，请使用 all 方法：

php
$collection->lists('id')->all();

命令和处理程序 ​

app/Commands 目录已重命名为 app/Jobs。但是，您不需要将所有命令移动到新位置，并且可以继续使用 make:command 和 handler:command Artisan 命令生成类。

同样，app/Handlers 目录已重命名为 app/Listeners，现在仅包含事件监听器。但是，您不需要移动或重命名现有的命令和事件处理程序，并且可以继续使用 handler:event 命令生成事件处理程序。

通过为 Laravel 5.0 文件夹结构提供向后兼容性，您可以将应用程序升级到 Laravel 5.1，并在方便时或团队方便时慢慢将事件和命令升级到新位置。

Blade ​

createMatcher、createOpenMatcher 和 createPlainMatcher 方法已从 Blade 编译器中移除。使用新的 directive 方法为 Laravel 5.1 中的 Blade 创建自定义指令。有关更多信息，请查阅 扩展 blade 文档。

测试 ​

将受保护的 $baseUrl 属性添加到 tests/TestCase.php 文件：

php
protected $baseUrl = 'http://localhost';

翻译文件 ​

已发布的供应商包的默认语言文件目录已移动。将任何供应商包语言文件从 resources/lang/packages/{locale}/{namespace} 移动到 resources/lang/vendor/{namespace}/{locale} 目录。例如，Acme/Anvil 包的 acme/anvil::foo 命名空间的英文语言文件将从 resources/lang/packages/en/acme/anvil/foo.php 移动到 resources/lang/vendor/acme/anvil/en/foo.php。

亚马逊 Web 服务 SDK ​

如果您使用 AWS SQS 队列驱动程序或 AWS SES 电子邮件驱动程序，您应该将已安装的 AWS PHP SDK 更新到版本 3.0。

如果您使用亚马逊 S3 文件系统驱动程序，您需要通过 Composer 更新相应的 Flysystem 包：

  • 亚马逊 S3: league/flysystem-aws-s3-v3 ~1.0

弃用 ​

以下 Laravel 功能已被弃用，并将在 2015 年 12 月发布的 Laravel 5.2 中完全移除：

  • 路由过滤器已被弃用，优先使用 中间件。
  • Illuminate\Contracts\Routing\Middleware 合同已被弃用。您的中间件不需要合同。此外，TerminableMiddleware 合同也已被弃用。无需实现接口，只需在中间件上定义一个 terminate 方法。
  • Illuminate\Contracts\Queue\ShouldBeQueued 合同已被弃用，取而代之的是 Illuminate\Contracts\Queue\ShouldQueue。
  • Iron.io "push queues" 已被弃用，优先使用典型的 Iron.io 队列和 队列监听器。
  • Illuminate\Foundation\Bus\DispatchesCommands trait 已被弃用，并重命名为 Illuminate\Foundation\Bus\DispatchesJobs。
  • Illuminate\Container\BindingResolutionException 已移至 Illuminate\Contracts\Container\BindingResolutionException。
  • 服务容器的 bindShared 方法已被弃用，取而代之的是 singleton 方法。
  • Eloquent 和查询构建器的 pluck 方法已被弃用，并重命名为 value。
  • 集合的 fetch 方法已被弃用，取而代之的是 pluck 方法。
  • array_fetch 辅助函数已被弃用，取而代之的是 array_pluck 方法。

升级到 5.0.16 ​

在您的 bootstrap/autoload.php 文件中，将 $compiledPath 变量更新为：

php
$compiledPath = __DIR__.'/../vendor/compiled.php';

服务提供者 ​

您可以从 app.php 配置文件中的服务提供者列表中移除 App\Providers\BusServiceProvider。

您可以从 app.php 配置文件中的服务提供者列表中移除 App\Providers\ConfigServiceProvider。

从 4.2 升级到 5.0 ​

全新安装，然后迁移 ​

推荐的升级方法是创建一个新的 Laravel 5.0 安装，然后将您的 4.2 站点的独特应用程序文件复制到新应用程序中。这将包括控制器、路由、Eloquent 模型、Artisan 命令、资产和其他特定于应用程序的代码文件。

首先，在本地环境中 安装一个新的 Laravel 5.0 应用程序 到一个新目录中。不要安装任何更新版本，因为我们需要先完成 5.0 的迁移步骤。我们将在下面更详细地讨论迁移过程的每个部分。

Composer 依赖和包 ​

不要忘记将任何其他 Composer 依赖项复制到您的 5.0 应用程序中。这包括第三方代码，如 SDK。

某些 Laravel 特定的包可能在初始发布时与 Laravel 5 不兼容。请与您的包维护者联系，以确定适用于 Laravel 5 的包的正确版本。一旦您添加了应用程序所需的任何其他 Composer 依赖项，请运行 composer update。

命名空间 ​

默认情况下，Laravel 4 应用程序未在应用程序代码中使用命名空间。因此，例如，所有 Eloquent 模型和控制器都简单地位于 "全局" 命名空间中。为了更快的迁移，您可以简单地将这些类保留在 Laravel 5 中的全局命名空间中。

配置 ​

迁移环境变量 ​

将新的 .env.example 文件复制到 .env，这是旧 .env.php 文件的 5.0 等效文件。在此处设置任何适当的值，如您的 APP_ENV 和 APP_KEY（您的加密密钥）、您的数据库凭据以及您的缓存和会话驱动。

此外，将您在旧 .env.php 文件中拥有的任何自定义值复制到 .env（本地环境的实际值）和 .env.example（其他团队成员的示例说明值）中。

有关环境配置的更多信息，请查看 完整文档。

exclamation

在部署 Laravel 5 应用程序之前，您需要在生产服务器上放置适当的 .env 文件和值。

配置文件 ​

Laravel 5.0 不再使用 app/config/{environmentName}/ 目录为给定环境提供特定的配置文件。相反，将任何因环境而异的配置值移动到 .env 中，然后在配置文件中使用 env('key', 'default value') 访问它们。您将在 config/database.php 配置文件中看到此示例。

将 config/ 目录中的配置文件设置为表示在所有环境中一致的值，或设置为使用 env() 加载因环境而异的值。

请记住，如果您向 .env 文件添加更多键，请在 .env.example 文件中添加示例值。这将帮助您的其他团队成员创建自己的 .env 文件。

路由 ​

将旧的 routes.php 文件复制并粘贴到新的 app/Http/routes.php 中。

控制器 ​

接下来，将所有控制器移动到 app/Http/Controllers 目录中。由于我们在本指南中不会迁移到完整的命名空间，请将 app/Http/Controllers 目录添加到 composer.json 文件的 classmap 指令中。接下来，您可以从抽象的 app/Http/Controllers/Controller.php 基类中移除命名空间。验证迁移的控制器是否扩展了此基类。

在 app/Providers/RouteServiceProvider.php 文件中，将 namespace 属性设置为 null。

路由过滤器 ​

将 app/filters.php 中的过滤器绑定复制到 app/Providers/RouteServiceProvider.php 的 boot() 方法中。在 app/Providers/RouteServiceProvider.php 中添加 use Illuminate\Support\Facades\Route; 以继续使用 Route Facade。

您不需要移动任何默认的 Laravel 4.0 过滤器，如 auth 和 csrf；它们都在这里，但作为中间件。编辑任何引用旧默认过滤器的路由或控制器（例如 ['before' => 'auth']），并将其更改为引用新的中间件（例如 ['middleware' => 'auth']）。

在 Laravel 5 中未移除过滤器。您仍然可以使用 before 和 after 绑定和使用自己的自定义过滤器。

全局 CSRF ​

默认情况下，CSRF 保护 在所有路由上启用。如果您想禁用此功能，或仅在某些路由上手动启用它，请从 App\Http\Kernel 的 middleware 数组中移除此行：

php
'App\Http\Middleware\VerifyCsrfToken',

如果您想在其他地方使用它，请将此行添加到 $routeMiddleware：

php
'csrf' => 'App\Http\Middleware\VerifyCsrfToken',

现在，您可以使用 ['middleware' => 'csrf'] 将中间件添加到单个路由/控制器。有关中间件的更多信息，请查阅 完整文档。

Eloquent 模型 ​

可以创建一个新的 app/Models 目录来存放您的 Eloquent 模型。同样，将此目录添加到 composer.json 文件的 classmap 指令中。

更新任何使用 SoftDeletingTrait 的模型以使用 Illuminate\Database\Eloquent\SoftDeletes。

Eloquent 缓存 ​

Eloquent 不再提供 remember 方法来缓存查询。您现在负责使用 Cache::remember 函数手动缓存查询。有关缓存的更多信息，请查阅 完整文档。

用户认证模型 ​

要升级您的 User 模型以适应 Laravel 5 的认证系统，请按照以下说明进行操作：

从您的 use 块中删除以下内容：

php
use Illuminate\Auth\UserInterface;
use Illuminate\Auth\Reminders\RemindableInterface;

在您的 use 块中添加以下内容：

php
use Illuminate\Auth\Authenticatable;
use Illuminate\Auth\Passwords\CanResetPassword;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\CanResetPassword as CanResetPasswordContract;

移除 UserInterface 和 RemindableInterface 接口。

将类标记为实现以下接口：

php
implements AuthenticatableContract, CanResetPasswordContract

在类声明中包含以下 trait：

php
use Authenticatable, CanResetPassword;

如果您使用了它们，请从您的 use 块和类声明中移除 Illuminate\Auth\Reminders\RemindableTrait 和 Illuminate\Auth\UserTrait。

Cashier 用户更改 ​

Laravel Cashier 使用的 trait 和接口名称已更改。请使用 Laravel\Cashier\Billable trait 代替 BillableTrait。并且，代替 Laravel\Cashier\BillableInterface 实现 Laravel\Cashier\Contracts\Billable 接口。无需进行其他方法更改。

Artisan 命令 ​

将所有命令类从旧的 app/commands 目录移动到新的 app/Console/Commands 目录。接下来，将 app/Console/Commands 目录添加到 composer.json 文件的 classmap 指令中。

然后，将 Artisan 命令列表从 start/artisan.php 复制到 app/Console/Kernel.php 文件的 commands 数组中。

数据库迁移和填充 ​

删除 Laravel 5.0 附带的两个迁移，因为您应该已经在数据库中拥有用户表。

将所有迁移类从旧的 app/database/migrations 目录移动到新的 database/migrations。将所有填充从 app/database/seeds 移动到 database/seeds。

全局 IoC 绑定 ​

如果您在 start/global.php 中有任何 服务容器 绑定，请将它们全部移动到 app/Providers/AppServiceProvider.php 文件的 register 方法中。您可能需要导入 App facade。

可选地，您可以按类别将这些绑定分解为单独的服务提供者。

视图 ​

将视图从 app/views 移动到新的 resources/views 目录。

Blade 标签更改 ​

为了默认更好的安全性，Laravel 5.0 从 {{ }} 和 {{{ }}} Blade 指令中转义所有输出。引入了一个新的 {!! !!} 指令来显示原始、未转义的输出。在升级应用程序时，最安全的选项是仅在您 确定 显示原始输出是安全的情况下使用新的 {!! !!} 指令。

但是，如果您 必须 使用旧的 Blade 语法，请在 AppServiceProvider@register 的底部添加以下行：

php
\Blade::setRawTags('{{', '}}');
\Blade::setContentTags('{{{', '}}}');
\Blade::setEscapedContentTags('{{{', '}}}');

这不应轻易进行，并可能使您的应用程序更容易受到 XSS 攻击。此外，带有 {{-- 的注释将不再有效。

翻译文件 ​

将语言文件从 app/lang 移动到新的 resources/lang 目录。

公共目录 ​

将应用程序的公共资产从 4.2 应用程序的 public 目录复制到新应用程序的 public 目录。请确保保留 5.0 版本的 index.php。

测试 ​

将测试从 app/tests 移动到新的 tests 目录。

杂项文件 ​

复制项目中的任何其他文件。例如，.scrutinizer.yml、bower.json 和其他类似的工具配置文件。

您可以将 Sass、Less 或 CoffeeScript 移动到您希望的任何位置。resources/assets 目录可能是一个不错的默认位置。

表单和 HTML 助手 ​

如果您使用表单或 HTML 助手，您将看到一个错误，指出 class 'Form' not found 或 class 'Html' not found。表单和 HTML 助手在 Laravel 5.0 中已被弃用；但是，有社区驱动的替代品，如由 Laravel Collective 维护的替代品。

例如，您可以在 composer.json 文件的 require 部分中添加 "laravelcollective/html": "~5.0"。

您还需要添加表单和 HTML facade 和服务提供者。编辑 config/app.php 并将此行添加到 'providers' 数组中：

php
'Collective\Html\HtmlServiceProvider',

接下来，将这些行添加到 'aliases' 数组中：

php
'Form' => 'Collective\Html\FormFacade',
'Html' => 'Collective\Html\HtmlFacade',

CacheManager ​

如果您的应用程序代码注入 Illuminate\Cache\CacheManager 以获取非 Facade 版本的 Laravel 缓存，请注入 Illuminate\Contracts\Cache\Repository。

分页 ​

将对 $paginator->links() 的任何调用替换为 $paginator->render()。

将对 $paginator->getFrom() 和 $paginator->getTo() 的任何调用替换为 $paginator->firstItem() 和 $paginator->lastItem()。

从对 $paginator->getPerPage()、$paginator->getCurrentPage()、$paginator->getLastPage() 和 $paginator->getTotal() 的调用中移除 "get" 前缀（例如 $paginator->perPage()）。

Beanstalk 排队 ​

Laravel 5.0 现在需要 "pda/pheanstalk": "~3.0"，而不是 "pda/pheanstalk": "~2.1"。

远程 ​

远程组件已被弃用。

Workbench ​

Workbench 组件已被弃用。

从 4.1 升级到 4.2 ​

PHP 5.4+ ​

Laravel 4.2 需要 PHP 5.4.0 或更高版本。

加密默认值 ​

在您的 app/config/app.php 配置文件中添加一个新的 cipher 选项。此选项的值应为 MCRYPT_RIJNDAEL_256。

php
'cipher' => MCRYPT_RIJNDAEL_256

此设置可用于控制 Laravel 加密功能使用的默认密码。

exclamation

在 Laravel 4.2 中，默认密码是 MCRYPT_RIJNDAEL_128（AES），被认为是最安全的密码。将密码更改回 MCRYPT_RIJNDAEL_256 是解密在 Laravel <= 4.1 中加密的 cookie/值所必需的。

软删除模型现在使用 Traits ​

如果您使用软删除模型，softDeletes 属性已被移除。您现在必须使用 SoftDeletingTrait，如下所示：

php
use Illuminate\Database\Eloquent\SoftDeletingTrait;

class User extends Eloquent
{
    use SoftDeletingTrait;
}

您还必须手动将 deleted_at 列添加到您的 dates 属性中：

php
class User extends Eloquent
{
    use SoftDeletingTrait;

    protected $dates = ['deleted_at'];
}

所有软删除操作的 API 保持不变。

exclamation

SoftDeletingTrait 不能应用于基模型。它必须用于实际的模型类。

视图/分页环境重命名 ​

如果您直接引用 Illuminate\View\Environment 类或 Illuminate\Pagination\Environment 类，请更新您的代码以引用 Illuminate\View\Factory 和 Illuminate\Pagination\Factory。这些类已重命名以更好地反映其功能。

分页呈现器上的附加参数 ​

如果您扩展了 Illuminate\Pagination\Presenter 类，抽象方法 getPageLinkWrapper 签名已更改，以添加 rel 参数：

php
abstract public function getPageLinkWrapper($url, $page, $rel = null);

Iron.Io 队列加密 ​

如果您使用 Iron.io 队列驱动程序，您需要在队列配置文件中添加一个新的 encrypt 选项：

php
'encrypt' => true

从 <= 4.1.x 升级到 4.1.29 ​

Laravel 4.1.29 改进了所有数据库驱动程序的列引用。这可以保护您的应用程序免受某些批量分配漏洞的影响，当 未 使用模型上的 fillable 属性时。如果您在模型上使用 fillable 属性来防止批量分配，您的应用程序不会受到影响。然而，如果您使用 guarded 并将用户控制的数组传递给 "update" 或 "save" 类型的函数，您应该立即升级到 4.1.29，因为您的应用程序可能面临批量分配的风险。

要升级到 Laravel 4.1.29，只需 composer update。此版本中未引入重大变更。

从 <= 4.1.25 升级到 4.1.26 ​

Laravel 4.1.26 引入了 "记住我" cookie 的安全改进。在此更新之前，如果一个记住 cookie 被另一个恶意用户劫持，即使帐户的真正所有者重置了密码、注销等，cookie 仍将保持有效。

此更改需要在 users（或等效）数据库表中添加一个新的 remember_token 列。此更改后，每次用户登录到您的应用程序时，都会为用户分配一个新的令牌。用户注销应用程序时，令牌也会刷新。此更改的影响是：如果一个 "记住我" cookie 被劫持，只需注销应用程序即可使 cookie 失效。

升级路径 ​

首先，在您的 users 表中添加一个新的、可为空的 remember_token，类型为 VARCHAR(100)、TEXT 或等效类型。

接下来，如果您使用 Eloquent 认证驱动程序，请使用以下三个方法更新您的 User 类：

php
public function getRememberToken()
{
    return $this->remember_token;
}

public function setRememberToken($value)
{
    $this->remember_token = $value;
}

public function getRememberTokenName()
{
    return 'remember_token';
}
exclamation

此更改将使所有现有的 "记住我" 会话失效，因此所有用户将被迫重新认证您的应用程序。

软件包维护者 ​

Illuminate\Auth\UserProviderInterface 接口中新增了两个方法。可以在默认驱动程序中找到示例实现：

php
public function retrieveByToken($identifier, $token);

public function updateRememberToken(UserInterface $user, $token);

Illuminate\Auth\UserInterface 也接收了在“升级路径”中描述的三个新方法。

从 4.0 升级到 4.1 ​

升级您的 Composer 依赖项 ​

要将您的应用程序升级到 Laravel 4.1，请在 composer.json 文件中将 laravel/framework 版本更改为 4.1.*。

替换文件 ​

用此存储库中的新副本替换您的 public/index.php 文件。

用此存储库中的新副本替换您的 artisan 文件。

添加配置文件和选项 ​

更新 app/config/app.php 配置文件中的 aliases 和 providers 数组。可以在此文件中找到这些数组的更新值。请务必将您的自定义和软件包服务提供者/别名添加回数组中。

从存储库中添加新的 app/config/remote.php 文件。

在 app/config/session.php 文件中添加新的 expire_on_close 配置选项。默认值应为 false。

在 app/config/queue.php 文件中添加新的 failed 配置部分。以下是该部分的默认值：

php
'failed' => [
    'database' => 'mysql', 'table' => 'failed_jobs',
],

（可选） 将 app/config/view.php 文件中的 pagination 配置选项更新为 pagination::slider-3。

控制器更新 ​

如果 app/controllers/BaseController.php 顶部有 use 语句，请将 use Illuminate\Routing\Controllers\Controller; 更改为 use Illuminate\Routing\Controller;。

密码提醒更新 ​

密码提醒已被彻底改造以提供更大的灵活性。您可以通过运行 php artisan auth:reminders-controller Artisan 命令来查看新的存根控制器。您还可以浏览更新的文档并相应地更新您的应用程序。

更新您的 app/lang/en/reminders.php 语言文件以匹配此更新文件。

环境检测更新 ​

出于安全原因，URL 域名不再用于检测您的应用程序环境。这些值很容易被伪造，并允许攻击者修改请求的环境。您应该将环境检测转换为使用机器主机名（Mac、Linux 和 Windows 上的 hostname 命令）。

更简单的日志文件 ​

Laravel 现在生成一个单一的日志文件：app/storage/logs/laravel.log。但是，您仍然可以在 app/start/global.php 文件中配置此行为。

删除重定向尾随斜杠 ​

在 bootstrap/start.php 文件中，删除对 $app->redirectIfTrailingSlash() 的调用。此方法不再需要，因为此功能现在由框架附带的 .htaccess 文件处理。

接下来，用这个新的 .htaccess 文件替换您的 Apache .htaccess 文件，该文件处理尾随斜杠。

当前路由访问 ​

当前路由现在通过 Route::current() 访问，而不是 Route::getCurrentRoute()。

Composer 更新 ​

完成上述更改后，您可以运行 composer update 函数来更新您的核心应用程序文件！如果您收到类加载错误，请尝试使用 --no-scripts 选项启用 update 命令，如下所示：composer update --no-scripts。

通配符事件监听器 ​

通配符事件监听器不再将事件附加到您的处理函数参数中。如果您需要查找触发的事件，您应该使用 Event::firing()。

版权所有 © 2024-2025 laravel.wiki