升级库版本

本页内容

概述

如何升级
重大变更
5.x 版本重大变更
4.x 版本重大变更

概述

在本页，您可以学习如何将Laravel MongoDB升级到新的大版本。本页还包括您必须对应用程序进行的更改，以在保留功能的情况下升级Laravel集成版本（如果适用）。

如何升级

在升级之前，请执行以下操作

确保新库版本与您的应用程序连接的MongoDB服务器版本以及应用程序运行的Laravel版本兼容。有关信息，请参阅兼容性页面。
处理应用程序现在使用的Laravel集成版本与您计划升级的版本之间的任何重大更改，请参阅本指南的重大更改部分。

要升级库版本，请在应用程序目录中运行以下命令

composer require mongodb/laravel-mongodb:5.1

要升级到库的另一个版本，将laravel-mongodb:后面的信息替换为您喜欢的版本号。

重大变更

重大变更是指在 Laravel 集成特定版本中修改了约定或行为，这可能会阻止您的应用程序按预期工作。

本节中的重大变更按引入它们的版本的主要版本进行分类。在升级库版本时，处理当前版本和计划升级版本之间的所有重大变更。

5.x 版本重大变更
4.x 版本重大变更

版本 5.x 重大变更

此库版本引入以下重大变更

查询构建器将结果返回为 stdClass 对象，而不是数组。此更改要求您在处理查询结果时将数组访问更改为属性访问。

以下代码显示了如何检索查询结果并从旧版本与 v5.0 的结果对象中访问属性。

$document = DB::table('accounts')
    ->where('name', 'Anita Charles')
    ->first();
// older versions
$document['balance'];
// v5.0
$document->balance;

移除了以下类的支持
- MongoDB\Laravel\Auth\DatabaseTokenRepository。取而代之的是，使用默认的 Illuminate\Queue\Failed\DatabaseFailedJobProvider 类并指定 MongoDB 连接。
- MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider。取而代之的是，使用默认的 Illuminate\Queue\Failed\DatabaseFailedJobProvider 类并指定 MongoDB 连接。
在查询中使用 DateTimeInterface 对象（包括 Carbon），库将 DateTimeInterface 转换为 MongoDB\BSON\UTCDateTime 对象。此转换适用于传递给 where() 方法或传递给 insert() 和 update() 方法的查询过滤器中的 DateTimeInterface 对象。
要查看将 Carbon 对象传递给 DB::where() 方法的示例，请参阅查询构建器指南中的匹配日期示例部分。
在查询结果中，库将 BSON UTCDateTime 对象转换为 Carbon 日期类，并应用默认时区。
在v5.1版本中，该库在实体化Model实例之前，还会将转换应用于Model::raw()方法的结果。
id是MongoDB文档中_id字段的别名，并且库会自动在查询数据时在id和_id之间进行转换。查询结果对象包含一个id字段来表示文档的_id字段。由于这种行为，您的文档中不能存在两个不同的id和_id字段。
在v5.1版本中，该库在实体化Model实例之前，还会将转换应用于Model::raw()方法的结果。在传递复杂的查询过滤器时，请使用DB::where()方法而不是Model::raw()。

移除了对$collection属性的支持。以下代码显示了如何在旧版本（与v5.0相比）中将MongoDB集合分配给User类中的变量。

use MongoDB\Laravel\Eloquent\Model;
class User extends Model
{
    protected $keyType = 'string';
    // older versions
    protected $collection = 'app_user';
    // v5.0
    protected $table = 'app_user';
    ...
}

本版本还对访问MongoDB集合的关联DB和Schema方法进行了修改。以下代码显示了如何在旧版本（与v5.0相比）中访问app_user集合。

use Illuminate\Support\Facades\Schema;
use Illuminate\Support\Facades\DB;
use MongoDB\Laravel\Schema\Blueprint;
// older versions
Schema::collection('app_user', function (Blueprint $collection) { ... });
DB::collection('app_user')->find($id);
// v5.0
Schema::table('app_user', function (Blueprint $table) { ... });
DB::table('app_user')->find($id);

4.x版本破坏性更改

此库版本引入以下重大变更

最低Laravel版本现在是10.0。有关升级Laravel版本的说明，请参阅Laravel文档中的升级指南。
依赖项名称现在为 "mongodb/laravel-mongodb"。请确保您的 composer.json 文件中的依赖项名称是 "mongodb/laravel-mongodb": "^4.0"。然后，运行 composer update。
命名空间现在为 MongoDB\Laravel\。请确保将您的模型和配置文件中的命名空间从 Jenssegers\Mongodb\ 更改为 MongoDB\Laravel\。
移除了对非Laravel项目的支持。
移除了对 $dates 属性的支持。请确保将您的模型文件中所有 $dates 实例更改为 $casts。
Model::unset($field) 不会保留更改。请确保在所有对 Model::unset($field) 的调用之后都跟着调用 Model::save()。
移除了 Query\Builder::whereAll($column, $values) 方法。请确保将所有对 Query\Builder::whereAll($column, $values) 的调用替换为 Query\Builder::where($column, 'all', $values)。
Query\Builder::delete() 可以删除一个或所有文档。请确保将只有值 1 或 null 传递给 limit()。
whereDate()、whereDay()、whereMonth()、whereYear() 和 whereTime() 方法现在在日期字段上使用MongoDB运算符。
添加了 MongoDB\Laravel\Eloquent\MassPrunable 特性。请确保将您的模型中所有 Illuminate\Database\Eloquent\MassPrunable 实例替换为 MongoDB\Laravel\Eloquent\MassPrunable。
移除了以下 Query\Builder 方法
- toSql()
- toRawSql()
- whereColumn()
- whereFullText()
- groupByRaw()
- orderByRaw()
- unionAll()
- union()
- having()
- havingRaw()
- havingBetween()
- whereIntegerInRaw()
- orWhereIntegerInRaw()
- whereIntegerNotInRaw()
- orWhereIntegerNotInRaw()

兼容性