Merge 5.4 into 5.x (#3402)

Author: mongodb-php-bot

docs/fundamentals/read-operations.txt

@@ -17,7 +17,8 @@ Read Operations
    Retrieve Data </fundamentals/read-operations/retrieve>
    Search Text </fundamentals/read-operations/search-text>
    Modify Query Results </fundamentals/read-operations/modify-results>
-   Set Read Preference </fundamentals/read-operations/read-pref>
+   Read Preference </fundamentals/read-operations/read-pref>
+   Query Logging </fundamentals/read-operations/query-logging>
 
 .. contents:: On this page
    :local:

docs/fundamentals/read-operations/query-logging.txt

@@ -0,0 +1,82 @@
+.. _laravel-query-logging:
+
+====================
+Enable Query Logging
+====================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: monitoring, CRUD, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to enable query logging in
+{+odm-long+}. Query logging can help you debug your queries and monitor
+database interactions.
+
+.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst
+
+Enable Logs On a Connection
+---------------------------
+
+To enable logs on a connection, you can use the ``enableQueryLog()``
+method on the ``DB`` facade. This method enables MongoDB command logging
+on any queries that you perform on the database connection.
+
+After you enable query logging, any queries you perform are stored in
+memory. To retrieve the logs, use one of the following methods:
+
+- ``getQueryLog()``: Returns a log of MongoDB queries
+- ``getRawQueryLog()``: Returns a log of raw MongoDB queries
+
+The following example enables query logging, performs some queries, then
+prints the query log:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/read-operations/ReadOperationsTest.php
+      :language: php
+      :dedent:
+      :start-after: start-query-log
+      :end-before: end-query-log
+      :emphasize-lines: 1, 7
+
+   .. output::
+      :language: json
+      :visible: false
+
+      {
+        "query": "{ \"find\" : \"movies\", \"filter\" : { \"title\" : \"Carrie\" } }",
+        "bindings": [],
+        "time": 29476
+      }
+      {
+        "query": "{ \"find\" : \"movies\", \"filter\" : { \"year\" : { \"$lt\" : { \"$numberInt\" : \"2005\" } } } }",
+        "bindings": [],
+        "time": 29861
+      }
+      {
+        "query": "{ \"find\" : \"movies\", \"filter\" : { \"imdb.rating\" : { \"$gt\" : { \"$numberDouble\" : \"8.5\" } } } }",
+        "bindings": [],
+        "time": 27251
+      }
+
+Additional Information
+----------------------
+
+To learn more about connecting to MongoDB, see the
+:ref:`laravel-connect-to-mongodb`.
+
+To learn how to retrieve data based on filter criteria, see the
+:ref:`laravel-fundamentals-read-retrieve` guide.

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

@@ -9,6 +9,13 @@
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Laravel\Tests\TestCase;
 
+use function json_encode;
+use function ob_get_flush;
+use function ob_start;
+
+use const JSON_PRETTY_PRINT;
+use const PHP_EOL;
+
 class ReadOperationsTest extends TestCase
 {
     protected function setUp(): void
@@ -183,4 +190,37 @@ public function testReadPreference(): void
         $this->assertNotNull($movies);
         $this->assertCount(2, $movies);
     }
+
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testQueryLog(): void
+    {
+        $output = '';
+        ob_start(function (string $buffer) use (&$output) {
+            $output .= $buffer;
+        });
+        // start-query-log
+        DB::connection('mongodb')->enableQueryLog();
+
+        Movie::where('title', 'Carrie')->get();
+        Movie::where('year', '<', 2005)->get();
+        Movie::where('imdb.rating', '>', 8.5)->get();
+
+        $logs = DB::connection('mongodb')->getQueryLog();
+        foreach ($logs as $log) {
+            echo json_encode($log, JSON_PRETTY_PRINT) . PHP_EOL;
+        }
+
+        // end-query-log
+        $output = ob_get_flush();
+        $this->assertNotNull($logs);
+        $this->assertNotEmpty($output);
+
+        $this->assertStringContainsString('"query": "{ \"find\" : \"movies\", \"filter\" : { \"title\" : \"Carrie\" } }"', $output);
+        $this->assertStringContainsString('"query": "{ \"find\" : \"movies\", \"filter\" : { \"imdb.rating\" : { \"$gt\" : { \"$numberDouble\" : \"8.5\" } } } }"', $output);
+        $this->assertStringContainsString('"query": "{ \"find\" : \"movies\", \"filter\" : { \"imdb.rating\" : { \"$gt\" : { \"$numberDouble\" : \"8.5\" } } } }"', $output);
+        $this->assertMatchesRegularExpression('/"time": \d+/', $output);
+    }
 }