DOCSP-38380: array reads

Author: rustagir

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 modelm then pass a query
+filter.
 
 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
@@ -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 with 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

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

@@ -33,6 +33,7 @@ protected function setUp(): void
             ['title' => 'movie_a', 'plot' => 'this is a love story'],
             ['title' => 'movie_b', 'plot' => 'love is a long story'],
             ['title' => 'movie_c', 'plot' => 'went on a trip'],
+            ['title' => 'movie_c', 'plot' => 'went on a trip'],
         ]);
     }
 
@@ -133,4 +134,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);
+    }
 }