diff --git a/.github/workflows/merge-up.yml b/.github/workflows/merge-up.yml
index a44a8501c..215c2d9ac 100644
--- a/.github/workflows/merge-up.yml
+++ b/.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
diff --git a/docs/index.txt b/docs/index.txt
index cd210fed2..febdb9371 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -14,6 +14,7 @@ Laravel MongoDB
:maxdepth: 1
/quick-start
+ Release Notes
/retrieve
/eloquent-models
/query-builder
diff --git a/docs/quick-start.txt b/docs/quick-start.txt
index b5f9166ae..d672f3e31 100644
--- a/docs/quick-start.txt
+++ b/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 `
+ :mdbu-course:`Getting Started with Laravel and MongoDB `
MongoDB University Learning Byte.
If you prefer to connect to MongoDB by using the PHP Library driver without
diff --git a/docs/upgrade.txt b/docs/upgrade.txt
index 8148fbdfc..1aeba2be3 100644
--- a/docs/upgrade.txt
+++ b/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 `__. 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:``
+ 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:`` 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 `__ 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()``