Merge 4.1 into 4.2

.github/workflows/merge-up.yml

@@ -5,12 +5,8 @@ on:
  branches:
  - "[0-9]+.[0-9]+"
 
-permissions:
- contents: write
- pull-requests: write
-
 env:
- GH_TOKEN: ${{ github.token }}
+ GH_TOKEN: ${{ secrets.MERGE_UP_TOKEN }}
 
 jobs:
  merge-up:
@@ -24,6 +20,7 @@ jobs:
  with:
  # fetch-depth 0 is required to fetch all branches, not just the branch being built
  fetch-depth: 0
+ token: ${{ secrets.MERGE_UP_TOKEN }}
 
  - name: Create pull request
  id: create-pull-request

docs/index.txt

@@ -14,6 +14,7 @@ Laravel MongoDB
  :maxdepth: 1
 
  /quick-start
+ Release Notes <https://github.com/mongodb/laravel-mongodb/releases/>
  /retrieve
  /eloquent-models
  /query-builder

docs/quick-start.txt

@@ -33,7 +33,7 @@ read and write operations on the data.
 
  You can learn how to set up a local Laravel development environment
  and perform CRUD operations by viewing the
- :mdbu-course:`Getting Started with Laravel and MongoDB </getting-started-with-laravel-and-mongodb>`
+ :mdbu-course:`Getting Started with Laravel and MongoDB </courses/getting-started-with-laravel-and-mongodb>`
  MongoDB University Learning Byte.
 
  If you prefer to connect to MongoDB by using the PHP Library driver without

docs/upgrade.txt

@@ -1,8 +1,8 @@
 .. _laravel-upgrading:
 
-=========
-Upgrading
-=========
+=======================
+Upgrade Library Version
+=======================
 
 .. facet::
  :name: genre
@@ -11,39 +11,109 @@ Upgrading
 .. meta::
  :keywords: php framework, odm, code example
 
-The PHP library uses `semantic versioning <https://semver.org/>`__. Upgrading
-to a new major version may require changes to your application.
+.. contents:: On this page
+ :local:
+ :backlinks: none
+ :depth: 1
+ :class: singlecol
 
-Upgrading from version 3 to 4
------------------------------
+Overview
+--------
 
-- Laravel 10.x is required
+On this page, you can learn how to upgrade {+odm-short+} to a new major version.
+This page also includes the changes you must make to your application to upgrade
+your object-document mapper (ODM) version without losing functionality, if applicable.
 
-- Change dependency name in your composer.json to ``"mongodb/laravel-mongodb": "^4.0"``
- and run ``composer update``
+How to Upgrade
+--------------
 
-- Change namespace from ``Jenssegers\Mongodb\`` to ``MongoDB\Laravel\``
- in your models and config
+Before you upgrade, perform the following actions:
 
-- Remove support for non-Laravel projects
+- 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 {+odm-short+} that
+ your application currently uses and your planned upgrade version in the
+ :ref:`<laravel-breaking-changes>` section of this guide.
 
-- Replace ``$dates`` with ``$casts`` in your models
+To upgrade your library version, run the following command in your application's 
+directory:
 
-- Call ``$model->save()`` after ``$model->unset('field')`` to persist the change
+.. code-block:: bash
+
+ composer require mongodb/laravel-mongodb:{+package-version+}
 
-- Replace calls to ``Query\Builder::whereAll($column, $values)`` with
- ``Query\Builder::where($column, 'all', $values)``
+To upgrade to a different version of the library, replace the information after
+``laravel-mongodb:`` with your preferred version number.
 
-- ``Query\Builder::delete()`` doesn't accept ``limit()`` other than ``1`` or ``null``.
+.. _laravel-breaking-changes:
 
-- ``whereDate``, ``whereDay``, ``whereMonth``, ``whereYear``, ``whereTime``
- now use MongoDB operators on date fields
+Breaking Changes
+----------------
 
-- Replace ``Illuminate\Database\Eloquent\MassPrunable`` with ``MongoDB\Laravel\Eloquent\MassPrunable``
- in your models
+A breaking change is a modification in a convention or behavior in
+a specific version of {+odm-short+} that might prevent your application
+from working as expected.
 
-- Remove calls to not-supported methods of ``Query\Builder``: ``toSql``,
- ``toRawSql``, ``whereColumn``, ``whereFullText``, ``groupByRaw``,
- ``orderByRaw``, ``unionAll``, ``union``, ``having``, ``havingRaw``,
- ``havingBetween``, ``whereIntegerInRaw``, ``orWhereIntegerInRaw``,
- ``whereIntegerNotInRaw``, ``orWhereIntegerNotInRaw``.
+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.
+
+.. _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()``