From 89b4a410cfd386976804a5c7d03fee86d8a1900b Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 13:57:53 -0500 Subject: [PATCH 01/11] DOCSP-46438: Read preference --- docs/fundamentals/read-operations.txt | 108 ++++++++++++++++++ .../read-operations/ReadOperationsTest.php | 16 +++ .../query-builder/QueryBuilderTest.php | 12 ++ docs/query-builder.txt | 28 ++++- 4 files changed, 160 insertions(+), 4 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index d5605033b..4a0d6731c 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -359,6 +359,8 @@ method: results in a specified order based on field values - :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document that matches the query filter +- :ref:`laravel-read-pref` uses the ``readPreference()`` method to direct the query + to specific replica set members .. _laravel-skip-limit: @@ -606,3 +608,109 @@ field. To learn more about the ``orderBy()`` method, see the :ref:`laravel-sort` section of this guide. + +.. _laravel-read-pref: + +Set a Read Preference +~~~~~~~~~~~~~~~~~~~~~ + +To specify which replica set members receive your read operation, +set a read preference by using the ``readPreference()`` method. + +The ``readPreference()`` method accepts the following parameters: + +- ``mode``: (Required) A string value specifying the read preference + mode. + +- ``tagSets``: (Optional) An array value specifying key-value tags that correspond to + the target replica set members. + +- ``options``: (Optional) An array value specifying additional read preference options. + +.. tip:: + + To view a full list of available read preference modes and options, see + :php:`MongoDB\Driver\ReadPreference::__construct ` + in the MongoDB PHP extension documentation. + +The following example queries for documents in which the value of the ``title`` +field is ``"Carrie"`` and retrieves the results from secondary replica set +members, or the primary member if no secondaries are available: + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-read-pref + :end-before: end-read-pref + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('title', 'Carrie') + ->readPreference('secondaryPreferred') + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Carrie + Year: 1952 + Runtime: 118 + IMDB Rating: 7.5 + IMDB Votes: 1458 + Plot: Carrie boards the train to Chicago with big ambitions. She gets a + job stitching shoes and her sister's husband takes almost all of her pay + for room and board. Then she injures a finger and ... + + Title: Carrie + Year: 1976 + Runtime: 98 + IMDB Rating: 7.4 + IMDB Votes: 115528 + Plot: A shy, outcast 17-year old girl is humiliated by her classmates for the + last time. + + Title: Carrie + Year: 2002 + Runtime: 132 + IMDB Rating: 5.5 + IMDB Votes: 7412 + Plot: Carrie White is a lonely and painfully shy teenage girl with telekinetic + powers who is slowly pushed to the edge of insanity by frequent bullying from + both her classmates and her domineering, religious mother. + + Title: Carrie + Year: 2013 + Runtime: 100 + IMDB Rating: 6 + IMDB Votes: 98171 + Plot: A reimagining of the classic horror tale about Carrie White, a shy girl + outcast by her peers and sheltered by her deeply religious mother, who unleashes + telekinetic terror on her small town after being pushed too far at her senior prom. diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index c27680fb5..bc262871c 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -164,4 +164,20 @@ public function arrayElemMatch(): void $this->assertNotNull($movies); $this->assertCount(2, $movies); } + + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testReadPreference(): void + { + // start-read-pref + $movies = Movie::where('title', 'Carrie') + ->readPreference('secondaryPreferred') + ->get(); + // end-read-pref + + $this->assertNotNull($movies); + $this->assertCount(4, $movies); + } } diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index d99796fb2..3b1c6edaa 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -452,6 +452,18 @@ public function testCursorTimeout(): void $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); } + public function testReadPreference(): void + { + // begin query read pref + $result = DB::table('movies') + ->where('runtime', '>', 240) + ->readPreference('secondary') + ->get(); + // end query read pref + + $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result); + } + public function testNear(): void { $this->importTheaters(); diff --git a/docs/query-builder.txt b/docs/query-builder.txt index b3c89b0ae..f6cdce148 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -840,6 +840,7 @@ to use the following MongoDB-specific query operations: - :ref:`Run MongoDB Query API operations ` - :ref:`Match documents that contain array elements ` - :ref:`Specify a cursor timeout ` +- :ref:`Specify a read preference <>` - :ref:`Match locations by using geospatial searches ` .. _laravel-query-builder-exists: @@ -1033,6 +1034,25 @@ to specify a maximum duration to wait for cursor operations to complete. `MongoDB\Collection::find() `__ in the PHP Library documentation. +.. _laravel-query-builder-read-pref: + +Specify a Read Preference Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can control how the {+odm-short+} directs read operations to replica +set members by setting a read preference. + +The following example queries the ``movie`` collection for documents +in which the ``runtime`` value is greater than ``240``. The example passes a +value of ``'secondary'`` to the ``readPreference()`` method, which sends +the query to secondary replica set members: + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin query read pref + :end-before: end query read pref + .. _laravel-query-builder-geospatial: Match Locations by Using Geospatial Operations @@ -1061,7 +1081,7 @@ in the {+server-docs-name+}. .. _laravel-query-builder-geospatial-near: Near a Position Example -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``near`` query operator with the ``where()`` query builder method to match documents that @@ -1081,7 +1101,7 @@ in the {+server-docs-name+}. .. _laravel-query-builder-geospatial-geoWithin: Within an Area Example -~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``geoWithin`` query operator with the ``where()`` @@ -1098,7 +1118,7 @@ GeoJSON object: .. _laravel-query-builder-geospatial-geoIntersects: Intersecting a Geometry Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``geoInstersects`` query operator with the ``where()`` query builder method to @@ -1114,7 +1134,7 @@ the specified ``LineString`` GeoJSON object: .. _laravel-query-builder-geospatial-geoNear: Proximity Data for Nearby Matches Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following example shows how to use the ``geoNear`` aggregation operator with the ``raw()`` query builder method to perform an aggregation that returns From 2eb10d43c11fc963627806452dcb36f8d4e7a971 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 14:22:32 -0500 Subject: [PATCH 02/11] edits --- docs/fundamentals/read-operations.txt | 10 +++++----- docs/query-builder.txt | 6 +++--- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 4a0d6731c..cfaf2bb99 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -619,13 +619,13 @@ set a read preference by using the ``readPreference()`` method. The ``readPreference()`` method accepts the following parameters: -- ``mode``: (Required) A string value specifying the read preference +- ``mode``: *(Required)* A string value specifying the read preference mode. -- ``tagSets``: (Optional) An array value specifying key-value tags that correspond to - the target replica set members. +- ``tagSets``: *(Optional)* An array value specifying key-value tags that correspond to + certain replica set members. -- ``options``: (Optional) An array value specifying additional read preference options. +- ``options``: *(Optional)* An array value specifying additional read preference options. .. tip:: @@ -635,7 +635,7 @@ The ``readPreference()`` method accepts the following parameters: The following example queries for documents in which the value of the ``title`` field is ``"Carrie"`` and retrieves the results from secondary replica set -members, or the primary member if no secondaries are available: +members or the primary member if no secondaries are available: .. tabs:: diff --git a/docs/query-builder.txt b/docs/query-builder.txt index f6cdce148..a361bf9fc 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -840,7 +840,7 @@ to use the following MongoDB-specific query operations: - :ref:`Run MongoDB Query API operations ` - :ref:`Match documents that contain array elements ` - :ref:`Specify a cursor timeout ` -- :ref:`Specify a read preference <>` +- :ref:`Specify a read preference ` - :ref:`Match locations by using geospatial searches ` .. _laravel-query-builder-exists: @@ -1042,9 +1042,9 @@ Specify a Read Preference Example You can control how the {+odm-short+} directs read operations to replica set members by setting a read preference. -The following example queries the ``movie`` collection for documents +The following example queries the ``movies`` collection for documents in which the ``runtime`` value is greater than ``240``. The example passes a -value of ``'secondary'`` to the ``readPreference()`` method, which sends +value of ``"secondary"`` to the ``readPreference()`` method, which sends the query to secondary replica set members: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php From 539cb7c5adba20b1ce074ac333dd5967c8036cdc Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 14:25:31 -0500 Subject: [PATCH 03/11] tip --- docs/query-builder.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index a361bf9fc..69823cbbc 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -1053,6 +1053,11 @@ the query to secondary replica set members: :start-after: begin query read pref :end-before: end query read pref +.. tip:: + + To learn more about read preferences, see :manual:`Read Preference + ` in the MongoDB {+server-docs-name+}. + .. _laravel-query-builder-geospatial: Match Locations by Using Geospatial Operations From f6f2648b5dbd08a99fe652795c86d36ee129691d Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 14:29:09 -0500 Subject: [PATCH 04/11] fix test --- .../fundamentals/read-operations/ReadOperationsTest.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index bc262871c..f7e6f98bb 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -33,6 +33,8 @@ 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' => 'Carrie', 'year' => 1976], + ['title' => 'Carrie', 'year' => 2002], ]); } @@ -178,6 +180,6 @@ public function testReadPreference(): void // end-read-pref $this->assertNotNull($movies); - $this->assertCount(4, $movies); + $this->assertCount(2, $movies); } } From 5a43c3ca40f3f1a46fc5ebe94c1d5c5573eeda31 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 14:32:37 -0500 Subject: [PATCH 05/11] fix --- .../fundamentals/read-operations/ReadOperationsTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index f7e6f98bb..90da15c2e 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -175,7 +175,7 @@ public function testReadPreference(): void { // start-read-pref $movies = Movie::where('title', 'Carrie') - ->readPreference('secondaryPreferred') + ->readPreference('primaryPreferred') ->get(); // end-read-pref From 3d6733eed6edc48b241276e133da5a9e53075c81 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 14:36:08 -0500 Subject: [PATCH 06/11] code --- .../fundamentals/read-operations/ReadOperationsTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index 90da15c2e..f7e6f98bb 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -175,7 +175,7 @@ public function testReadPreference(): void { // start-read-pref $movies = Movie::where('title', 'Carrie') - ->readPreference('primaryPreferred') + ->readPreference('secondaryPreferred') ->get(); // end-read-pref From d6861d91381479ef9ac5eaece8251bc9b6ed7d62 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 30 Jan 2025 15:17:42 -0500 Subject: [PATCH 07/11] JS feedback --- docs/fundamentals/read-operations.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index cfaf2bb99..ec7015829 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -614,7 +614,7 @@ field. Set a Read Preference ~~~~~~~~~~~~~~~~~~~~~ -To specify which replica set members receive your read operation, +To specify which replica set members receive your read operations, set a read preference by using the ``readPreference()`` method. The ``readPreference()`` method accepts the following parameters: @@ -634,7 +634,8 @@ The ``readPreference()`` method accepts the following parameters: in the MongoDB PHP extension documentation. The following example queries for documents in which the value of the ``title`` -field is ``"Carrie"`` and retrieves the results from secondary replica set +field is ``"Carrie"`` and sets the read preference to ``"secondaryPreferred"``. +As a result, the query retrieves the results from secondary replica set members or the primary member if no secondaries are available: .. tabs:: From 4637e5e6cce8be582ca1edb35f5dbcc9d898c939 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 6 Feb 2025 18:33:03 +0100 Subject: [PATCH 08/11] Switch example to SECONDARY_PREFERRED --- docs/includes/query-builder/QueryBuilderTest.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 3b1c6edaa..f7525bf6e 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -11,6 +11,7 @@ use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; use MongoDB\Collection; +use MongoDB\Driver\ReadPreference; use MongoDB\Laravel\Tests\TestCase; use function file_get_contents; @@ -457,7 +458,7 @@ public function testReadPreference(): void // begin query read pref $result = DB::table('movies') ->where('runtime', '>', 240) - ->readPreference('secondary') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) ->get(); // end query read pref From eeba8080d25f4d7cd778bdeeef4992051bc5b7e7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 6 Feb 2025 15:24:56 -0500 Subject: [PATCH 09/11] JT feedback --- docs/fundamentals/read-operations.txt | 4 ++-- .../fundamentals/read-operations/ReadOperationsTest.php | 3 ++- docs/query-builder.txt | 5 +++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index ec7015829..f3b02c5ec 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -634,7 +634,7 @@ The ``readPreference()`` method accepts the following parameters: in the MongoDB PHP extension documentation. The following example queries for documents in which the value of the ``title`` -field is ``"Carrie"`` and sets the read preference to ``"secondaryPreferred"``. +field is ``"Carrie"`` and sets the read preference to ``ReadPreference::SECONDARY_PREFERRED``. As a result, the query retrieves the results from secondary replica set members or the primary member if no secondaries are available: @@ -668,7 +668,7 @@ members or the primary member if no secondaries are available: public function show() { $movies = Movie::where('title', 'Carrie') - ->readPreference('secondaryPreferred') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) ->get(); return view('browse_movies', [ diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index f7e6f98bb..7aab95ed2 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -7,6 +7,7 @@ use App\Models\Movie; use Illuminate\Support\Facades\DB; use MongoDB\Laravel\Tests\TestCase; +use MongoDB\Driver\ReadPreference; class ReadOperationsTest extends TestCase { @@ -175,7 +176,7 @@ public function testReadPreference(): void { // start-read-pref $movies = Movie::where('title', 'Carrie') - ->readPreference('secondaryPreferred') + ->readPreference(ReadPreference::SECONDARY_PREFERRED) ->get(); // end-read-pref diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 69823cbbc..89caf8846 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -1044,8 +1044,9 @@ set members by setting a read preference. The following example queries the ``movies`` collection for documents in which the ``runtime`` value is greater than ``240``. The example passes a -value of ``"secondary"`` to the ``readPreference()`` method, which sends -the query to secondary replica set members: +value of ``ReadPreference::SECONDARY_PREFERRED`` to the ``readPreference()`` +method, which sends the query to secondary replica set members +or the primary member if no secondaries are available: .. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php From 0792d5b9fc4949c395b69b6ffaa2f9492744da2a Mon Sep 17 00:00:00 2001 From: norareidy <107268623+norareidy@users.noreply.github.com> Date: Thu, 6 Feb 2025 20:25:36 +0000 Subject: [PATCH 10/11] apply phpcbf formatting --- .../fundamentals/read-operations/ReadOperationsTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php index 7aab95ed2..207fd442e 100644 --- a/docs/includes/fundamentals/read-operations/ReadOperationsTest.php +++ b/docs/includes/fundamentals/read-operations/ReadOperationsTest.php @@ -6,8 +6,8 @@ use App\Models\Movie; use Illuminate\Support\Facades\DB; -use MongoDB\Laravel\Tests\TestCase; use MongoDB\Driver\ReadPreference; +use MongoDB\Laravel\Tests\TestCase; class ReadOperationsTest extends TestCase { From 50c5783843a5921467baf716959100fde22486ba Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 7 Feb 2025 12:07:49 -0500 Subject: [PATCH 11/11] tests