Merge 4.8 into 5.0

docs/includes/query-builder/QueryBuilderTest.php

@@ -46,6 +46,19 @@ protected function tearDown(): void
         parent::tearDown();
     }
 
+    public function testOptions(): void
+    {
+        // begin options
+        $result = DB::connection('mongodb')
+            ->table('movies')
+            ->where('year', 2000)
+            ->options(['comment' => 'hello'])
+            ->get();
+        // end options
+
+        $this->assertInstanceOf(\Illuminate\Support\Collection::class, $result);
+    }
+
     public function testWhere(): void
     {
         // begin query where

docs/query-builder.txt

@@ -46,15 +46,19 @@ The following example shows the syntax of a query builder call:
    DB::table('<collection name>')
        // chain methods by using the "->" object operator
        ->get();
+
 .. tip::
 
-   Before using the ``DB::table()`` method, ensure that you specify MongoDB as your application's
-   default database connection. For instructions on setting the database connection,
-   see the :ref:`laravel-quick-start-connect-to-mongodb` step in the Quick Start.
+   Before using the ``DB::table()`` method, ensure that you specify
+   MongoDB as your application's default database connection. For
+   instructions on setting the database connection, see the
+   :ref:`laravel-quick-start-connect-to-mongodb` step in the Quick
+   Start.
 
-   If MongoDB is not your application's default database, you can use the ``DB::connection()`` method
-   to specify a MongoDB connection. Pass the name of the connection to the ``connection()`` method,
-   as shown in the following code:
+   If MongoDB is not your application's default database, you can use
+   the ``DB::connection()`` method to specify a MongoDB connection. Pass
+   the name of the connection to the ``connection()`` method, as shown
+   in the following code:
 
    .. code-block:: php
 
@@ -63,6 +67,7 @@ The following example shows the syntax of a query builder call:
 This guide provides examples of the following types of query builder operations:
 
 - :ref:`laravel-retrieve-query-builder`
+- :ref:`laravel-options-query-builder`
 - :ref:`laravel-modify-results-query-builder`
 - :ref:`laravel-mongodb-read-query-builder`
 - :ref:`laravel-mongodb-write-query-builder`
@@ -606,6 +611,33 @@ value of ``imdb.rating`` of those matches by using the
    :start-after: begin aggregation with filter
    :end-before: end aggregation with filter
 
+.. _laravel-options-query-builder:
+
+Set Query-Level Options
+-----------------------
+
+You can modify the way that the {+odm-short+} performs operations by
+setting options on the query builder. You can pass an array of options
+to the ``options()`` query builder method to specify options for the
+query.
+
+The following code demonstrates how to attach a comment to
+a query:
+
+.. literalinclude:: /includes/query-builder/QueryBuilderTest.php
+   :language: php
+   :dedent:
+   :start-after: begin options
+   :end-before: end options
+
+The query builder accepts the same options that you can set for
+the :phpmethod:`find() <phpmethod.MongoDB\\Collection::find()>` method in the
+{+php-library+}. Some of the options to modify query results, such as
+``skip``, ``sort``, and ``limit``, are settable directly as query
+builder methods and are described in the
+:ref:`laravel-modify-results-query-builder` section of this guide. We
+recommend that you use these methods instead of passing them as options.
+
 .. _laravel-modify-results-query-builder:
 
 Modify Query Results