Merge branch '4.6' into paginator-total-override

Author: GromNaN

.github/workflows/release.yml

@@ -115,34 +115,17 @@ jobs:
           aws_region_name: ${{ vars.AWS_REGION_NAME }}
           aws_secret_id: ${{ secrets.AWS_SECRET_ID }}
 
-      - name: "Generate authorized publication document"
-        uses: mongodb-labs/drivers-github-tools/authorized-pub@v2
+      - name: "Generate SSDLC Reports"
+        uses: mongodb-labs/drivers-github-tools/full-report@v2
         with:
           product_name: "MongoDB Laravel Integration"
           release_version: ${{ inputs.version }}
-          filenames: ""
-          token: ${{ env.GH_TOKEN }}
-
-      - name: "Download SBOM file from Silk"
-        uses: mongodb-labs/drivers-github-tools/sbom@v2
-        with:
           silk_asset_group: mongodb-laravel-integration
 
       - name: "Upload SBOM as release artifact"
         run: gh release upload ${{ inputs.version }} ${{ env.S3_ASSETS }}/cyclonedx.sbom.json
         continue-on-error: true
 
-      - name: "Generate SARIF report from code scanning alerts"
-        uses: mongodb-labs/drivers-github-tools/code-scanning-export@v2
-        with:
-          ref: ${{ inputs.version }}
-          output-file: ${{ env.S3_ASSETS }}/code-scanning-alerts.json
-
-      - name: "Generate compliance report"
-        uses: mongodb-labs/drivers-github-tools/compliance-report@v2
-        with:
-          token: ${{ env.GH_TOKEN }}
-
       - name: Upload S3 assets
         uses: mongodb-labs/drivers-github-tools/upload-s3-assets@v2
         with:

CHANGELOG.md

@@ -3,11 +3,12 @@ All notable changes to this project will be documented in this file.
 
 ## [4.6.0] - upcoming
 
+* Add `DocumentTrait` to use any 3rd party model with MongoDB @GromNaN in [#2580](https://github.com/mongodb/laravel-mongodb/pull/2580)
 * Add support for Closure for Embed pagination @GromNaN in [#3027](https://github.com/mongodb/laravel-mongodb/pull/3027)
 
 ## [4.5.0] - 2024-06-20
 
-* Add GridFS integration for Laravel File Storage by @GromNaN in [#2984](https://github.com/mongodb/laravel-mongodb/pull/2984)
+* Add GridFS integration for Laravel File Storage by @GromNaN in [#2985](https://github.com/mongodb/laravel-mongodb/pull/2985)
 
 ## [4.4.0] - 2024-05-31
 

docs/fundamentals/read-operations.txt

@@ -57,16 +57,13 @@ You can use Laravel's Eloquent object-relational mapper (ORM) to create models
 that represent MongoDB collections and chain methods on them to specify
 query criteria.
 
-To retrieve documents that match a set of criteria, pass a query filter to the
-``where()`` method.
+To retrieve documents that match a set of criteria, call the ``where()``
+method on the collection's corresponding Eloquent model, then pass a query
+filter to the method.
 
 A query filter specifies field value requirements and instructs the find
 operation to return only documents that meet these requirements.
 
-You can use Laravel's Eloquent object-relational mapper (ORM) to create models
-that represent MongoDB collections. To retrieve documents from a collection,
-call the ``where()`` method on the collection's corresponding Eloquent model.
-
 You can use one of the following ``where()`` method calls to build a query:
 
 - ``where('<field name>', <value>)`` builds a query that matches documents in
@@ -79,7 +76,7 @@ You can use one of the following ``where()`` method calls to build a query:
 To apply multiple sets of criteria to the find operation, you can chain a series
 of ``where()`` methods together.
 
-After building your query with the ``where()`` method, chain the ``get()``
+After building your query by using the ``where()`` method, chain the ``get()``
 method to retrieve the query results.
 
 This example calls two ``where()`` methods on the ``Movie`` Eloquent model to
@@ -150,6 +147,60 @@ retrieve documents that meet the following criteria:
 To learn how to query by using the Laravel query builder instead of the
 Eloquent ORM, see the :ref:`laravel-query-builder` page.
 
+Match Array Field Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify a query filter to match array field elements when
+retrieving documents. If your documents contain an array field, you can
+match documents based on if the value contains all or some specified
+array elements.
+
+You can use one of the following ``where()`` method calls to build a
+query on an array field:
+
+- ``where('<array field>', <array>)`` builds a query that matches documents in
+  which the array field value is exactly the specified array
+
+- ``where('<array field>', 'in', <array>)`` builds a query
+  that matches documents in which the array field value contains one or
+  more of the specified array elements
+
+After building your query by using the ``where()`` method, chain the ``get()``
+method to retrieve the query results.
+
+Select from the following :guilabel:`Exact Array Match` and
+:guilabel:`Element Match` tabs to view the query syntax for each pattern:
+
+.. tabs::
+
+   .. tab:: Exact Array Match
+      :tabid: exact-array
+
+      This example retrieves documents in which the ``countries`` array is
+      exactly ``['Indonesia', 'Canada']``:
+
+      .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php
+         :language: php
+         :dedent:
+         :start-after: start-exact-array
+         :end-before: end-exact-array
+
+   .. tab:: Element Match
+      :tabid: element-match
+
+      This example retrieves documents in which the ``countries`` array
+      contains one of the values in the array ``['Canada', 'Egypt']``:
+
+      .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php
+         :language: php
+         :dedent:
+         :start-after: start-elem-match
+         :end-before: end-elem-match
+
+To learn how to query array fields by using the Laravel query builder instead of the
+Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in
+the Query Builder guide.
+
 .. _laravel-retrieve-all:
 
 Retrieve All Documents in a Collection
@@ -200,7 +251,7 @@ by the ``$search`` field in your query filter that you pass to the
 ``where()`` method. The ``$text`` operator performs a text search on the
 text-indexed fields. The ``$search`` field specifies the text to search for.
 
-After building your query with the ``where()`` method, chain the ``get()``
+After building your query by using the ``where()`` method, chain the ``get()``
 method to retrieve the query results.
 
 This example calls the ``where()`` method on the ``Movie`` Eloquent model to

docs/includes/fundamentals/read-operations/ReadOperationsTest.php

@@ -133,4 +133,35 @@ public function testTextRelevance(): void
         $this->assertCount(1, $movies);
         $this->assertEquals('this is a love story', $movies[0]->plot);
     }
+
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function exactArrayMatch(): void
+    {
+        // start-exact-array
+        $movies = Movie::where('countries', ['Indonesia', 'Canada'])
+            ->get();
+        // end-exact-array
+
+        $this->assertNotNull($movies);
+        $this->assertCount(1, $movies);
+        $this->assertEquals('Title 1', $movies[0]->title);
+    }
+
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function arrayElemMatch(): void
+    {
+        // start-elem-match
+        $movies = Movie::where('countries', 'in', ['Canada', 'Egypt'])
+            ->get();
+        // end-elem-match
+
+        $this->assertNotNull($movies);
+        $this->assertCount(2, $movies);
+    }
 }

docs/index.txt

@@ -23,6 +23,7 @@
    /cache
    /queues
    /transactions
+   /filesystems
    /issues-and-help
    /feature-compatibility
    /compatibility
@@ -73,6 +74,7 @@ see the following content:
 - :ref:`laravel-cache`
 - :ref:`laravel-queues`
 - :ref:`laravel-transactions`
+- :ref:`laravel-filesystems`
 
 Issues & Help
 -------------

docs/queues.txt

@@ -9,24 +9,29 @@ Queues
    :values: tutorial
 
 .. meta::
-   :keywords: php framework, odm, code example
+   :keywords: php framework, odm, code example, jobs
 
-If you want to use MongoDB as your database backend for Laravel Queue, change
-the driver in ``config/queue.php``:
+To use MongoDB as your database for Laravel Queue, change
+the driver in your application's ``config/queue.php`` file:
 
 .. code-block:: php
 
    'connections' => [
        'database' => [
            'driver' => 'mongodb',
-           // You can also specify your jobs specific database created on config/database.php
+           // You can also specify your jobs-specific database
+           // in the config/database.php file
            'connection' => 'mongodb',
            'collection' => 'jobs',
            'queue' => 'default',
-           'retry_after' => 60,
+           // Optional setting
+           // 'retry_after' => 60,
        ],
    ],
 
+The following table describes properties that you can specify to configure
+the behavior of the queue:
+
 .. list-table::
    :header-rows: 1
    :widths: 25 75
@@ -35,22 +40,29 @@ the driver in ``config/queue.php``:
      - Description
 
    * - ``driver``
-     - **Required**. Specifies the queue driver to use. Must be ``mongodb``.
+     - **Required** Queue driver to use. The value of
+       this property must be ``mongodb``.
 
    * - ``connection``
-     - The database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified.
+     - Database connection used to store jobs. It must be a
+       ``mongodb`` connection. The driver uses the default connection if
+       a connection is not specified.
 
    * - ``collection``
-     - **Required**. Name of the MongoDB collection to store jobs to process.
+     - **Required** Name of the MongoDB collection to
+       store jobs to process.
 
    * - ``queue``
-     - **Required**. Name of the queue.
+     - **Required** Name of the queue.
 
    * - ``retry_after``
-     - Specifies how many seconds the queue connection should wait before retrying a job that is being processed. Defaults to ``60``. 
+     - Specifies how many seconds the queue connection should wait
+       before retrying a job that is being processed. The value is
+       ``60`` by default.
 
-If you want to use MongoDB to handle failed jobs, change the database in
-``config/queue.php``:
+To use MongoDB to handle failed jobs, create a ``failed`` entry in your
+application's ``config/queue.php`` file and specify the database and
+collection:
 
 .. code-block:: php
 
@@ -60,6 +72,9 @@ If you want to use MongoDB to handle failed jobs, change the database in
        'collection' => 'failed_jobs',
    ],
 
+The following table describes properties that you can specify to configure
+how to handle failed jobs:
+
 .. list-table::
    :header-rows: 1
    :widths: 25 75
@@ -68,32 +83,41 @@ If you want to use MongoDB to handle failed jobs, change the database in
      - Description
 
    * - ``driver``
-     - **Required**. Specifies the queue driver to use. Must be ``mongodb``.
+     - **Required** Queue driver to use. The value of
+       this property must be ``mongodb``.
 
    * - ``connection``
-     - The database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified.
+     - Database connection used to store jobs. It must be
+       a ``mongodb`` connection. The driver uses the default connection
+       if a connection is not specified.
 
    * - ``collection``
-     - Name of the MongoDB collection to store failed jobs. Defaults to ``failed_jobs``. 
-
+     - Name of the MongoDB collection to store failed
+       jobs. The value is ``failed_jobs`` by default.
 
-Add the service provider in ``config/app.php``:
+Then, add the service provider in your application's
+``config/app.php`` file:
 
 .. code-block:: php
 
    MongoDB\Laravel\MongoDBQueueServiceProvider::class,
 
-
 Job Batching
 ------------
 
-`Job batching <https://laravel.com/docs/{+laravel-docs-version+}/queues#job-batching>`__
-is a Laravel feature to execute a batch of jobs and subsequent actions before,
-after, and during the execution of the jobs from the queue.
+**Job batching** is a Laravel feature that enables you to execute a
+batch of jobs and related actions before, after, and during the
+execution of the jobs from the queue. To learn more about this feature,
+see `Job Batching <https://laravel.com/docs/{+laravel-docs-version+}/queues#job-batching>`__
+in the Laravel documentation.
+
+In MongoDB, you don't have to create a designated collection before
+using job batching. The ``job_batches`` collection is created
+automatically to store metadata about your job batches, such as
+their completion percentage.
 
-With MongoDB, you don't have to create any collection before using job batching.
-The ``job_batches`` collection is created automatically to store meta
-information about your job batches, such as their completion percentage.
+To enable job batching, create the ``batching`` entry in your
+application's ``config/queue.php`` file:
 
 .. code-block:: php
 
@@ -103,6 +127,9 @@ information about your job batches, such as their completion percentage.
        'collection' => 'job_batches',
    ],
 
+The following table describes properties that you can specify to configure
+job batching:
+
 .. list-table::
    :header-rows: 1
    :widths: 25 75
@@ -111,15 +138,20 @@ information about your job batches, such as their completion percentage.
      - Description
 
    * - ``driver``
-     - **Required**. Specifies the queue driver to use. Must be ``mongodb``.
+     - **Required** Queue driver to use. The value of
+       this property must be ``mongodb``.
 
    * - ``connection``
-     - The database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified.
+     - Database connection used to store jobs. It must be a
+       ``mongodb`` connection. The driver uses the default connection if
+       a connection is not specified.
 
    * - ``collection``
-     - Name of the MongoDB collection to store job batches. Defaults to ``job_batches``. 
+     - Name of the MongoDB collection to store job
+       batches. The value is ``job_batches`` by default.
 
-Add the service provider in ``config/app.php``:
+Then, add the service provider in your application's ``config/app.php``
+file:
 
 .. code-block:: php
 

docs/transactions.txt

@@ -99,15 +99,16 @@ to another account:
    :start-after: begin transaction callback
    :end-before: end transaction callback
 
-You can optionally pass the maximum number of times to retry a failed transaction as the second parameter as shown in the following code example:
+You can optionally pass the maximum number of times to retry a failed transaction
+as the second parameter, as shown in the following code example:
 
 .. code-block:: php
    :emphasize-lines: 4
 
    DB::transaction(function() {
            // transaction code
        },
-       retries: 5,
+       attempts: 5,
    );
 
 .. _laravel-transaction-commit: