upgrade.txt

.. _laravel-upgrading:

=======================
Upgrade Library Version
=======================

.. facet::
   :name: genre
   :values: tutorial

.. meta::
   :keywords: php framework, odm, code example

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

On this page, you can learn how to upgrade {+odm-long+} to a new major version.
This page also includes the changes you must make to your application to upgrade
your version of the {+odm-short+} 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 :ref:`<laravel-compatibility>`
  page for this information.
- Address any breaking changes between the version of the {+odm-short+} that
  your application now uses and your planned upgrade version in the
  :ref:`<laravel-breaking-changes>` section of this guide.

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

.. code-block:: bash
   
    composer require mongodb/laravel-mongodb:{+package-version+}

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

.. _laravel-breaking-changes:

Breaking Changes
----------------

A breaking change is a modification in a convention or behavior in
a specific version of the {+odm-short+} 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.

- :ref:`laravel-breaking-changes-v5.x`
- :ref:`laravel-breaking-changes-v4.x`

.. _laravel-breaking-changes-v5.x:

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:

  .. code-block:: php
     :emphasize-lines: 8-9

     $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 :ref:`laravel-query-builder-wheredate`
  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:
  
  .. code-block:: php
     :emphasize-lines: 10-11
 
     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:
  
  .. code-block:: php
     :emphasize-lines: 9-11
 
     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);

.. _laravel-breaking-changes-v4.x:

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 <https://laravel.com/docs/10.x/upgrade>`__ 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()``