升级 Laravel 集成库版本

5.x 版重大更改

此库版本引入了以下重大更改：

• 查询构建器将结果作为 stdClass 对象而不是数组返回。此更改要求您在与查询结果交互时将大量访问权限更改为属性访问权限。

  以下代码展示了如何在旧版本（与 v 5.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()方法的DateTimeInterface对象，或作为数据传递给insert()和update()方法的 对象。

  要查看将Carbon对象传递给DB::where()方法的示例，请参阅 查询生成器指南的匹配日期示例部分。

• 在查询结果中，该库将BSON UTCDateTime对象转换为Carbon日期类，并应用默认时区。

  在 v 5.1 中，在水合模型实例之前，该库还会对 Model::raw() 方法结果执行此转换。

• id 是MongoDB文档中_id字段的别名，查询数据时该库会自动在id和_id之间进行转换。 查询结果对象包含一个id字段来表示文档的_id字段。 由于这种行为，您的文档中不能有两个单独的id和_id字段。

  在 v 5.1 中，在水合模型实例之前，该库还会对 Model::raw() 方法结果执行此转换。传递复杂查询过滤时，请使用 DB::where() 方法而不是 Model::raw()。

  从 v5.3 开始，您可以为嵌入式文档禁用从 id 自动转换为 _id 的功能。要学习；了解更多信息，请参阅 连接选项指南的禁用ID字段名称转换部分。

• 删除支持$collection属性的支持。 以下代码展示了如何在旧版本（与 v 5.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方法。 以下代码展示了如何在旧版本与 v 5.0中访问权限app_user集合：

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

• 从 v5.9 开始，最低 Laravel 版本为 12.0。有关升级 Laravel 版本的说明，请参阅 Laravel 文档中的升级指南。

• 从 v5.9 开始，最低 PHP 版本为 8.2。在升级之前，请确认您的应用程序运行在受支持的 PHP 版本上。

• 从 v5.11 开始，在以下条件下，where() 方法会将数组值解释为字面值：

  • 您向 where() 方法传递了 3 个参数。

  • 其中一个参数是 = 操作符。

  • 另一个参数是数组值。

  在早期版本中，Laravel Integration 将数组作为操作符文档传递给 MongoDB，这可能会注入意外的查询条件。要学习更多信息，请参阅查询构建者指南中的数组值以及相关的CVE-2026-88022 问题。

• 从 v5.12 开始，prefix 连接设置适用于库的模式构建器中的模式方法，就像在 Laravel 中一样。hasTable()、dropIfExists()、getColumns() 和 getIndexes() 方法现在将前缀应用于您传递的集合名称。getColumnListing()、getIndexListing() 和 hasIndex() 也是如此，它们委托给 getColumns() 和 getIndexes()。要了解有关此设置的更多信息，请参阅 Laravel 数据库连接配置。

  如果您的应用程序将带前缀的集合名称传递给这些方法，请改用不带前缀的名称。示例，如果您的连接使用 prefix 为 app_，请调用 Schema::hasTable('users') 而不是 Schema::hasTable('app_users')。

  hasCollection() 以及 getCollection() 并不属于 Laravel 的模式 API。它们继续采用存储在 MongoDB 中的集合名称，因此这些方法可以使用带前缀的名称。

• 此版本还修复了一个迁移问题：在 v5.12 之前，带有前缀的 php artisan migrate 会在每次运行时重新创建迁移存储库，并再次运行所有迁移。

版本 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()

版本 5.8弃用

从 Laravel MongoDB v5.8 开始，Eloquent 模型属性的 array 投射类型已弃用。使用 array 作为投射类型可将属性值作为 JSON 编码字符串存储在 MongoDB 中，而这不是原生 BSON 格式。当您向使用 array 投射的属性写入时，该库会发出以下弃用通知：

USER DEPRECATED  The "array" cast on attribute "<attribute>"of model "<Model>" stores values as a JSON-encoded string inMongoDB, which is not the native format. Remove the cast tostore native BSON arrays. If you must keep JSON stringstorage, use the "json" cast explicitly.

废弃通知包括受影响的属性和模型类的名称。

要将模型属性迁移到未来版本，请使用以下选项之一：

• 删除 array 转型（推荐）。在没有转型类型的情况下，MongoDB 可以将 PHP 数组存储和检索为 BSON 数组。以下代码展示如何更新模型：

  // Before (deprecated in v5.8)protected $casts = [    'options' => 'array',];
  // After: remove the cast to use native BSON storageprotected $casts = [    // other casts...];

• 将 array 替换为 json 以明确保留 JSON string 存储：

  protected $casts = [    'options' => 'json',];

如果字段已经包含原生 BSON 数组，并且模型仍然使用 array 转换，则库可以正确读回。