From 09580b36c646514ff6d92eb81f66a68dc310ee55 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Wed, 13 Mar 2024 16:21:41 -0400 Subject: [PATCH 1/3] DOCSP-35933: Upgrade version guide (#2755) * DOCSP-35933: Upgrade version guide * DOCSP-35933: Upgrade guide * source constant fix * wording * JS feedback * odm to library * apply phpcbf formatting * empty commit (checks) --------- Co-authored-by: norareidy --- docs/upgrade.txt | 124 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 97 insertions(+), 27 deletions(-) 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()`` From 0a425e1ee9d85c2dea3727cb93eca445cda499d7 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 13 Mar 2024 16:57:25 -0400 Subject: [PATCH 2/3] DOCSP-37601 course and release notes (#2764) * DOCSP-37601: release notes link, university course link fix --- docs/index.txt | 1 + docs/quick-start.txt | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) 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 From e915378f5c2fc8291ce5746d2357e75f83618439 Mon Sep 17 00:00:00 2001 From: Andreas Braun Date: Thu, 14 Mar 2024 10:26:13 +0100 Subject: [PATCH 3/3] Use bot access token for merge-up pull requests (#2772) --- .github/workflows/merge-up.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) 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