From 0a143cc31601417ff07290afa7b7a700f6f8d144 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Fri, 28 Jun 2024 12:52:23 -0400 Subject: [PATCH 1/2] DOCSP-41010: Fix transactions code example (#3016) --- docs/transactions.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/transactions.txt b/docs/transactions.txt index 5ef3df19d..89562c795 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -99,7 +99,8 @@ 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 @@ -107,7 +108,7 @@ You can optionally pass the maximum number of times to retry a failed transactio DB::transaction(function() { // transaction code }, - retries: 5, + attempts: 5, ); .. _laravel-transaction-commit: From cb3fa4ef27cbf65f8e0edbd7b632c7707ab3cb28 Mon Sep 17 00:00:00 2001 From: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Date: Mon, 8 Jul 2024 11:38:52 -0400 Subject: [PATCH 2/2] DOCSP-38380: array reads (#3028) * DOCSP-38380: array reads * fix * NR PR fixes 1 * remove extra doc in test --- docs/fundamentals/read-operations.txt | 67 ++++++++++++++++--- .../read-operations/ReadOperationsTest.php | 31 +++++++++ 2 files changed, 90 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 8025f0087..29437aa59 100644 --- a/docs/fundamentals/read-operations.txt +++ b/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('', )`` 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('', )`` builds a query that matches documents in + which the array field value is exactly the specified array + +- ``where('', 'in', )`` 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 diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index a2080ec8f..c27680fb5 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/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); + } }