升级指南

• 从 5.2 升级到 5.3.0
• 从 5.1 升级到 5.2.0

从 5.2 升级到 5.3.0

Lumen 5.3 对底层框架结构做改动。改动的只有底层共用于 Laravel 5.3 的扩展包升级。在你升级为 Lumen 5.3 前，请按照 Laravel 5.3 的 升级指南 来升级对应正在使用的 Laravel 模块调用代码。

当你做完这些升级修改以后，请在 composer.json 文件中升级 Lumen 框架的依赖为 5.3，并运行 composer update 命令：

`"laravel/lumen-framework": "5.3.*"`

从 5.1 升级到 5.2.0

Lumen 5.2 更加专注于构建无状态 API，正因为如此，session 和视图不在包含在框架中。如果你需要这些功能，建议升级到完整版本的 Laravel 5.2。

升级 Lumen 应用程序到完整的 Laravel 框架只需要复制路由和类到新的程序中即可，因为 Laravel 和 Lumen 基本上使用同样的功能模块构成。

升级依赖

修改 composer.json 文件，把依赖版本指向 laravel/lumen-framework 5.2.* 和 vlucas/phpdotenv ~2.2。

启动文件

在启动文件 bootstrap/app.php 中，你需要修改 Dotenv::load(...) 的调用为以下：

try {
    (new Dotenv\Dotenv(__DIR__.'/../'))->load();
} catch (Dotenv\Exception\InvalidPathException $e) {
    //
}

Application contract

Lumen 不在依赖于 Illuminate\Contracts\Foundation\Application contract，所有 Application contract 类型提示的地方都应该修改为引用 Laravel\Lumen\Application。

用户授权

因为 Lumen 不再使用 session，用户认证必须通过传送 API 令牌或者标头信息。你可以新的 AuthServiceProvider 中完全控制这些逻辑，请阅读 用户认证文档 获取更多信息。

集合

Eloquent 集合

大部分的 Eloquent 集合会返回新的「Eloquent 集合」实例，但是 pluck, keys, zip, collapse, flatten 和 flip 方法会返回「集合基类 (Illuminate\Support\Collection)」实例。

保留键名

slice, chunk, 和 reverse 方法现在会保留集合的键名，如果你不想这些方法保留键名，使用 集合实例 调用 values 方法即可。

数据库

MySQL 日期

自 MySQL 5.7 以后，默认 strict 模式是开启的，所以已经不再支持 0000-00-00 00:00:00 作为默认的日期值。所有的 timestamp 类型的字段在入库的时候都应该是正确的日期格式。

你可以在数据库迁移中使用 useCurrent 方法默认使用当前时间，或者设置字段为 nullable 来接受 null 值：

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

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

$table->nullableTimestamps();

MySQL JSON 字段类型

在 MySQL 驱动下，json 字段类型现在创建真实的 JSON 字段类型，如果你没有使用 MySQL 5.7 或者以上版本的话，将无法使用此字段。你可以使用 text 字段类型作为替代。

Eloquent

日期转化

当调用模型或模型集合的 toArray 方法时，任何添加到 $casts 的属性，如 date 或 datetime，现在都会被转化为字符串。这使在 $dates 数组中制定的日期转化规则保持一致。

全局作用域

我们重写了全局作用域的实现以便于更方便的使用，全局作用域不再需要 remove 方法，因此可以在所有你使用到该方法的地方将其移除。

如果你曾在 Eloquent 查询构建器上调用过了 getQuery 方法以获取底层查询构建器实例，现在应该改为调用 toBase 方法。

如果你因为某种原因直接调用了 remove 方法，需要将其改成 $eloquentBuilder->withoutGlobalScope($scope) 这种方式来调用。

在 Eloquent 查询构建器中新增了 withoutGlobalScope 和 withoutGlobalScopes 方法，任何调用 $model->removeGlobalScopes($builder) 的地方现在都要改成 $builder->withoutGlobalScopes()。

主键

默认情况下，Eloquent 会假设你的主键是 integer 整数类型，并且会强制类型为 integer 整数类型，如果你的主键不是整数类型，请设置类属性 $incrementing 为 false：

/**
 * Indicates if the IDs are auto-incrementing.
 *
 * @var bool
 */
public $incrementing = true;

异常处理

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

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

/**
 * A list of the exception types that should not be reported.
 *
 * @var array
 */
protected $dontReport = [
    AuthorizationException::class,
    HttpException::class,
    ModelNotFoundException::class,
    ValidationException::class,
];

IronMQ

IronMQ 队列驱动被移动到自己的扩展包中：

github.com/LaravelCollective/iron-q...

文件系统

如果你使用了 Laravel 的 Flysystem，你需要注册 filesystem 绑定，在 bootstrap/app.php 文件中增加以下代码：

$app->singleton('filesystem', function ($app) {
    return $app->loadComponent(
        'filesystems',
        Illuminate\Filesystem\FilesystemServiceProvider::class,
        'filesystem'
    );
});

数据验证

ValidatesRequests trait 已经被合并到 Lumen 控制器基类使用的 ProvidesConvenienceMethods trait 中。

如果你在基础控制器以外使用了 ValidatesRequests trait 的话，你需要从 5.1 分支 里复制过来，或者直接使用 ProvidesConvenienceMethods trait。

测试

DatabaseMigrations 和 DatabaseTransactions traits 之前的文件存放位置 Illuminate\Foundation\Testing\DatabaseMigrations 和 Illuminate\Foundation\Testing\DatabaseTransactions 已经发生变动，请在你的测试中更新来使用新的命名空间：

<?php

use Laravel\Lumen\Testing\DatabaseMigrations;
use Laravel\Lumen\Testing\DatabaseTransactions;

class ExampleTest extends TestCase
{
    use DatabaseMigrations;
}