Update MongoDB\Database documentation

docs/includes/apiargs-MongoDBDatabase-method-command-option.yaml

@@ -3,10 +3,18 @@ source:
   ref: readPreference
 operation: MongoDB\\Database::command
 position: 1
+description: |
+  The read preference to use when executing the command. This may be used when
+  issuing the command to a replica set or shard cluster to ensure that the
+  driver sets the wire protocol accordingly or adds the read preference to the
+  command document, respectively. Defaults to the Database's read preference.
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
 operation: MongoDB\\Database::command
 position: 2
+description: |
+  Type map for BSON deserialization. This will be applied to the returned
+  cursor. Defaults to the database's type map.
 ...

docs/includes/apiargs-MongoDBDatabase-method-command-param.yaml

 arg_name: param
 name: $command
-type: string
+type: array|object
 description: |
-  The name of the :manual:`database command </reference/command>`
-  to execute.
+  The :manual:`database command </reference/command>` document.
 interface: phpmethod
 operation: MongoDB\\Database::command
 optional: false

docs/includes/apiargs-MongoDBDatabase-method-construct-option.yaml

@@ -3,17 +3,39 @@ source:
   ref: readConcern
 operation: MongoDB\\Database::__construct
 position: 1
+replacement:
+  resource: "database"
+  parent: "manager"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
 operation: MongoDB\\Database::__construct
 position: 2
+replacement:
+  resource: "database"
+  parent: "manager"
 ---
-source:
-  file: apiargs-common-option.yaml
-  ref: typeMap
+arg_name: option
+name: typeMap
+type: array
+description: |
+  Default :php:`type map
+  <manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
+  to apply to cursors. The type map determines how BSON documents are converted
+  to PHP values which determines. The |php-library| uses the following type map
+  by default:
+
+  .. code-block:: php
+
+     [
+         'array' => 'MongoDB\Model\BSONArray',
+         'document' => 'MongoDB\Model\BSONDocument',
+         'root' => 'MongoDB\Model\BSONDocument',
+     ]
+interface: phpmethod
 operation: MongoDB\\Database::__construct
+optional: true
 position: 3
 ---
 source:
@@ -21,4 +43,7 @@ source:
   ref: writeConcern
 operation: MongoDB\\Database::__construct
 position: 4
+replacement:
+  resource: "database"
+  parent: "manager"
 ...

docs/includes/apiargs-MongoDBDatabase-method-construct-param.yaml

@@ -5,8 +5,8 @@ operation: MongoDB\\Database::__construct
 position: 1
 ---
 source:
-  ref: $databaseName
   file: apiargs-common-param.yaml
+  ref: $databaseName
 operation: MongoDB\\Database::__construct
 position: 2
 ---
@@ -14,5 +14,5 @@ source:
   ref: $options
   file: apiargs-common-param.yaml
 operation: MongoDB\\Database::__construct
-position: 2
+position: 3
 ...

docs/includes/apiargs-MongoDBDatabase-method-createCollection-option.yaml

@@ -2,66 +2,77 @@ arg_name: option
 name: autoIndexId
 type: boolean
 description: |
-
-  *Default: true*. Specify false to disable the automatic creation of
-  an index on the _id field.
+  Specify ``false`` to disable the automatic creation of an index on the ``_id``
+  field.
 
   .. important::
 
      For replica sets, do not set ``autoIndexId`` to ``false``.
 
-  .. deprecated:: 3.2. The ``autoIndexId`` option will be removed in MongoDB v3.4.
-
-optional: true
+  .. deprecated:: 3.2. The ``autoIndexId`` option will be removed in MongoDB 3.4.
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
-position: 1
----
-arg_name: option
-name: indexOptionDefaults
-type: array
-description: |
-  Allows users to specify a default configuration for indexes when
-  creating a collection.
-
-  The ``indexOptionDefaults`` option accepts a ``storageEngine`` document,
-  which should take the following form::
-
-    { <storage-engine-name>: <options> } 
-  
-  Storage engine configurations specified when creating indexes are
-  validated and logged to the :term:`oplog` during replication to support
-  replica sets with members that use different storage engines.
 optional: true
-interface: phpmethod
-operation: MongoDB\\Database::createCollection
-position: 2
+position: 1
 ---
 arg_name: option
 name: capped
 type: boolean
 description: |
-  To create a capped collection, specify ``true``. If you specify
-  ``true``, you must also set a maximum size in the ``size`` option.
-optional: true
+  To create a capped collection, specify ``true``. If you specify ``true``, you
+  must also set a maximum size in the ``size`` option.
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
+optional: true
 position: 3
 ---
 arg_name: option
-name: size
+name: flags
 type: integer
 description: |
-  Specify a maximum size in bytes for a capped collection. Once a
-  capped collection reaches its maximum size, MongoDB removes the older
-  documents to make space for the new documents. The ``size`` option is
-  required for capped collections and ignored for other collections.
-optional: true
+  Available for the MMAPv1 storage engine only to set the ``usePowerOf2Sizes``
+  and ``noPadding`` flags.
+
+  The |php-library| provides constants that you can combine with a :php:`bitwise
+  OR operator <language.operators.bitwise>` to set the flag values:
+
+  - ``MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES``: ``1``
+  - ``MongoDB\Operation\CreateCollection::NO_PADDING``: ``2``
+
+  Defaults to ``1``.
+
+  .. note::
+
+     MongoDB 3.0 and later ignores the ``usePowerOf2Sizes`` flag. See
+     :manual:`collMod </reference/command/collMod>` and
+     :manual:`db.createCollection()
+     </reference/method/db.createCollection>` for more information.
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
+optional: true
 position: 4
 ---
 arg_name: option
+name: indexOptionDefaults
+type: array|object
+description: |
+  Allows users to specify a default configuration for indexes when creating a
+  collection.
+
+  The ``indexOptionDefaults`` option accepts a ``storageEngine`` document,
+  which should take the following form::
+
+     { <storage-engine-name>: <options> }
+
+  Storage engine configurations specified when creating indexes are validated
+  and logged to the :term:`oplog` during replication to support replica sets
+  with members that use different storage engines.
+interface: phpmethod
+operation: MongoDB\\Database::createCollection
+optional: true
+position: 5
+---
+arg_name: option
 name: max
 type: integer
 description: |
@@ -75,11 +86,30 @@ description: |
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
 optional: true
-position: 5
+position: 6
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: maxTimeMS
+operation: MongoDB\\Database::createCollection
+position: 7
+---
+arg_name: option
+name: size
+type: integer
+description: |
+  Specify a maximum size in bytes for a capped collection. Once a capped
+  collection reaches its maximum size, MongoDB removes the older documents to
+  make space for the new documents. The ``size`` option is required for capped
+  collections and ignored for other collections.
+interface: phpmethod
+operation: MongoDB\\Database::createCollection
+optional: true
+position: 8
 ---
 arg_name: option
 name: storageEngine
-type: array
+type: array|object
 description: |
   Available for the WiredTiger storage engine only.
 
@@ -95,144 +125,108 @@ description: |
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
 optional: true
-position: 6
+position: 9
 ---
-arg_name: option
-name: flags
-type: integer
-description: |
-
-  Available for the MMAPv1 storage engine only to set the
-  ``usePowerOf2Sizes`` and ``noPadding`` flags.
-  
-  The |php-library| provides constants that you can combine with a
-  :php:`bitwise OR operator <language.operators.bitwise>` to set the
-  flag values:
-  
-  - ``MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES``: ``1``
-  - ``MongoDB\Operation\CreateCollection::NO_PADDING``: ``2``
-
-  Defaults to ``1``.
-  
-  .. note:: 
-
-     MongoDB 3.0 and later ignores the ``usePowerOf2Sizes`` flag. See
-     :manual:`collMod </reference/command/collMod>` and
-     :manual:`db.createCollection()
-     </reference/method/db.createCollection>` for more information.
-
-interface: phpmethod
+source:
+  file: apiargs-common-option.yaml
+  ref: typeMap
 operation: MongoDB\\Database::createCollection
-optional: true
-position: 7
+position: 10
+description: |
+  Type map for BSON deserialization. This will be used for the returned command
+  result document. Defaults to the database's type map.
 ---
 arg_name: option
 name: validator
 type: array
 description: |
   Allows users to specify :manual:`validation rules or expressions
-  </core/document-validation>` for the collection. For more information,
-  see :manual:`Document Validation </core/document-validation>`
-  in the MongoDB manual.
+  </core/document-validation>` for the collection. For more information, see
+  :manual:`Document Validation </core/document-validation>` in the MongoDB
+  manual.
 
-  The ``validator`` option takes an array that specifies the
-  validation rules or expressions. You can specify the expressions using
-  the same operators as MongoDB's :manual:`query operators </reference/operator/query>`
-  with the exception of :query:`$geoNear`, :query:`$near`,
-  :query:`$nearSphere`, :query:`$text`, and :query:`$where`.
+  The ``validator`` option takes an array that specifies the validation rules or
+  expressions. You can specify the expressions using the same operators as
+  MongoDB's :manual:`query operators </reference/operator/query>` with the
+  exception of :query:`$geoNear`, :query:`$near`, :query:`$nearSphere`,
+  :query:`$text`, and :query:`$where`.
 
   .. note::
 
-     - Validation occurs during updates and inserts. Existing
-       documents do not undergo validation checks until modification.
+     - Validation occurs during updates and inserts. Existing documents do not
+       undergo validation checks until modification.
 
      - You cannot specify a validator for collections in the ``admin``,
        ``local``, and ``config`` databases.
 
      - You cannot specify a validator for ``system.*`` collections.
-
 operation: MongoDB\\Database::createCollection
 interface: phpmethod
 optional: true
-position: 8
+position: 11
 ---
 arg_name: option
-name: validationLevel
+name: validationAction
 type: string
 description: |
-   Determines how strictly MongoDB applies the
-   validation rules to existing documents during an update.
+   Determines whether to ``error`` on invalid documents or just ``warn`` about
+   the violations but allow invalid documents to be inserted.
+
+   .. important::
+
+      Validation of documents only applies to those documents as determined by
+      the ``validationLevel``.
 
    .. list-table::
       :header-rows: 1
 
-      * - ``validationLevel``
+      * - ``validationAction``
 
         - Description
 
-      * - ``"off"``
-
-        - No validation for inserts or updates.
-
-      * - ``"strict"``
-
-        - **Default** Apply validation rules to all inserts and all
-          updates.
+      * - ``"error"``
 
-      * - ``"moderate"``
+        - **Default**. Documents must pass validation before the write occurs.
+          Otherwise, the write operation fails.
 
-        - Apply validation rules to inserts and to updates on existing *valid*
-          documents. Do not apply rules to updates on existing *invalid*
-          documents.
+      * - ``"warn"``
 
+        - Documents do not have to pass validation. If the document fails
+          validation, the write operation logs the validation failure.
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
 optional: true
-position: 9
+position: 12
 ---
 arg_name: option
-name: validationAction
+name: validationLevel
 type: string
 description: |
-   Determines whether to ``error`` on invalid documents or just ``warn``
-   about the violations but allow invalid documents to be inserted.
-
-   .. important::
-
-      Validation of documents only applies to those documents as
-      determined by the ``validationLevel``.
+   Determines how strictly MongoDB applies the validation rules to existing
+   documents during an update.
 
    .. list-table::
       :header-rows: 1
 
-      * - ``validationAction``
+      * - ``validationLevel``
 
         - Description
 
-      * - ``"error"``
+      * - ``"off"``
 
-        - **Default** Documents must pass validation before the write occurs.
-          Otherwise, the write operation fails.
+        - No validation for inserts or updates.
 
-      * - ``"warn"``
+      * - ``"strict"``
 
-        - Documents do not have to pass validation. If the document fails
-          validation, the write operation logs the validation failure.
+        - **Default**. Apply validation rules to all inserts and all updates.
 
+      * - ``"moderate"``
+
+        - Apply validation rules to inserts and to updates on existing *valid*
+          documents. Do not apply rules to updates on existing *invalid*
+          documents.
 interface: phpmethod
 operation: MongoDB\\Database::createCollection
 optional: true
-position: 10
----
-source:
-  file: apiargs-common-option.yaml
-  ref: maxTimeMS
-operation: MongoDB\\Database::createCollection
-position: 11
----
-source:
-  file: apiargs-common-option.yaml
-  ref: typeMap
-operation: MongoDB\\Database::createCollection
-position: 12
+position: 13
 ...

docs/includes/apiargs-MongoDBDatabase-method-createCollection-param.yaml

@@ -3,12 +3,12 @@ source:
   ref: $collectionName
 operation: MongoDB\\Database::createCollection
 position: 1
-optional: false
+replacement:
+  action: " to create"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
 operation: MongoDB\\Database::createCollection
 position: 2
-optional: true
 ...

docs/includes/apiargs-MongoDBDatabase-method-drop-option.yaml

 source:
   file: apiargs-common-option.yaml
   ref: typeMap
-operation: MongoDB\\Database::dropCollection
+operation: MongoDB\\Database::drop
 position: 1
+description: |
+  Type map for BSON deserialization. This will be used for the returned command
+  result document. Defaults to the database's type map.
 ...

docs/includes/apiargs-MongoDBDatabase-method-drop-param.yaml

-source:
-  file: apiargs-common-param.yaml
-  ref: $collectionName
-operation: MongoDB\\Database::dropCollection
-position: 1
-optional: false
----
 source:
   file: apiargs-common-param.yaml
   ref: $options
-operation: MongoDB\\Database::dropCollection
-position: 2
-optional: true
+operation: MongoDB\\Database::drop
+position: 1
 ...

docs/includes/apiargs-MongoDBDatabase-method-dropCollection-option.yaml

@@ -3,4 +3,7 @@ source:
   ref: typeMap
 operation: MongoDB\\Database::dropCollection
 position: 1
+description: |
+  Type map for BSON deserialization. This will be used for the returned command
+  result document. Defaults to the database's type map.
 ...

docs/includes/apiargs-MongoDBDatabase-method-dropCollection-param.yaml

@@ -3,12 +3,12 @@ source:
   ref: $collectionName
 operation: MongoDB\\Database::dropCollection
 position: 1
-optional: false
+replacement:
+  action: " to drop"
 ---
 source:
   file: apiargs-common-param.yaml
   ref: $options
 operation: MongoDB\\Database::dropCollection
 position: 2
-optional: true
 ...

docs/includes/apiargs-MongoDBDatabase-method-get-param.yaml

@@ -3,4 +3,6 @@ source:
   ref: $collectionName
 operation: MongoDB\\Database::__get
 position: 1
+replacement:
+  action: " to select"
 ...

docs/includes/apiargs-MongoDBDatabase-method-listCollections-option.yaml

-source:
-  file: apiargs-common-option.yaml
-  ref: readConcern
+arg_name: option
+name: filter
+type: array|object
+description: |
+  Query by which to filter collections.
+interface: phpmethod
 operation: MongoDB\\Database::listCollections
+optional: true
 position: 1
 ---
 source:
   file: apiargs-common-option.yaml
-  ref: readPreference
+  ref: maxTimeMS
 operation: MongoDB\\Database::listCollections
 position: 2
----
-source:
-  file: apiargs-common-option.yaml
-  ref: typeMap
-operation: MongoDB\\Database::listCollections
-position: 3
----
-source:
-  file: apiargs-common-option.yaml
-  ref: writeConcern
-operation: MongoDB\\Database::listCollections
-position: 4
 ...

docs/includes/apiargs-MongoDBDatabase-method-listCollections-param.yaml

@@ -3,5 +3,4 @@ source:
   ref: $options
 operation: MongoDB\\Database::listCollections
 position: 1
-optional: true
 ...

docs/includes/apiargs-MongoDBDatabase-method-selectCollection-option.yaml

@@ -3,22 +3,33 @@ source:
   ref: readConcern
 operation: MongoDB\\Database::selectCollection
 position: 1
+replacement:
+  resource: "collection"
+  parent: "database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
 operation: MongoDB\\Database::selectCollection
 position: 2
+replacement:
+  resource: "collection"
+  parent: "database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
 operation: MongoDB\\Database::selectCollection
 position: 3
+replacement:
+  parent: "database"
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
 operation: MongoDB\\Database::selectCollection
 position: 4
+replacement:
+  resource: "collection"
+  parent: "database"
 ...

docs/includes/apiargs-MongoDBDatabase-method-selectCollection-param.yaml

@@ -3,7 +3,8 @@ source:
   ref: $collectionName
 operation: MongoDB\\Database::selectCollection
 position: 1
-optional: false
+replacement:
+  action: " to select"
 ---
 source:
   file: apiargs-common-param.yaml

docs/includes/apiargs-MongoDBDatabase-method-withOptions-option.yaml

@@ -3,30 +3,30 @@ source:
   ref: readConcern
 operation: MongoDB\\Database::withOptions
 description: |
-  The default read concern to use for database operations. Defaults
-  to the original Databases's specified read concern.
+  The default read concern to use for database operations. Defaults to the
+  original Databases's read concern.
 ---
 source:
   file: apiargs-common-option.yaml
   ref: readPreference
 operation: MongoDB\\Database::withOptions
 description: |
-  The default read preference to use for database operations.
-  Defaults to the original Database's read preference.
+  The default read preference to use for database operations. Defaults to the
+  original Database's read preference.
 ---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap
 operation: MongoDB\\Database::withOptions
 description: |
-  Default type map for cursors and BSON documents. Defaults to the
-  original Database's type map value.
+  Default type map to use for converting BSON. Defaults to the original
+  Database's type map.
 ---
 source:
   file: apiargs-common-option.yaml
   ref: writeConcern
 operation: MongoDB\\Database::withOptions
 description: |
-  The default write concern to use for database operations. Defaults
-  to the original Database's specified write concern.
+  The default write concern to use for database operations. Defaults to the
+  original Database's write concern.
 ...

docs/includes/apiargs-MongoDBDatabase-method-withOptions-param.yaml

 source:
-  ref: $options
   file: apiargs-common-param.yaml
+  ref: $options
 operation: MongoDB\\Database::withOptions
 position: 1
 ...

docs/reference/class/MongoDBDatabase.txt

@@ -44,8 +44,8 @@ Methods
 .. toctree::
    :titlesonly:
 
-   /reference/method/MongoDBDatabase__get
    /reference/method/MongoDBDatabase__construct
+   /reference/method/MongoDBDatabase__get
    /reference/method/MongoDBDatabase-command
    /reference/method/MongoDBDatabase-createCollection
    /reference/method/MongoDBDatabase-drop

docs/reference/method/MongoDBDatabase-command.txt

@@ -13,7 +13,7 @@ MongoDB\\Database::command()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::command
+.. phpmethod:: MongoDB\\Database::command()
 
    Execute a :manual:`command </reference/command>` on the database.
 
@@ -21,100 +21,121 @@ Definition
 
       function command($command, array $options = []): MongoDB\Driver\Cursor
 
-   :phpmethod:`MongoDB\\Database::command` has the following parameters:
+   :phpmethod:`MongoDB\\Database::command()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-command-param.rst
 
-   ``command`` supports the following options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-command-option.rst
 
+   :returns:
+
+      A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` object.
+
 Example
 -------
 
-The following operation creates a new user in the database using
-the :dbcommand:`createUser` command:
+The following example executes an :manual:`isMaster
+</reference/command/isMaster>` command, which returns a cursor with a single
+result document:
 
 .. code-block:: php
 
+   <?php
+
    $database = (new MongoDB\Client)->example;
 
-   $newUser = $database->command(
-       [
-           'createUser' => 'admin',
-           'pwd' => 'admin123',
-           'roles' => [
-               'readWrite'
-           ]
-       ]
-   );
+   $cursor = $database->command(['isMaster' => 1]);
+
+   var_dump($c->toArray()[0]);
+
+The output would resemble::
 
+   object(MongoDB\Model\BSONDocument)#11 (1) {
+     ["storage":"ArrayObject":private]=>
+     array(8) {
+       ["ismaster"]=>
+       bool(true)
+       ["maxBsonObjectSize"]=>
+       int(16777216)
+       ["maxMessageSizeBytes"]=>
+       int(48000000)
+       ["maxWriteBatchSize"]=>
+       int(1000)
+       ["localTime"]=>
+       object(MongoDB\BSON\UTCDateTime)#3 (1) {
+         ["milliseconds"]=>
+         string(13) "1477608046464"
+       }
+       ["maxWireVersion"]=>
+       int(4)
+       ["minWireVersion"]=>
+       int(0)
+       ["ok"]=>
+       float(1)
+     }
+   }
+
+The following example executes a :manual:`listCollections
+</reference/command/listCollections>` command, which returns a cursor with
+multiple result documents:
+
+.. code-block:: php
+
+   <?php
+
+   $database = (new MongoDB\Client)->example;
 
+   $cursor = $database->command(['isMaster' => 1]);
 
-   var_dump($newUser);
+   var_dump($c->toArray());
 
 The output would resemble::
 
-  object(MongoDB\Driver\Cursor)#10 (2) {
-     ["cursor"]=>
-     array(17) {
-       ["stamp"]=>
-       int(0)
-       ["is_command"]=>
-       bool(true)
-       ["sent"]=>
-       bool(true)
-       ["done"]=>
-       bool(false)
-       ["end_of_event"]=>
-       bool(false)
-       ["in_exhaust"]=>
-       bool(false)
-       ["has_fields"]=>
-       bool(false)
-       ["query"]=>
-       object(stdClass)#9 (3) {
-         ["createUser"]=>
-         string(5) "admin"
-         ["pwd"]=>
-         string(8) "admin123"
-         ["roles"]=>
-         array(1) {
+   array(3) {
      [0]=>
-           string(9) "readWrite"
+     object(MongoDB\Model\BSONDocument)#11 (1) {
+       ["storage":"ArrayObject":private]=>
+       array(2) {
+         ["name"]=>
+         string(11) "restaurants"
+         ["options"]=>
+         object(MongoDB\Model\BSONDocument)#3 (1) {
+           ["storage":"ArrayObject":private]=>
+           array(0) {
            }
          }
-       ["fields"]=>
-       object(stdClass)#3 (0) {
        }
-       ["read_preference"]=>
+     }
+     [1]=>
+     object(MongoDB\Model\BSONDocument)#13 (1) {
+       ["storage":"ArrayObject":private]=>
        array(2) {
-         ["mode"]=>
-         int(1)
-         ["tags"]=>
+         ["name"]=>
+         string(5) "users"
+         ["options"]=>
+         object(MongoDB\Model\BSONDocument)#12 (1) {
+           ["storage":"ArrayObject":private]=>
+           array(0) {
+           }
+         }
+       }
+     }
+     [2]=>
+     object(MongoDB\Model\BSONDocument)#15 (1) {
+       ["storage":"ArrayObject":private]=>
+       array(2) {
+         ["name"]=>
+         string(6) "restos"
+         ["options"]=>
+         object(MongoDB\Model\BSONDocument)#14 (1) {
+           ["storage":"ArrayObject":private]=>
            array(0) {
            }
          }
-       ["flags"]=>
-       int(0)
-       ["skip"]=>
-       int(0)
-       ["limit"]=>
-       int(1)
-       ["count"]=>
-       int(1)
-       ["batch_size"]=>
-       int(0)
-       ["ns"]=>
-       string(12) "example.$cmd"
-       ["current_doc"]=>
-       object(stdClass)#8 (1) {
-         ["ok"]=>
-         float(1)
        }
      }
-     ["server_id"]=>
-     int(1)
    }
 
 .. seealso::
@@ -122,4 +143,6 @@ The output would resemble::
    - :doc:`/tutorial/commands`
    - :manual:`Database Commands </reference/command>` in the
      MongoDB manual
-     
+   - :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>`
+   - :php:`MongoDB\\Driver\\Manager::executeCommand()
+     <manual/en/mongodb-driver-manager.executecommand.php>`

docs/reference/method/MongoDBDatabase-createCollection.txt

@@ -13,7 +13,7 @@ MongoDB\\Database::createCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::createCollection
+.. phpmethod:: MongoDB\\Database::createCollection()
 
    Explicitly creates a collection.
 
@@ -21,37 +21,37 @@ Definition
 
       function createCollection($collectionName, array $options = []): array|object
 
-   MongoDB creates collections implicitly when you first reference
-   the collection in a command, such as when inserting a document
-   into a new collection. You may also explicitly create a collection
-   with specific options using the ``createCollection()``
-   method, or using :dbcommand:`create` in the :program:`mongo` shell.
+   MongoDB creates collections implicitly when you first reference the
+   collection in a command, such as when inserting a document into a new
+   collection. You may also explicitly create a collection with specific options
+   using the :phpmethod:`MongoDB\\Database::createCollection()` method, or using
+   :manual:`db.createCollection() </reference/method/db.createCollection/>` in
+   the :program:`mongo` shell.
 
    Explicitly creating collections enables you to create
    :manual:`capped collections </core/capped-collections>`, specify
    :manual:`document validation criteria </core/document-validation>`,
    or configure your storage engine or indexing options.
 
-   :phpmethod:`MongoDB\\Database::createCollection` has the following
+   :phpmethod:`MongoDB\\Database::createCollection()` has the following
    parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-createCollection-param.rst
 
-   The ``$options`` parameter accepts the following options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-createCollection-option.rst
 
-   Note that not all options are available on all versions of MongoDB.
-   Document Validation, for example, was added in MongoDB 3.2;
-   similarly, the WiredTiger storage engine is available only for
-   MongoDB 3.0 and later. Refer to the :manual:`create command
-   </reference/command/create>` reference in the MongoDB manual for
-   compatibility considerations.
+   Note that not all options are available on all versions of MongoDB. Document
+   validation, for example, was added in MongoDB 3.2; similarly, the WiredTiger
+   storage engine is available only for MongoDB 3.0 and later. Refer to the
+   :manual:`create </reference/command/create>` command reference in the MongoDB
+   manual for compatibility considerations.
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array.
+      An array or object with the result document of the :manual:`create
+      </reference/command/create>` command.
 
 Example
 -------
@@ -61,6 +61,8 @@ database with document validation criteria:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $result = $db->createCollection('users', [
@@ -70,12 +72,11 @@ database with document validation criteria:
        ],
    ]);
 
-   
    var_dump($result);
 
 The output would then resemble::
 
-   Object(MongoDB\Model\BSONDocument)#11 (1) {
+   object(MongoDB\Model\BSONDocument)#11 (1) {
      ["storage":"ArrayObject":private]=>
      array(1) {
        ["ok"]=>
@@ -85,5 +86,6 @@ The output would then resemble::
 
 .. seealso::
 
-   :manual:`create </reference/command/create>` command reference in
-   the MongoDB manual
+   - :manual:`create </reference/command/create>` command reference in the MongoDB
+     manual
+   - :manual:`db.createCollection() </reference/method/db.createCollection/>`

docs/reference/method/MongoDBDatabase-drop.txt

@@ -13,27 +13,27 @@ MongoDB\\Database::drop()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::drop
+.. phpmethod:: MongoDB\\Database::drop()
 
-   Drops the database.
+   Drop the database.
 
    .. code-block:: php
 
-      function dropCollection($collectionName, array $options = []): array|object
+      function drop(array $options = []): array|object
 
-   :phpmethod:`MongoDB\\Database::drop` has the following
-   parameters:
+   :phpmethod:`MongoDB\\Database::drop()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-drop-param.rst
 
-   The ``$options`` parameter accepts the following options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-drop-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array.
+      An array or object with the result document of the :manual:`dropDatabase
+      </reference/command/dropDatabase>` command. The return type will depend on
+      the ``typeMap`` option.
 
 Example
 -------
@@ -42,11 +42,12 @@ The following example drops the ``demo`` database:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $result = $db->drop();
 
-   
    var_dump($result);
 
 The output would then resemble::
@@ -63,6 +64,6 @@ The output would then resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Client::dropDatabase`
-   - :manual:`dropDatabase </reference/command/dropDatabase>` command
-     reference in the MongoDB manual
+   - :phpmethod:`MongoDB\\Client::dropDatabase()`
+   - :manual:`dropDatabase </reference/command/dropDatabase>` command reference
+     in the MongoDB manual

docs/reference/method/MongoDBDatabase-dropCollection.txt

@@ -13,7 +13,7 @@ MongoDB\\Database::dropCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::dropCollection
+.. phpmethod:: MongoDB\\Database::dropCollection()
 
    Drop a collection within the current database.
 
@@ -21,33 +21,34 @@ Definition
 
       function dropCollection($collectionName, array $options = []): array|object
 
-   :phpmethod:`MongoDB\\Database::dropCollection` has the following
+   :phpmethod:`MongoDB\\Database::dropCollection()` has the following
    parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-dropCollection-param.rst
 
-   The ``$options`` parameter accepts the following options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-dropCollection-option.rst
 
-Output
-------
+   :returns:
 
-Returns the command result document as an array.
+      An array or object with the result document of the :manual:`drop
+      </reference/command/drop>` command. The return type will depend on
+      the ``typeMap`` option.
 
 Example
 -------
 
-The following example drops the ``users`` collection in the ``demo``
-database:
+The following example drops the ``users`` collection in the ``demo`` database:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $result = $db->dropCollection('users');
 
-   
    var_dump($result);
 
 The output would then resemble::
@@ -66,6 +67,6 @@ The output would then resemble::
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::drop`
-   - :manual:`drop </reference/command/drop>` command reference in
-     the MongoDB manual
+   - :phpmethod:`MongoDB\\Collection::drop()`
+   - :manual:`drop </reference/command/drop>` command reference in the MongoDB
+     manual

docs/reference/method/MongoDBDatabase-getDatabaseName.txt

@@ -13,27 +13,27 @@ MongoDB\\Database::getDatabaseName()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::getDatabaseName
+.. phpmethod:: MongoDB\\Database::getDatabaseName()
 
-   Drops the database.
+   Returns the name of this database.
 
    .. code-block:: php
 
       function getDatabaseName(): string
 
-Output
-------
+   :returns:
 
-Returns the name of the database as a string.
+      The name of this database as a string.
 
 Example
 -------
 
-The following example gets the name of the database from the ``$db``
-variable:
+The following example prints the name of a database object:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    echo $db->getDatabaseName();

docs/reference/method/MongoDBDatabase-getManager.txt

@@ -17,7 +17,7 @@ Definition
 
    Accessor for the
    :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` used by this
-   :phpclass:`Client <MongoDB\\Database>`.
+   :phpclass:`Database <MongoDB\\Database>`.
 
    .. code-block:: php
 

docs/reference/method/MongoDBDatabase-listCollections.txt

@@ -13,34 +13,33 @@ MongoDB\\Database::listCollections()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::listCollections
+.. phpmethod:: MongoDB\\Database::listCollections()
 
    Returns information for all collections in this database.
 
    .. code-block:: php
 
-      function listCollections(array $options=[]): MongoDB\Model\CollectionInfoIterator
+      function listCollections(array $options = []): MongoDB\Model\CollectionInfoIterator
 
-   :phpmethod:`MongoDB\\Database::listCollections` has the following
+   :phpmethod:`MongoDB\\Database::listCollections()` has the following
    parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-listCollections-param.rst
 
-   The ``$options`` parameter accepts the following options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-listCollections-option.rst
 
-Output
-------
+   :returns:
 
-Returns information for all collections in the database. The elements
-in the returned iterator are ``MongoDB\Model\CollectionInfo`` objects.
+      A traversable :phpclass:`MongoDB\\Model\CollectionInfoIterator`, which
+      contains an :phpclass:`MongoDB\\Model\CollectionInfo` object for each
+      collection in the database.
 
 Example
 -------
 
-The following example lists all of the collections in the ``example``
-database:
+The following example lists all of the collections in the ``example`` database:
 
 .. code-block:: php
 
@@ -61,7 +60,7 @@ The output would then resemble::
      array(0) {
      }
    }
-   object(MongoDB\Model\CollectionInfo)#11 (2) {
+   object(MongoDB\Model\CollectionInfo)#3 (2) {
      ["name"]=>
      string(5) "users"
      ["options"]=>
@@ -76,10 +75,46 @@ The output would then resemble::
      }
    }
 
-.. seealso::
+The following example lists all collections whose name starts with ``"rest"``
+in the ``example`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $database = (new MongoDB\Client)->example;
+
+   $collections = $database->listCollections([
+       'filter' => [
+           'name' => new MongoDB\BSON\Regex('^rest.*'),
+       ],
+   ]);
+
+   foreach ($collections as $collectionInfo) {
+       var_dump($collectionInfo);
+   }
+
+The output would then resemble::
+
+   object(MongoDB\Model\CollectionInfo)#3 (2) {
+     ["name"]=>
+     string(11) "restaurants"
+     ["options"]=>
+     array(0) {
+     }
+   }
+   object(MongoDB\Model\CollectionInfo)#3 (2) {
+     ["name"]=>
+     string(6) "restos"
+     ["options"]=>
+     array(0) {
+     }
+   }
 
-   - :manual:`listCollections </reference/command/listCollections`
-     command reference in the MongoDB manual.
+.. seealso::
 
-   - MongoDB Specification `Enumerating Collections 
+   - :manual:`listCollections </reference/command/listCollections` command
+     reference in the MongoDB manual
+   - `Enumerating Collections
      <https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst>`_
+     specification

docs/reference/method/MongoDBDatabase-selectCollection.txt

@@ -13,38 +13,54 @@ MongoDB\\Database::selectCollection()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::selectCollection
+.. phpmethod:: MongoDB\\Database::selectCollection()
 
-   Selects a collection within the database. The collection inherits
-   options such as read preference and type map from the Database object
-   unless otherwise specified in the ``$options`` parameter.
+   Selects a collection within the database.
 
    .. code-block:: php
 
       function selectCollection($collectionName, array $options = []): MongoDB\Collection
 
-   :phpmethod:`MongoDB\\Database::selectCollection` has the following
+   :phpmethod:`MongoDB\\Database::selectCollection()` has the following
    parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-selectCollection-param.rst
 
-   The ``$options`` parameter accepts the following options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-selectCollection-option.rst
 
-Output
-------
+   :returns:
 
-Returns a :phpclass:`MongoDB\\Collection` object.
+      A :phpclass:`MongoDB\\Collection` object.
+
+Behavior
+--------
+
+The selected collection inherits options such as read preference and type
+mapping from the :phpclass:`Database <MongoDB\\Database>` object. Options may be
+overridden via the ``$options`` parameter.
 
 Example
 -------
 
+The following example selects the ``users`` collection in the ``demo`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $db = (new MongoDB\Client)->demo;
+
+   $collection = $db->selectCollection('demo', 'users');
+
 The following example selects the ``users`` collection in the ``demo``
 database with a custom read preference:
 
 .. code-block:: php
 
+   <?php
+
    $db = (new MongoDB\Client)->demo;
 
    $users = $db->selectCollection(
@@ -54,87 +70,8 @@ database with a custom read preference:
        ]
    );
 
-   
-   var_dump($users);
-
-The output would then resemble::
-
-   object(MongoDB\Collection)#8 (7) {
-     ["collectionName"]=>
-     string(5) "users"
-     ["databaseName"]=>
-     string(4) "demo"
-     ["manager"]=>
-     object(MongoDB\Driver\Manager)#2 (2) {
-       ["uri"]=>
-       string(25) "mongodb://localhost:27017"
-       ["cluster"]=>
-       array(1) {
-         [0]=>
-         array(11) {
-           ["host"]=>
-           string(9) "localhost"
-           ["port"]=>
-           int(27017)
-           ["type"]=>
-           int(0)
-           ["is_primary"]=>
-           bool(false)
-           ["is_secondary"]=>
-           bool(false)
-           ["is_arbiter"]=>
-           bool(false)
-           ["is_hidden"]=>
-           bool(false)
-           ["is_passive"]=>
-           bool(false)
-           ["tags"]=>
-           array(0) {
-           }
-           ["last_is_master"]=>
-           array(0) {
-           }
-           ["round_trip_time"]=>
-           int(-1)
-         }
-       }
-     }
-     ["readConcern"]=>
-     object(MongoDB\Driver\ReadConcern)#5 (1) {
-       ["level"]=>
-       NULL
-     }
-     ["readPreference"]=>
-     object(MongoDB\Driver\ReadPreference)#3 (2) {
-       ["mode"]=>
-       int(2)
-       ["tags"]=>
-       array(0) {
-       }
-     }
-     ["typeMap"]=>
-     array(3) {
-       ["array"]=>
-       string(23) "MongoDB\Model\BSONArray"
-       ["document"]=>
-       string(26) "MongoDB\Model\BSONDocument"
-       ["root"]=>
-       string(26) "MongoDB\Model\BSONDocument"
-     }
-     ["writeConcern"]=>
-     object(MongoDB\Driver\WriteConcern)#7 (4) {
-       ["w"]=>
-       NULL
-       ["wmajority"]=>
-       bool(false)
-       ["wtimeout"]=>
-       int(0)
-       ["journal"]=>
-       NULL
-     }
-   }   
-
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::__construct`
-   - :phpmethod:`MongoDB\\Database::__get`
+   - :phpmethod:`MongoDB\\Database::__get()`
+   - :phpmethod:`MongoDB\\Client::selectCollection()`
+   - :phpmethod:`MongoDB\\Collection::__construct()`

docs/reference/method/MongoDBDatabase-withOptions.txt

@@ -4,10 +4,16 @@ MongoDB\\Database::withOptions()
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::withOptions
+.. phpmethod:: MongoDB\\Database::withOptions()
 
    Returns a clone of the Database object, but with different options.
 
@@ -15,34 +21,34 @@ Definition
 
       function withOptions(array $options = []): MongoDB\Database
 
-   :phpmethod:`MongoDB\\Database::withOptions` supports the
-   following parameter:
+   :phpmethod:`MongoDB\\Database::withOptions()` has the following parameters:
 
-   .. include:: /includes/apiargs/MongoDBCollection-method-withOptions-param.rst
+   .. include:: /includes/apiargs/MongoDBDatabase-method-withOptions-param.rst
 
    The ``$options`` parameter supports the following options:
 
-   .. include:: /includes/apiargs/MongoDBCollection-method-withOptions-option.rst
+   .. include:: /includes/apiargs/MongoDBDatabase-method-withOptions-option.rst
+
+   :returns:
+
+      A :phpclass:`MongoDB\\Database` object.
 
 Example
 -------
 
-The following example clones the ``$newDb`` Database object with read
-preference ``RP_SECONDARY``.
+The following example clones an existing Database object with a new read
+preference:
 
 .. code-block:: php
 
    <?php
 
-   $database = new MongoDB\Client;
+   $db = (new MongoDB\Client)->demo;
 
-   $newDb = $database->withOptions('sample','restaurants');
-
-   $newCollection = $sourceCollection->withOptions([ 
+   $newDb = $db->withOptions([
        'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
    ]);
 
-
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Collection::__construct`
+   - :phpmethod:`MongoDB\\Database::__construct()`

docs/reference/method/MongoDBDatabase__construct.txt

@@ -13,7 +13,7 @@ MongoDB\\Database::__construct()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::__construct
+.. phpmethod:: MongoDB\\Database::__construct()
 
    Constructs a new :phpclass:`Database <MongoDB\\Database>` instance.
 
@@ -25,16 +25,20 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-construct-param.rst
 
-   :phpmethod:`MongoDB\\Database::__construct` supports the following
-   options:
+   The ``$options`` parameter supports the following options:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-construct-option.rst
 
-   If you construct the Database explicitly, the Database inherits any
-   options from the ``Manager`` object. If you select the Database
-   from a :phpclass:`Client <MongoDB\\Client>` object, the Database
-   inherits its options from that object.
+Behavior
+--------
+
+If you construct a Database explicitly, the Database inherits any options from
+the :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` object. If
+you select the Database from a :phpclass:`Client <MongoDB\\Client>` object, the
+Database inherits its options from that object.
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Database::withOptions`
+   - :phpmethod:`MongoDB\\Database::withOptions()`
+   - :phpmethod:`MongoDB\\Client::selectDatabase()`
+   - :phpmethod:`MongoDB\\Client::__get()`

docs/reference/method/MongoDBDatabase__get.txt

@@ -4,7 +4,6 @@ MongoDB\\Database::__get()
 
 .. default-domain:: mongodb
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -14,25 +13,29 @@ MongoDB\\Database::__get()
 Definition
 ----------
 
-.. phpmethod:: MongoDB\\Database::__get($collectionName)
+.. phpmethod:: MongoDB\\Database::__get()
 
-   Select a collection from the database.
+   Select a collection within the database.
 
    .. code-block:: php
 
       function __get($collectionName): MongoDB\Collection
 
-   :phpmethod:`MongoDB\\Database::__get` has the following parameters:
+   :phpmethod:`MongoDB\\Database::__get()` has the following parameters:
 
    .. include:: /includes/apiargs/MongoDBDatabase-method-get-param.rst
 
+   :returns:
+
+      A :phpclass:`MongoDB\\Collection` object.
+
 Behavior
 --------
 
-The selected database inherits options such as read preference and
-type mapping from the :phpclass:`Database  <MongoDB\\Database>` object.
-If you wish to override any options, use the 
-:phpmethod:`MongoDB\\Database::selectCollection` method.
+The selected collection inherits options such as read preference and type
+mapping from the :phpclass:`Database <MongoDB\\Database>` object. If you wish to
+override any options, use the :phpmethod:`MongoDB\\Database::selectCollection`
+method.
 
 .. note::
 
@@ -40,7 +43,7 @@ If you wish to override any options, use the
    ``.``, use complex syntax, as in ``$database->{'that.database'}``.
 
    Alternatively, :phpmethod:`MongoDB\\Database::selectCollection` supports
-   selecting databases whose names contain special characters.
+   selecting collections whose names contain special characters.
 
 Examples
 --------
@@ -59,5 +62,6 @@ collections from the ``demo`` database:
 
 .. seealso::
 
-   - :phpmethod:`MongoDB\\Database::selectCollection`
-   - :php:`Property Overloading <oop5.overloading>` in the PHP Manual.
+   - :phpmethod:`MongoDB\\Database::selectCollection()`
+   - :phpmethod:`MongoDB\\Client::selectCollection()`
+   - :php:`Property Overloading <oop5.overloading>` in the PHP Manual