升级指南

• 升级到 5.0.16
• 从 4.2 升级到 5.0
• 从 4.1 升级到 4.2
• 从 <= 4.1.x 升级到 4.1.29
• 从 <= 4.1.25 升级到 4.1.26
• 从 4.0 升级到 4.1

升级到 5.0.16

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

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

从 4.2 升级到 5.0

全新安装，然后迁移

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

首先，在本地环境中安装一个新的 Laravel 5 应用到一个新的目录中。我们将在下面更详细地讨论迁移过程的每个部分。

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（其他团队成员的示例说明值）。

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

在部署你的 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 数组中删除此行：

'App\Http\Middleware\VerifyCsrfToken',

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

'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 块中删除以下内容：

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

将以下内容添加到你的 use 块中：

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 接口。

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

implements AuthenticatableContract, CanResetPasswordContract

在类声明中包含以下特性：

use Authenticatable, CanResetPassword;

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

Cashier 用户更改

Laravel Cashier 使用的特性和接口名称已更改。使用 Laravel\Cashier\Billable 特性代替 BillableTrait。并且，使用 Laravel\Cashier\Contracts\Billable 接口代替 Laravel\Cashier\BillableInterface。不需要其他方法更改。

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 中有任何 IoC 绑定，将它们全部移动到 app/Providers/AppServiceProvider.php 文件的 register 方法中。你可能需要导入 App facade。

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

视图

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

Blade 标签更改

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

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

\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' 数组中添加此行：

'Collective\Html\HtmlServiceProvider',

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

'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"。

远程

远程组件已被弃用。

工作台

工作台组件已被弃用。

从 4.1 升级到 4.2

PHP 5.4+

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

加密默认值

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

'cipher' => MCRYPT_RIJNDAEL_256

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

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

软删除模型现在使用特性

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

use Illuminate\Database\Eloquent\SoftDeletingTrait;

class User extends Eloquent {
	use SoftDeletingTrait;
}

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

class User extends Eloquent {
	use SoftDeletingTrait;

	protected $dates = ['deleted_at'];
}

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

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

视图/分页环境重命名

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

分页呈现器上的额外参数

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

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

Iron.Io 队列加密

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

'encrypt' => true

从 <= 4.1.x 升级到 4.1.29

Laravel 4.1.29 改进了所有数据库驱动的列引用。这保护你的应用在不使用模型上的 fillable 属性时免受一些批量分配漏洞的影响。如果你正在使用模型上的 fillable 属性来防止批量分配，你的应用不易受攻击。然而，如果你正在使用 guarded 并将用户控制的数组传递给“更新”或“保存”类型的函数，你应该立即升级到 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 类：

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

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

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

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

包维护者

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

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 配置部分。以下是该部分的默认值：

'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 文件处理。

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

当前路由访问

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

Composer 更新

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

通配符事件监听器

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