DOCSP-44949 Relabel TOC

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,5 +6,3 @@ This will help reviewers and should be a good start for the documentation.
 ### Checklist
 
 - [ ] Add tests and ensure they pass
-- [ ] Add an entry to the CHANGELOG.md file
-- [ ] Update documentation for new features

.github/workflows/merge-up.yml

@@ -3,7 +3,7 @@ name: Merge up
 on:
   push:
     branches:
-      - "[0-9]+.[0-9]+"
+      - "[0-9]+.[0-9x]+"
 
 env:
   GH_TOKEN: ${{ secrets.MERGE_UP_TOKEN }}
@@ -28,4 +28,5 @@ jobs:
         with:
           ref: ${{ github.ref_name }}
           branchNamePattern: '<major>.<minor>'
+          devBranchNamePattern: '<major>.x'
           enableAutoMerge: true

.github/workflows/release.yml

@@ -32,6 +32,7 @@ jobs:
         run: |
           echo RELEASE_VERSION=${{ inputs.version }} >> $GITHUB_ENV
           echo RELEASE_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' -f-2) >> $GITHUB_ENV
+          echo DEV_BRANCH=$(echo ${{ inputs.version }} | cut -d '.' - f-1).x >> $GITHUB_ENV
 
       - name: "Ensure release tag does not already exist"
         run: |
@@ -40,12 +41,31 @@ jobs:
             exit 1
           fi
 
-      - name: "Fail if branch names don't match"
-        if: ${{ github.ref_name != env.RELEASE_BRANCH }}
+      # For patch releases (A.B.C where C != 0), we expect the release to be
+      # triggered from the A.B maintenance branch
+      - name: "Fail if patch release is created from wrong release branch"
+        if: ${{ !endsWith(inputs.version, '.0') && env.RELEASE_BRANCH != github.ref_name }}
         run: |
           echo '❌ Release failed due to branch mismatch: expected ${{ inputs.version }} to be released from ${{ env.RELEASE_BRANCH }}, got ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY
           exit 1
 
+      # For non-patch releases (A.B.C where C == 0), we expect the release to
+      # be triggered from the A.x maintenance branch or A.x development branch
+      - name: "Fail if non-patch release is created from wrong release branch"
+        if: ${{ endsWith(inputs.version, '.0') && env.RELEASE_BRANCH != github.ref_name && env.DEV_BRANCH != github.ref_name }}
+        run: |
+          echo '❌ Release failed due to branch mismatch: expected ${{ inputs.version }} to be released from ${{ env.RELEASE_BRANCH }} or ${{ env.DEV_BRANCH }}, got ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY
+          exit 1
+
+      # If a non-patch release is created from its A.x development branch,
+      # create the A.B maintenance branch from the current one and push it
+      - name: "Create and push new release branch for non-patch release"
+        if: ${{ endsWith(inputs.version, '.0') && env.DEV_BRANCH == github.ref_name }}
+        run: |
+          echo '🆕 Creating new release branch ${RELEASE_BRANCH} from ${{ github.ref_name }}' >> $GITHUB_STEP_SUMMARY
+          git checkout -b ${RELEASE_BRANCH}
+          git push origin ${RELEASE_BRANCH}
+
       #
       # Preliminary checks done - commence the release process
       #

.github/workflows/static-analysis.yml

@@ -23,6 +23,7 @@ jobs:
         php:
           - '8.1'
           - '8.2'
+          - '8.3'
     steps:
       - name: Checkout
         uses: actions/checkout@v4

CONTRIBUTING.md

@@ -70,8 +70,7 @@ If the project maintainer has any additional requirements, you will find them li
 
 - **Add tests!** - Your patch won't be accepted if it doesn't have tests.
 
-- **Document any change in behaviour** - Make sure the documentation is kept up-to-date, and update the changelog for
-new features and bug fixes.
+- **Document any change in behaviour** - Make sure the documentation is kept up-to-date.
 
 - **Consider our release cycle** - We try to follow [SemVer v2.0.0](https://semver.org/). Randomly breaking public APIs is not an option.
 

composer.json

@@ -30,7 +30,8 @@
         "illuminate/database": "^10.30|^11",
         "illuminate/events": "^10.0|^11",
         "illuminate/support": "^10.0|^11",
-        "mongodb/mongodb": "^1.15"
+        "mongodb/mongodb": "^1.18",
+        "symfony/http-foundation": "^6.4|^7"
     },
     "require-dev": {
         "mongodb/builder": "^0.2",
@@ -41,7 +42,8 @@
         "mockery/mockery": "^1.4.4",
         "doctrine/coding-standard": "12.0.x-dev",
         "spatie/laravel-query-builder": "^5.6",
-        "phpstan/phpstan": "^1.10"
+        "phpstan/phpstan": "^1.10",
+        "rector/rector": "^1.2"
     },
     "conflict": {
         "illuminate/bus": "< 10.37.2"
@@ -68,7 +70,6 @@
         "laravel": {
             "providers": [
                 "MongoDB\\Laravel\\MongoDBServiceProvider",
-                "MongoDB\\Laravel\\MongoDBQueueServiceProvider",
                 "MongoDB\\Laravel\\MongoDBBusServiceProvider"
             ]
         }
@@ -77,7 +78,8 @@
         "test": "phpunit",
         "test:coverage": "phpunit --coverage-clover ./coverage.xml",
         "cs": "phpcs",
-        "cs:fix": "phpcbf"
+        "cs:fix": "phpcbf",
+        "rector": "rector"
     },
     "config": {
         "allow-plugins": {

docs/compatibility.txt

@@ -15,7 +15,7 @@ Compatibility
    :class: singlecol
 
 .. meta::
-   :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2
+   :keywords: laravel 9, laravel 10, laravel 11, 4.0, 4.1, 4.2, 5.0, 5.1
 
 Laravel Compatibility
 ---------------------

docs/eloquent-models.txt

@@ -11,6 +11,12 @@ Eloquent Models
 .. meta::
    :keywords: php framework, odm
 
+.. toctree::
+
+   Eloquent Model Class </eloquent-models/model-class/>
+   Relationships </eloquent-models/relationships>
+   Schema Builder </eloquent-models/schema-builder>
+
 Eloquent models are part of the Laravel Eloquent object-relational
 mapping (ORM) framework, which lets you to work with data in a relational
 database by using model classes and Eloquent syntax. The {+odm-short+} extends
@@ -26,9 +32,3 @@ the {+odm-short+} to work with MongoDB in the following ways:
   between models
 - :ref:`laravel-schema-builder` shows how to manage indexes on your MongoDB
   collections by using Laravel migrations
-
-.. toctree::
-
-   /eloquent-models/model-class/
-   Relationships </eloquent-models/relationships>
-   Schema Builder </eloquent-models/schema-builder>

docs/eloquent-models/model-class.txt

@@ -216,8 +216,8 @@ model attribute, stored in MongoDB as a :php:`MongoDB\\BSON\\UTCDateTime
    To learn more, see `Attribute Casting <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-mutators#attribute-casting>`__
    in the Laravel documentation.
 
-This conversion lets you use the PHP :php:`DateTime <class.datetime>`
-or the `Carbon class <https://carbon.nesbot.com/docs/>`__ to work with dates
+This conversion lets you use the PHP :php:`DateTime
+<class.datetime>` class to work with dates
 in this field. The following example shows a Laravel query that uses the
 casting helper on the model to query for planets with a ``discovery_dt`` of
 less than three years ago:
@@ -226,6 +226,13 @@ less than three years ago:
 
    Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get();
 
+.. note:: Carbon Date Class
+
+   Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB
+   are returned as `Carbon <https://carbon.nesbot.com/docs/>`__ date
+   classes in query results. The {+odm-short+} applies the default
+   timezone when performing this conversion.
+
 To learn more about MongoDB's data types, see :manual:`BSON Types </reference/bson-types/>`
 in the Server manual.
 
@@ -295,12 +302,8 @@ including this trait, you can make the third-party class compatible with
 MongoDB.
 
 When you apply the ``DocumentModel`` trait to a model class, you must
-declare the following properties in your class:
-
-- ``$primaryKey = '_id'``, because the ``_id`` field uniquely
-  identifies MongoDB documents
-- ``$keyType = 'string'``, because the {+odm-short+} casts MongoDB
-  ``ObjectId`` values to type ``string``
+set the  ``$keyType`` property to ``'string'`` as the {+odm-short+}
+casts MongoDB ``ObjectId`` values to type ``string``.
 
 Extended Class Example
 ~~~~~~~~~~~~~~~~~~~~~~

docs/fundamentals.txt

@@ -15,11 +15,11 @@ Fundamentals
    :titlesonly:
    :maxdepth: 1
 
-   /fundamentals/connection
-   /fundamentals/database-collection
-   /fundamentals/read-operations
-   /fundamentals/write-operations
-   /fundamentals/aggregation-builder
+   Connections </fundamentals/connection>
+   Databases & Collections </fundamentals/database-collection>
+   Read Operations </fundamentals/read-operations>
+   Write Operations </fundamentals/write-operations>
+   Aggregation Builder </fundamentals/aggregation-builder>
 
 Learn more about the following concepts related to {+odm-long+}:
 

docs/fundamentals/connection.txt

@@ -13,9 +13,9 @@ Connections
 
 .. toctree::
 
-   /fundamentals/connection/connect-to-mongodb
-   /fundamentals/connection/connection-options
-   /fundamentals/connection/tls
+   Connection Guide </fundamentals/connection/connect-to-mongodb>
+   Connection Options </fundamentals/connection/connection-options>
+   Configure TLS </fundamentals/connection/tls>
 
 .. contents:: On this page
    :local:

docs/fundamentals/connection/connect-to-mongodb.txt

@@ -136,10 +136,8 @@ For a MongoDB database connection, you can specify the following details:
 
           'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'],
 
-       .. note::
-
-          This option does not accept hosts that use the DNS seedlist
-          connection format.
+       | This option does not accept hosts that use the DNS seedlist
+         connection format.
 
    * - ``database``
      - Specifies the name of the MongoDB database to read and write to.

docs/fundamentals/database-collection.txt

@@ -258,16 +258,21 @@ schema builder method in your application.
 You can also use the following methods to return more information about the
 collection fields:
 
-- ``Schema::hasColumn(string $<collection>, string $<field name>)``: checks if the specified field exists
-  in at least one document
-- ``Schema::hasColumns(string $<collection>, string[] $<field names>)``: checks if each specified field exists
-  in at least one document
+- ``Schema::hasColumn(string $<collection>, string $<field name>)``:
+  checks if the specified field exists in at least one document
+- ``Schema::hasColumns(string $<collection>, string[] $<field names>)``:
+  checks if each specified field exists in at least one document
 
-.. note::
+MongoDB is a schemaless database, so the preceding methods query the collection
+data rather than the database schema. If the specified collection doesn't exist
+or is empty, these methods return a value of ``false``.
+
+.. note:: id Alias
 
-   MongoDB is a schemaless database, so the preceding methods query the collection
-   data rather than the database schema. If the specified collection doesn't exist
-   or is empty, these methods return a value of ``false``.
+   Starting in {+odm-long+} v5.1, the ``getColumns()`` method represents
+   the ``_id`` field name in a MongoDB collection as the alias ``id`` in
+   the returned list of field names. You can pass either ``_id`` or
+   ``id`` to the ``hasColumn()`` and ``hasColumns()`` methods.
 
 Example
 ```````

docs/includes/auth/PersonalAccessToken.php

@@ -11,6 +11,5 @@ class PersonalAccessToken extends SanctumToken
 
     protected $connection = 'mongodb';
     protected $table = 'personal_access_tokens';
-    protected $primaryKey = '_id';
     protected $keyType = 'string';
 }

docs/includes/eloquent-models/PlanetThirdParty.php

@@ -10,6 +10,5 @@ class Planet extends CelestialBody
     use DocumentModel;
 
     protected $fillable = ['name', 'diameter'];
-    protected $primaryKey = '_id';
     protected $keyType = 'string';
 }

docs/includes/framework-compatibility-laravel.rst

@@ -7,7 +7,7 @@
      - Laravel 10.x
      - Laravel 9.x
 
-   * - 4.2 to 4.8
+   * - 4.2 to 5.1
      - ✓
      - ✓
      -

docs/includes/fundamentals/write-operations/WriteOperationsTest.php

@@ -162,7 +162,7 @@ public function testModelUpdateFluent(): void
 
         // begin model update one fluent
         $concert = Concert::where(['performer' => 'Brad Mehldau'])
-            ->orderBy('_id')
+            ->orderBy('id')
             ->first()
             ->update(['venue' => 'Manchester Arena', 'ticketsSold' => 9543]);
         // end model update one fluent
@@ -370,31 +370,31 @@ public function testModelDeleteById(): void
 
         $data = [
             [
-                '_id' => 'CH-0401242000',
+                'id' => 'CH-0401242000',
                 'performer' => 'Mitsuko Uchida',
                 'venue' => 'Carnegie Hall',
                 'genres' => ['classical'],
                 'ticketsSold' => 2121,
                 'performanceDate' => new UTCDateTime(Carbon::create(2024, 4, 1, 20, 0, 0, 'EST')),
             ],
             [
-                '_id' => 'MSG-0212252000',
+                'id' => 'MSG-0212252000',
                 'performer' => 'Brad Mehldau',
                 'venue' => 'Philharmonie de Paris',
                 'genres' => [ 'jazz', 'post-bop' ],
                 'ticketsSold' => 5745,
                 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
             ],
             [
-                '_id' => 'MSG-021222000',
+                'id' => 'MSG-021222000',
                 'performer' => 'Billy Joel',
                 'venue' => 'Madison Square Garden',
                 'genres' => [ 'rock', 'soft rock', 'pop rock' ],
                 'ticketsSold' => 12852,
                 'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
             ],
             [
-                '_id' => 'SF-06302000',
+                'id' => 'SF-06302000',
                 'performer' => 'The Rolling Stones',
                 'venue' => 'Soldier Field',
                 'genres' => [ 'rock', 'pop', 'blues' ],
@@ -478,22 +478,22 @@ public function testModelDeleteMultipleById(): void
         Concert::truncate();
         $data = [
             [
-                '_id' => 3,
+                'id' => 3,
                 'performer' => 'Mitsuko Uchida',
                 'venue' => 'Carnegie Hall',
             ],
             [
-                '_id' => 5,
+                'id' => 5,
                 'performer' => 'Brad Mehldau',
                 'venue' => 'Philharmonie de Paris',
             ],
             [
-                '_id' => 7,
+                'id' => 7,
                 'performer' => 'Billy Joel',
                 'venue' => 'Madison Square Garden',
             ],
             [
-                '_id' => 9,
+                'id' => 9,
                 'performer' => 'The Rolling Stones',
                 'venue' => 'Soldier Field',
             ],