Upgrade Library Version

Version 5.x Breaking Changes

This library version introduces the following breaking changes:

• The query builder returns results as stdClass objects instead of as arrays. This change requires that you change array access to property access when interacting with query results.

  The following code shows how to retrieve a query result and access a property from the result object in older versions compared to v5.0:

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

• Removes support for the following classes:

  • MongoDB\Laravel\Auth\DatabaseTokenRepository. Instead, use the default Illuminate\Queue\Failed\DatabaseFailedJobProvider class and specify a connection to MongoDB.

  • MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider. Instead, use the default Illuminate\Queue\Failed\DatabaseFailedJobProvider class and specify a connection to MongoDB.

• When using a DateTimeInterface object, including Carbon, in a query, the library converts the DateTimeInterface to a MongoDB\BSON\UTCDateTime object. This conversion applies to DateTimeInterface objects passed as query filters to the where() method or as data passed to the insert() and update() methods.

  To view an example that passes a Carbon object to the DB::where() method, see the Match Dates Example section of the Query Builder guide.

• In query results, the library converts BSON UTCDateTime objects to Carbon date classes, applying the default timezone.

  In v5.1, the library also performs this conversion to the Model::raw() method results before hydrating a Model instance.

• id is an alias for the _id field in MongoDB documents, and the library automatically converts between id and _id when querying data. The query result object includes an id field to represent the document's _id field. Because of this behavior, you cannot have two separate id and _id fields in your documents.

  In v5.1, the library also performs this conversion to the Model::raw() method results before hydrating a Model instance. When passing a complex query filter, use the DB::where() method instead of Model::raw().

  Starting in v5.3, you can disable automatic conversion of id to _id for embedded documents. To learn more, see the Disable Use of id Field Name Conversion section of the Connection Options guide.

• Removes support for the $collection property. The following code shows how to assign a MongoDB collection to a variable in your User class in older versions compared to v5.0:

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

  This release also modifies the associated DB and Schema methods for accessing a MongoDB collection. The following code shows how to access the app_user collection in older versions compared to v5.0:

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

Version 4.x Breaking Changes

This library version introduces the following breaking changes:

• Minimum Laravel version is now 10.0. For instructions on upgrading your Laravel version, see the Upgrade Guide in the Laravel documentation.

• Dependency name is now "mongodb/laravel-mongodb". Ensure that the dependency name in your composer.json file is "mongodb/laravel-mongodb": "^4.0". Then, run composer update.

• Namespace is now MongoDB\Laravel\. Ensure that you change the namespace from Jenssegers\Mongodb\ to MongoDB\Laravel\ in your models and config files.

• Removes support for non-Laravel projects.

• Removes support for the $dates property. Ensure that you change all instances of $dates to $casts in your model files.

• Model::unset($field) does not persist the change. Ensure that you follow all calls to Model::unset($field) with Model::save().

• Removes the Query\Builder::whereAll($column, $values) method. Ensure that you replace all calls to Query\Builder::whereAll($column, $values) with Query\Builder::where($column, 'all', $values).

• Query\Builder::delete() can delete one or all documents. Ensure that you pass only the values 1 or null to limit().

• whereDate(), whereDay(), whereMonth(), whereYear(), and whereTime() methods now use MongoDB operators on date fields.

• Adds the MongoDB\Laravel\Eloquent\MassPrunable trait. Ensure that you replace all instances of Illuminate\Database\Eloquent\MassPrunable with MongoDB\Laravel\Eloquent\MassPrunable in your models.

• Removes support for the following Query\Builder methods:

  • toSql()

  • toRawSql()

  • whereColumn()

  • whereFullText()

  • groupByRaw()

  • orderByRaw()

  • unionAll()

  • union()

  • having()

  • havingRaw()

  • havingBetween()

  • whereIntegerInRaw()

  • orWhereIntegerInRaw()

  • whereIntegerNotInRaw()

  • orWhereIntegerNotInRaw()

Version 5.8 Deprecations

Starting in Laravel MongoDB v5.8, the array cast type for Eloquent model attributes is deprecated. Using array as a cast type stores attribute values as JSON-encoded strings in MongoDB, which is not the native BSON format. When you write to an attribute that uses the array cast, the library emits the following deprecation notice:

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.

The deprecation notice includes the name of the affected attribute and model class.

To migrate your model attributes for future versions, use one of the following options:

• Remove the array cast (recommended). Without a cast type, MongoDB natively stores and retrieves PHP arrays as BSON arrays. The following code shows how to update your model:

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

• Replace array with json to explicitly keep JSON string storage:

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

If a field already holds a native BSON array and the model still uses the array cast, the library reads it back correctly.