Merge pull request #189 from rustagir/DOCSP-44644-dbcoll-accessor-aliases

DOCSP-44644: db/coll access methods

Author: rustagir

source/data-formats/modeling-bson-data.txt

@@ -21,7 +21,7 @@ allows control over how BSON is converted to PHP. Additionally,
 the :phpclass:`MongoDB\Client`, :phpclass:`MongoDB\Database`, and
 :phpclass:`MongoDB\Collection` classes accept a ``typeMap`` option, which can
 be used to specify a default type map to apply to any supporting methods and
-selected classes (e.g. :phpmethod:`MongoDB\Client::selectDatabase()`).
+selected classes (e.g. :phpmethod:`MongoDB\Client::getDatabase()`).
 
 The :phpclass:`MongoDB\Client`, :phpclass:`MongoDB\Database`, and
 :phpclass:`MongoDB\Collection` classes use the following type map by

source/databases-collections.txt

@@ -40,7 +40,7 @@ MongoDB organizes data into a hierarchy of the following levels:
 Access a Database
 -----------------
 
-Access a database by passing the database name to the ``MongoDB\Client::selectDatabase()``
+Access a database by passing the database name to the ``MongoDB\Client::getDatabase()``
 method.
 
 The following example accesses a database named ``test_database``:
@@ -76,12 +76,12 @@ Access a Collection
 
 Access a collection by using either of the following methods:
 
-- ``MongoDB\Client::selectCollection()``: Pass the database and collection names as 
+- ``MongoDB\Client::getCollection()``: Pass the database and collection names as 
   parameters
-- ``MongoDB\Database::selectCollection()``: Pass the collection name as a parameter
+- ``MongoDB\Database::getCollection()``: Pass the collection name as a parameter
 
 The following example accesses a collection named ``test_collection`` by using the 
-``MongoDB\Database::selectCollection()`` method:
+``MongoDB\Database::getCollection()`` method:
 
 .. literalinclude:: /includes/databases-collections/databases-collections.php
     :language: php
@@ -198,10 +198,10 @@ by specifying a read preference, read concern, or write concern.
 
 By default, databases inherit read and write settings from the ``MongoDB\Client``
 instance. Collections inherit these settings from the ``MongoDB\Client`` or
-``MongoDB\Database`` instance on which the ``selectCollection()`` method is called.
+``MongoDB\Database`` instance on which the ``getCollection()`` method is called.
 You can change these settings by passing an options array to the
-``MongoDB\Client::selectDatabase()``, ``MongoDB\Client::selectCollection()``, or
-``MongoDB\Database::selectCollection()`` methods.
+``MongoDB\Client::getDatabase()``, ``MongoDB\Client::getCollection()``, or
+``MongoDB\Database::getCollection()`` methods.
 
 To learn more about setting a read preference, read concern, and write concern,
 see the :ref:`php-read-write-pref` guide.
@@ -212,9 +212,9 @@ API Documentation
 To learn more about any of the methods or types discussed in this
 guide, see the following API documentation:
 
-- :phpmethod:`MongoDB\Client::selectDatabase()`
-- :phpmethod:`MongoDB\Client::selectCollection()`
-- :phpmethod:`MongoDB\Database::selectCollection()`
+- :phpmethod:`MongoDB\Client::getDatabase()`
+- :phpmethod:`MongoDB\Client::getCollection()`
+- :phpmethod:`MongoDB\Database::getCollection()`
 - :phpmethod:`MongoDB\Database::createCollection()`
 - :phpmethod:`MongoDB\Database::listCollections()`
 - :phpmethod:`MongoDB\Database::dropCollection()`

source/examples/aws-lambda/index.php

@@ -9,7 +9,7 @@
 try {
     $client = new Client($uri);
     $planets = $client
-        ->selectCollection('sample_guides', 'planets')
+        ->getCollection('sample_guides', 'planets')
         ->find([], ['sort' => ['orderFromSun' => 1]]);
 } catch (Throwable $exception) {
     exit($exception->getMessage());

source/examples/codecs/handling-documents/using-codec.php

@@ -3,7 +3,7 @@
 use MongoDB\Client;
 
 $client = new Client();
-$collection = $client->selectCollection('test', 'person', [
+$collection = $client->getCollection('test', 'person', [
     'codec' => new PersonCodec(),
 ]);
 

source/examples/encryption/create_data_key.php

@@ -17,8 +17,8 @@
 /* Prepare the database for this script. Drop the key vault collection and
  * ensure it has a unique index for keyAltNames. This would typically be done
  * during application deployment. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], [
+$client->getCollection('encryption', '__keyVault')->drop();
+$client->getCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], [
     'unique' => true,
     'partialFilterExpression' => ['keyAltNames' => ['$exists' => true]],
 ]);

source/examples/encryption/csfle-automatic_encryption-local_schema.php

@@ -63,8 +63,8 @@
  * Note: without a server-side schema, another client could potentially insert
  * unencrypted data into the collection. Therefore, a local schema should always
  * be used in conjunction with a server-side schema. */
-$encryptedClient->selectDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
-$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
+$encryptedClient->getDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
+$encryptedCollection = $encryptedClient->getCollection('test', 'coll');
 
 /* Using the encrypted client, insert and find a document to demonstrate that
  * the encrypted field is automatically encrypted and decrypted. */
@@ -74,7 +74,7 @@
 
 /* Using the client configured without encryption, find the same document and
  * observe that the field is not automatically decrypted. */
-$unencryptedCollection = $client->selectCollection('test', 'coll');
+$unencryptedCollection = $client->getCollection('test', 'coll');
 
 print_r($unencryptedCollection->findOne(['_id' => 1]));
 

source/examples/encryption/csfle-automatic_encryption-server_side_schema.php

@@ -55,8 +55,8 @@
 
 /* Create a new collection for this script. Configure a server-side schema by
  * explicitly creating the collection with a "validator" option. */
-$encryptedClient->selectDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
-$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
+$encryptedClient->getDatabase('test')->createCollection('coll', ['validator' => ['$jsonSchema' => $schema]]);
+$encryptedCollection = $encryptedClient->getCollection('test', 'coll');
 
 /* Using the encrypted client, insert and find a document to demonstrate that
  * the encrypted field is automatically encrypted and decrypted. */
@@ -66,7 +66,7 @@
 
 /* Using the client configured without encryption, find the same document and
  * observe that the field is not automatically decrypted. */
-$unencryptedCollection = $client->selectCollection('test', 'coll');
+$unencryptedCollection = $client->getCollection('test', 'coll');
 
 print_r($unencryptedCollection->findOne(['_id' => 1]));
 

source/examples/encryption/csfle-explicit_encryption.php

@@ -36,7 +36,7 @@
     'keyId' => $keyId,
 ]);
 
-$collection = $client->selectCollection('test', 'coll');
+$collection = $client->getCollection('test', 'coll');
 $collection->insertOne(['_id' => 1, 'encryptedField' => $encryptedValue]);
 
 /* Using the client configured without encryption, find the document and observe

source/examples/encryption/csfle-explicit_encryption_automatic_decryption.php

@@ -42,7 +42,7 @@
     'keyId' => $keyId,
 ]);
 
-$collection = $client->selectCollection('test', 'coll');
+$collection = $client->getCollection('test', 'coll');
 $collection->insertOne(['_id' => 1, 'encryptedField' => $encryptedValue]);
 
 /* Using the client configured with encryption (but not automatic encryption),

source/examples/encryption/key_alt_name.php

@@ -18,8 +18,8 @@
 /* Prepare the database for this script. Drop the key vault collection and
  * ensure it has a unique index for keyAltNames. This would typically be done
  * during application deployment. */
-$client->selectCollection('encryption', '__keyVault')->drop();
-$client->selectCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], [
+$client->getCollection('encryption', '__keyVault')->drop();
+$client->getCollection('encryption', '__keyVault')->createIndex(['keyAltNames' => 1], [
     'unique' => true,
     'partialFilterExpression' => ['keyAltNames' => ['$exists' => true]],
 ]);

source/examples/encryption/queryable_encryption-automatic.php

@@ -59,8 +59,8 @@
  * infer encryptedFields from the client configuration and manage internal
  * encryption collections automatically. Alternatively, the "encryptedFields"
  * option can also be passed explicitly. */
-$encryptedClient->selectDatabase('test')->createCollection('coll');
-$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
+$encryptedClient->getDatabase('test')->createCollection('coll');
+$encryptedCollection = $encryptedClient->getCollection('test', 'coll');
 
 /* Using the encrypted client, insert a document and find it by querying on the
  * encrypted field. Fields will be automatically encrypted and decrypted. */
@@ -74,6 +74,6 @@
 
 /* Using the client configured without encryption, find the same document and
  * observe that fields are not automatically decrypted. */
-$unencryptedCollection = $client->selectCollection('test', 'coll');
+$unencryptedCollection = $client->getCollection('test', 'coll');
 
 print_r($unencryptedCollection->findOne(['_id' => 1]));

source/examples/encryption/queryable_encryption-explicit.php

@@ -59,8 +59,8 @@
  * option to ensure that internal encryption collections are also created. The
  * "encryptedFields" option should also be specified when dropping the
  * collection to ensure that internal encryption collections are dropped. */
-$encryptedClient->selectDatabase('test')->createCollection('coll', ['encryptedFields' => $encryptedFields]);
-$encryptedCollection = $encryptedClient->selectCollection('test', 'coll');
+$encryptedClient->getDatabase('test')->createCollection('coll', ['encryptedFields' => $encryptedFields]);
+$encryptedCollection = $encryptedClient->getCollection('test', 'coll');
 
 // Insert a document with manually encrypted fields
 $indexedInsertPayload = $clientEncryption->encrypt('indexedValue', [

source/includes/databases-collections/databases-collections.php

@@ -10,7 +10,7 @@
 
 // Accesses the "test_database" database
 // start-access-database
-$db = $client->selectDatabase('test_database');
+$db = $client->getDatabase('test_database');
 // end-access-database
 
 // Invokes the __get() method to access the "test_database" database
@@ -20,7 +20,7 @@
 
 // Accesses the "test_collection" collection
 // start-access-collection
-$collection = $client->test_database->selectCollection('test_collection');
+$collection = $client->test_database->getCollection('test_collection');
 // end-access-collection
 
 // Invokes the __get() method to access the "test_collection" collection
@@ -51,7 +51,7 @@
 $readConcern = new ReadConcern(ReadConcern::LOCAL);
 $writeConcern = new WriteConcern(WriteConcern::MAJORITY);
 
-$db = $client->selectDatabase('test_database', [
+$db = $client->getDatabase('test_database', [
     'readPreference' => $readPreference,
     'readConcern' => $readConcern,
     'writeConcern' => $writeConcern,
@@ -64,7 +64,7 @@
 $readConcern = new ReadConcern(ReadConcern::AVAILABLE);
 $writeConcern = new WriteConcern(WriteConcern::MAJORITY);
 
-$collection = $client->selectCollection('test_database', 'test_collection', [
+$collection = $client->getCollection('test_database', 'test_collection', [
     'readPreference' => $readPreference,
     'readConcern' => $readConcern,
     'writeConcern' => $writeConcern,
@@ -85,7 +85,7 @@
     ],
 );
 
-$db = $client->selectDatabase(
+$db = $client->getDatabase(
     'test_database',
     ['readPreference' => $readPreference],
 );

source/includes/read-write-pref.php

@@ -43,7 +43,7 @@
 
 // Sets read and write settings for the "test_database" database
 // start-database-settings
-$db = $client->selectDatabase('test_database', [
+$db = $client->getDatabase('test_database', [
     'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
     'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
     'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
@@ -52,7 +52,7 @@
 
 // Sets read and write settings for the "test_collection" collection
 // start-collection-settings
-$collection = $client->selectCollection('test_database', 'test_collection', [
+$collection = $client->getCollection('test_database', 'test_collection', [
     'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED),
     'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
     'writeConcern' => new WriteConcern(0),
@@ -73,7 +73,7 @@
     ],
 );
 
-$db = $client->selectDatabase(
+$db = $client->getDatabase(
     'test_database',
     ['readPreference' => $readPreference],
 );

source/includes/usage-examples/sample-app.php

@@ -5,7 +5,7 @@
 $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
 $client = new MongoDB\Client($uri);
 
-$collection = $client->selectCollection('<database>', '<collection>');
+$collection = $client->getCollection('<database>', '<collection>');
 
 // Start example code here
 

source/includes/usage-examples/write-code-examples.php

@@ -109,7 +109,7 @@
 
 // Stores a file in a GridFS bucket and writes data to the file
 // start-gridfs-upload
-$bucket = $client->selectDatabase('<database name>')->selectGridFSBucket();
+$bucket = $client->getDatabase('<database name>')->selectGridFSBucket();
 $stream = $bucket->openUploadStream('<file name>');
 fwrite($stream, '<data>');
 fclose($stream);

source/includes/write/run-command.php

@@ -8,7 +8,7 @@
 $client = new MongoDB\Client($uri);
 
 // start-hello
-$database = $client->selectDatabase('myDB');
+$database = $client->getDatabase('myDB');
 $cursor = $database->command(['hello' => 1]);
 // end-hello
 

source/read-write-pref.txt

@@ -64,9 +64,9 @@ following methods:
   settings
 - :ref:`MongoDB\Driver\Session::startTransaction() <php-read-write-transaction>`:
   Configures transaction-level settings
-- :ref:`MongoDB\Client::selectDatabase() <php-read-write-database>`: Configures
+- :ref:`MongoDB\Client::getDatabase() <php-read-write-database>`: Configures
   database-level settings
-- :ref:`MongoDB\Client::selectCollection() <php-read-write-collection>`: Configures
+- :ref:`MongoDB\Client::getCollection() <php-read-write-collection>`: Configures
   collection-level settings
 
 .. _php-read-write-client:
@@ -161,7 +161,7 @@ Database Configuration
 
 This example shows how to set the read preference, read concern, and
 write concern of a database called ``test_database`` by passing an options
-array to the ``selectDatabase()`` method. The code configures the following settings:
+array to the ``getDatabase()`` method. The code configures the following settings:
 
 - ``PRIMARY_PREFERRED`` read preference: Read operations retrieve data from 
   the primary replica set member, or secondary members if the primary is unavailable
@@ -184,7 +184,7 @@ Collection Configuration
 
 This example shows how to set the read preference, read concern, and
 write concern of a collection called ``test_collection`` by passing an options
-array to the ``selectCollection()`` method. The code configures the following settings:
+array to the ``getCollection()`` method. The code configures the following settings:
 
 - ``SECONDARY_PREFERRED`` read preference: Read operations retrieve data from 
   secondary replica set members, or the primary members if no secondaries are available
@@ -281,8 +281,8 @@ guide, see the following library API documentation:
 
 - :phpmethod:`MongoDB\Client::__construct()`
 - :phpmethod:`MongoDB\Client::startSession()`
-- :phpmethod:`MongoDB\Client::selectDatabase()`
-- :phpmethod:`MongoDB\Client::selectCollection()`
+- :phpmethod:`MongoDB\Client::getDatabase()`
+- :phpmethod:`MongoDB\Client::getCollection()`
 
 To learn more about the ``startTransaction()`` method, see :php:`MongoDB\Driver\Session::startTransaction()
 <mongodb-driver-session.starttransaction>` in the extension API documentation.

source/reference/class/MongoDBClient.txt

@@ -2,7 +2,6 @@
 MongoDB\\Client Class
 =====================
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -32,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>
@@ -50,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

@@ -21,7 +21,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

@@ -21,7 +21,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
@@ -50,6 +50,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>
@@ -73,6 +74,7 @@ Methods
 - :phpmethod:`MongoDB\Database::createEncryptedCollection()`
 - :phpmethod:`MongoDB\Database::drop()`
 - :phpmethod:`MongoDB\Database::dropCollection()`
+- :phpmethod:`MongoDB\Database::getCollection()`
 - :phpmethod:`MongoDB\Database::getDatabaseName()`
 - :phpmethod:`MongoDB\Database::getManager()`
 - :phpmethod:`MongoDB\Database::getReadConcern()`