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