DOCSP-44644: db/coll accessor methods

.github/workflows/vale-tdbx.yml

@@ -12,23 +12,26 @@ jobs:
       - name: checkout
         uses: actions/checkout@v4
 
+      - name: Install docutils
+        run: sudo apt-get install -y docutils
+
       - id: files
         uses: masesgroup/retrieve-changed-files@v2
         with:
-          format: 'csv'
+          format: "csv"
 
       - name: checkout-latest-rules
         uses: actions/checkout@v4
         with:
           repository: mongodb/mongodb-vale-action
-          path: './tdbx-vale-rules'
+          path: "./tdbx-vale-rules"
           token: ${{secrets.GITHUB_TOKEN}}
 
       - name: move-files-for-vale-action
         run: |
-            cp tdbx-vale-rules/.vale.ini .vale.ini
-            mkdir -p .github/styles/
-            cp -rf tdbx-vale-rules/.github/styles/ .github/
+          cp tdbx-vale-rules/.vale.ini .vale.ini
+          mkdir -p .github/styles/
+          cp -rf tdbx-vale-rules/.github/styles/ .github/
 
       - name: run-vale
         uses: errata-ai/vale-action@reviewdog

source/reference/class/MongoDBClient.txt

@@ -2,8 +2,6 @@
 MongoDB\\Client Class
 =====================
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -33,6 +31,8 @@ Methods
    addSubscriber() </reference/method/MongoDBClient-addSubscriber>
    createClientEncryption() </reference/method/MongoDBClient-createClientEncryption>
    dropDatabase() </reference/method/MongoDBClient-dropDatabase>
+   getCollection() </reference/method/MongoDBClient-getCollection>
+   getDatabase() </reference/method/MongoDBClient-getDatabase>
    getManager() </reference/method/MongoDBClient-getManager>
    getReadConcern() </reference/method/MongoDBClient-getReadConcern>
    getReadPreference() </reference/method/MongoDBClient-getReadPreference>
@@ -51,6 +51,8 @@ Methods
 - :phpmethod:`MongoDB\Client::addSubscriber()`
 - :phpmethod:`MongoDB\Client::createClientEncryption()`
 - :phpmethod:`MongoDB\Client::dropDatabase()`
+- :phpmethod:`MongoDB\Client::getCollection()`
+- :phpmethod:`MongoDB\Client::getDatabase()`
 - :phpmethod:`MongoDB\Client::getManager()`
 - :phpmethod:`MongoDB\Client::getReadConcern()`
 - :phpmethod:`MongoDB\Client::getReadPreference()`

source/reference/class/MongoDBCollection.txt

@@ -22,7 +22,7 @@ Definition
    :php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>` class or
    select a collection from the library's :phpclass:`MongoDB\Client` or
    :phpclass:`MongoDB\Database` classes. A collection may also be cloned from
-   an existing :phpclass:`MongoDB\Collection` object via the
+   an existing :phpclass:`MongoDB\Collection` object by using the
    :phpmethod:`withOptions() <MongoDB\Collection::withOptions()>` method.
 
    :phpclass:`MongoDB\Collection` supports the :php:`readConcern

source/reference/class/MongoDBDatabase.txt

@@ -2,8 +2,6 @@
 MongoDB\\Database Class
 =======================
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -22,7 +20,7 @@ Definition
    :php:`MongoDB\Driver\Manager <class.mongodb-driver-manager>` class or
    select a database from the library's :phpclass:`MongoDB\Client` class. A
    database may also be cloned from an existing :phpclass:`MongoDB\Database`
-   object via the :phpmethod:`withOptions() <MongoDB\Database::withOptions()>`
+   object by using the :phpmethod:`withOptions() <MongoDB\Database::withOptions()>`
    method.
 
    :phpclass:`MongoDB\Database` supports the :php:`readConcern
@@ -51,6 +49,7 @@ Methods
    createEncryptedCollection() </reference/method/MongoDBDatabase-createEncryptedCollection>
    drop() </reference/method/MongoDBDatabase-drop>
    dropCollection() </reference/method/MongoDBDatabase-dropCollection>
+   getCollection() </reference/method/MongoDBDatabase-getCollection>
    getDatabaseName() </reference/method/MongoDBDatabase-getDatabaseName>
    getManager() </reference/method/MongoDBDatabase-getManager>
    getReadConcern() </reference/method/MongoDBDatabase-getReadConcern>
@@ -75,6 +74,7 @@ Methods
 - :phpmethod:`MongoDB\Database::drop()`
 - :phpmethod:`MongoDB\Database::dropCollection()`
 - :phpmethod:`MongoDB\Database::getDatabaseName()`
+- :phpmethod:`MongoDB\Database::getCollection()`
 - :phpmethod:`MongoDB\Database::getManager()`
 - :phpmethod:`MongoDB\Database::getReadConcern()`
 - :phpmethod:`MongoDB\Database::getReadPreference()`

source/reference/method/MongoDBClient-getCollection.txt

@@ -0,0 +1,126 @@
+================================
+MongoDB\\Client::getCollection()
+================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\Client::getCollection()
+
+   Gets access to a collection on the server. This method is an alias for
+   :phpmethod:`MongoDB\Client::selectCollection()` and will replace it in
+   a future release.
+
+   .. code-block:: php
+
+      function getCollection(
+          string $databaseName,
+          string $collectionName,
+          array $options = []
+      ): MongoDB\Collection
+
+Parameters
+----------
+
+``$databaseName`` : string
+  The name of the database containing the collection to access.
+
+``$collectionName`` : string
+  The name of the collection to access.
+
+``$options`` : array
+  An array specifying the desired options.
+
+  .. list-table::
+     :header-rows: 1
+     :widths: 20 20 80
+
+     * - Name
+       - Type
+       - Description
+
+     * - codec
+       - MongoDB\\Codec\\DocumentCodec
+       - The default :doc:`codec </data-formats/codecs>` to use for collection
+         operations.
+
+         .. versionadded:: 1.17
+
+     * - readConcern
+       - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
+       - The default read concern to use for collection operations. Defaults to
+         the client's read concern.
+
+     * - readPreference
+       - :php:`MongoDB\Driver\ReadPreference <class.mongodb-driver-readpreference>`
+       - The default read preference to use for collection operations. Defaults
+         to the client's read preference.
+
+     * - typeMap
+       - array
+       - The default type map to use for collection operations. Defaults to the
+         client's type map.
+
+     * - writeConcern
+       - :php:`MongoDB\Driver\WriteConcern <class.mongodb-driver-writeconcern>`
+       - The default write concern to use for collection operations. Defaults to
+         the client's write concern.
+
+Return Values
+-------------
+
+A :phpclass:`MongoDB\Collection` object.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+
+Behavior
+--------
+
+The selected collection inherits options such as read preference and type
+mapping from the :phpclass:`Client <MongoDB\Client>` object. Options may be
+overridden by using the ``$options`` parameter.
+
+Example
+-------
+
+The following example gets access to the ``users`` collection in the ``test`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $client = new MongoDB\Client;
+
+   $collection = $client->getCollection('test', 'users');
+
+The following example gets access to the ``users`` collection in the ``test`` database
+with a custom read preference:
+
+.. code-block:: php
+
+   <?php
+
+   $client = new MongoDB\Client;
+
+   $collection = $client->getCollection(
+       'test',
+       'users',
+       [
+           'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
+       ]
+   );
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\Collection::__construct()`
+- :phpmethod:`MongoDB\Database::getCollection()`

source/reference/method/MongoDBClient-getDatabase.txt

@@ -0,0 +1,114 @@
+==============================
+MongoDB\\Client::getDatabase()
+==============================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\Client::getDatabase()
+
+   Gets access to a database on the server. This method is an alias for
+   :phpmethod:`MongoDB\Client::selectDatabase()` and will replace it in
+   a future release.
+
+   .. code-block:: php
+
+      function getDatabase(
+          string $databaseName,
+          array $options = []
+      ): MongoDB\Database
+
+Parameters
+----------
+
+``$databaseName`` : string
+  The name of the database to access.
+
+``$options`` : array
+  An array specifying the desired options.
+
+  .. list-table::
+     :header-rows: 1
+     :widths: 20 20 80
+
+     * - Name
+       - Type
+       - Description
+
+     * - readConcern
+       - :php:`MongoDB\Driver\ReadConcern <class.mongodb-driver-readconcern>`
+       - The default read concern to use for database operations. Defaults to
+         the client's read concern.
+
+     * - readPreference
+       - :php:`MongoDB\Driver\ReadPreference <class.mongodb-driver-readpreference>`
+       - The default read preference to use for database operations. Defaults to
+         the client's read preference.
+
+     * - typeMap
+       - array
+       - The default type map to use for database operations. Defaults to the
+         client's type map.
+
+     * - writeConcern
+       - :php:`MongoDB\Driver\WriteConcern <class.mongodb-driver-writeconcern>`
+       - The default write concern to use for database operations. Defaults to
+         the client's write concern.
+
+Return Values
+-------------
+
+A :phpclass:`MongoDB\Database` object.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+
+Behavior
+--------
+
+The selected database inherits options such as read preference and type mapping
+from the :phpclass:`Client <MongoDB\Client>` object. Options may be overridden
+by using the ``$options`` parameter.
+
+Example
+-------
+
+The following example gets access to the ``test`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $client = new MongoDB\Client;
+
+   $db = $client->getDatabase('test');
+
+The following examples gets access to the ``test`` database with a custom read
+preference:
+
+.. code-block:: php
+
+   <?php
+
+   $client = new MongoDB\Client;
+
+   $db = $client->getDatabase(
+       'test',
+       [
+           'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
+       ]
+   );
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\Client::__get()`
+- :phpmethod:`MongoDB\Database::__construct()`

source/reference/method/MongoDBClient-selectCollection.txt

@@ -2,8 +2,6 @@
 MongoDB\\Client::selectCollection()
 ===================================
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -15,7 +13,9 @@ Definition
 
 .. phpmethod:: MongoDB\Client::selectCollection()
 
-   Selects a collection on the server.
+   Selects a collection on the server. This method is aliased by
+   :phpmethod:`MongoDB\Client::getCollection()` and will be replaced by
+   it in a future release.
 
    .. code-block:: php
 
@@ -87,7 +87,7 @@ Behavior
 
 The selected collection inherits options such as read preference and type
 mapping from the :phpclass:`Client <MongoDB\Client>` object. Options may be
-overridden via the ``$options`` parameter.
+overridden by using the ``$options`` parameter.
 
 Example
 -------