Docs Menu
Docs Home
/ / /
Laravel MongoDB

Upgrade Library Version

On this page

  • Overview
  • How to Upgrade
  • Breaking Changes
  • Version 5.x Breaking Changes
  • Version 4.x Breaking Changes

On this page, you can learn how to upgrade Laravel MongoDB to a new major version. This page also includes the changes you must make to your application to upgrade your version of the Laravel Integration without losing functionality, if applicable.

Before you upgrade, perform the following actions:

  • Ensure the new library version is compatible with the MongoDB Server version your application connects to and the version of Laravel that your application runs on. See the Compatibility page for this information.

  • Address any breaking changes between the version of the Laravel Integration that your application now uses and your planned upgrade version in the Breaking Changes section of this guide.

To upgrade your library version, run the following command in your application's directory:

composer require mongodb/laravel-mongodb:5.1

To upgrade to a different version of the library, replace the information after laravel-mongodb: with your preferred version number.

A breaking change is a modification in a convention or behavior in a specific version of the Laravel Integration that might prevent your application from working as expected.

The breaking changes in this section are categorized by the major version releases that introduced them. When upgrading library versions, address all the breaking changes between your current version and the planned upgrade version.

This library version introduces the following breaking changes:

  • The query builder returns results as 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().

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

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

Back

Next Steps