Upgrade Library Version
On this page
Overview
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.
How to Upgrade
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.
Breaking Changes
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.
Version 5.x Breaking Changes
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 defaultIlluminate\Queue\Failed\DatabaseFailedJobProvider
class and specify a connection to MongoDB.MongoDB\Laravel\Queue\Failed\MongoFailedJobProvider
. Instead, use the defaultIlluminate\Queue\Failed\DatabaseFailedJobProvider
class and specify a connection to MongoDB.
When using a
DateTimeInterface
object, includingCarbon
, in a query, the library converts theDateTimeInterface
to aMongoDB\BSON\UTCDateTime
object. This conversion applies toDateTimeInterface
objects passed as query filters to thewhere()
method or as data passed to theinsert()
andupdate()
methods.To view an example that passes a
Carbon
object to theDB::where()
method, see the Match Dates Example section of the Query Builder guide.In query results, the library converts BSON
UTCDateTime
objects toCarbon
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 betweenid
and_id
when querying data. The query result object includes anid
field to represent the document's_id
field. Because of this behavior, you cannot have two separateid
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 theDB::where()
method instead ofModel::raw()
.Removes support for the
$collection
property. The following code shows how to assign a MongoDB collection to a variable in yourUser
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
andSchema
methods for accessing a MongoDB collection. The following code shows how to access theapp_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 yourcomposer.json
file is"mongodb/laravel-mongodb": "^4.0"
. Then, runcomposer update
.Namespace is now
MongoDB\Laravel\
. Ensure that you change the namespace fromJenssegers\Mongodb\
toMongoDB\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 toModel::unset($field)
withModel::save()
.Removes the
Query\Builder::whereAll($column, $values)
method. Ensure that you replace all calls toQuery\Builder::whereAll($column, $values)
withQuery\Builder::where($column, 'all', $values)
.Query\Builder::delete()
can delete one or all documents. Ensure that you pass only the values1
ornull
tolimit()
.whereDate()
,whereDay()
,whereMonth()
,whereYear()
, andwhereTime()
methods now use MongoDB operators on date fields.Adds the
MongoDB\Laravel\Eloquent\MassPrunable
trait. Ensure that you replace all instances ofIlluminate\Database\Eloquent\MassPrunable
withMongoDB\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()