升级库版本

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

版本 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 in
MongoDB, which is not the native format. Remove the cast to
store native BSON arrays. If you must keep JSON string
storage, 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 storage
  protected $casts = [
      // other casts...
  ];

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

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

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