Skip to content

M
mongo-php-library
Commit ba1c74f9 authored by Jeremy Mikola's avatar Jeremy Mikola
Browse files
Options

Add Client API documentation

parent 459ed9aa
Hide whitespace changes
Inline Side-by-side
Showing with 275 additions and 52 deletions
docs/classes/client.md
View file @ ba1c74f9
# MongoDB\Client # MongoDB\Client
`MongoDB\Client` serves as an entry point for the library and driver. It is The MongoDB\Client class serves as an entry point for the library. It is the
constructed with the same arguments as the driver's `MongoDB\Driver\Manager` preferred class for connecting to a MongoDB server or cluster of servers and
class, which it composes. Additional reference may be found in the serves as a gateway for accessing individual databases and collections. It is
[`MongoDB\Driver\Manager::__construct`](http://php.net/manual/en/mongodb-driver-manager.construct.php]) analogous to the driver's [MongoDB\Driver\Manager][manager] class, which it
and composes.
[Connection String](https://docs.mongodb.org/manual/reference/connection-string/)
documentation.
[manager]: http://php.net/mongodb-driver-manager
---
## __construct()
```php
function __construct($uri = 'mongodb://localhost:27017', array $uriOptions = [], array $driverOptions = [])
``` ```
/* By default, the driver connects to mongodb://localhost:27017 */
$client = new MongoDB\Client;
/* Any URI options will be merged into the URI string */ Constructs a new Client instance.
Additional URI options may be provided as the second argument and will take
precedence over any like options present in the URI string (e.g. authentication
credentials, query string parameters).
Driver options may be provided as the third argument. In addition to any options
supported by the extension, this library allows you to specify a default
type map to apply to the cursors it creates. A more thorough description of type
maps may be found in the driver's [Persistence documentation][typemap].
[typemap]: http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps
### Supported URI Options
See [MongoDB\Driver\Manager::__construct()][manager-construct] and the
[MongoDB manual][connection-string].
[manager-construct]: http://php.net/manual/en/mongodb-driver-manager.construct.php
[connection-string]: https://docs.mongodb.org/manual/reference/connection-string/
### Supported Driver Options
typeMap (array)
: Default type map for cursors and BSON documents.
### Example
By default, the driver connects to a standalone server on localhost via port
27017. The following example demonstrates how to connect to a replica set.
Additionally, it demonstrates a replica set with a custom read preference:
```
<?php
$client = new MongoDB\Client( $client = new MongoDB\Client(
'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet', 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet',
['readPreference' => 'secondaryPreferred'] [
'readPreference' => 'secondaryPreferred'
]
); );
``` ```
Driver options may be provided as the third argument. In addition to options By default, the library will unserialize BSON documents and arrays as
supported by the extension, the PHP library allows you to specify a default MongoDB\Model\BSONDocument and MongoDB\Model\BSONArray objects, respectively.
type map to apply to the cursors it creates. A more thorough description of type The following example demonstrates how to have the library unserialize
maps may be found in the driver's everything as a PHP array, as was done in the legacy
[Persistence documentation](http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps). [mongo extension][ext-mongo]:
[ext-mongo]: http://php.net/mongo
``` ```
/* This example instructs the library to unserialize root and embedded BSON <?php
* documents as PHP arrays, like the legacy driver (i.e. ext-mongo). */
$client = new MongoDB\Client(null, [], [ $client = new MongoDB\Client(
'typeMap' => ['root' => 'array', 'document' => 'array'], null,
[],
['typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array']]
); );
``` ```
By default, the library will unserialize BSON documents and arrays as ### See Also
`MongoDB\Model\BSONDocument` and `MongoDB\Model\BSONArray` objects,
respectively. Each of these model classes extends PHP's * [MongoDB\Driver\Manager::__construct()][manager-construct]
[`ArrayObject`](http://php.net/arrayobject) class and implements the driver's * [MongoDB Manual: Connection String][connection-string]
[`MongoDB\BSON\Serializable`](http://php.net/mongodb-bson-serializable) and
[`MongoDB\BSON\Unserializable`](http://php.net/mongodb-bson-unserializable)
interfaces.
## Selecting Databases and Collections ---
The Client class provides methods for creating Database or Collection instances ## __get()
(using its internal Manager instance). When selecting a Database or Collection,
the child will inherit options (e.g. read preference, type map) from the Client.
New options may also be provided to the `selectDatabase()` and
`selectCollection()` methods.
```php
function __get($databaseName): MongoDB\Database
``` ```
Select a database.
The Database will inherit options (e.g. read preference, type map) from the
Client object. Use [selectDatabase()](#selectdatabase) to override any options.
**Note:** databases whose names contain special characters (e.g. "-") may be
selected with complex syntax (e.g. `$client->{"that-database"}`) or
[selectDatabase()](#selectdatabase).
### Example
The following example selects the "demo" and "another-app" databases:
```
<?php
$client = new MongoDB\Client; $client = new MongoDB\Client;
/* Select the "demo" database */ $demo = $client->demo;
$db = $client->selectDatabase('demo'); $anotherApp = $client->{'another-app'};
```
/* Select the "demo.users" collection */ ### See Also
$collection = $client->selectCollection('demo', 'users');
* [MongoDB\Client::selectDatabase()](#selectdatabase)
* [PHP Manual: Property Overloading](http://php.net/oop5.overloading#object.get)
---
/* selectDatabase() and selectCollection() also take an options array, which can ## dropDatabase
* override any options inherited from the Client. */
$db = $client->selectDatabase('demo', [
'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
]);
/* The property accessor may also be used to select a database without ```php
* specifying additional options. PHP's complex syntax may be used for selecting function dropDatabase($databaseName, array $options = []): array|object
* databases whose names contain special characters (e.g. "-"). */
$db = $client->demo;
$db = $client->{'another-app'};
``` ```
## Database Management Drop a database. Returns the command result document.
The Client class has several methods for managing databases. ### Supported Options
### Dropping Databases typeMap (array)
: Type map for BSON deserialization. This will only be used for the returned
command result document.
### Example
The following example drops the "demo" database:
``` ```
<?php
$client = new MongoDB\Client; $client = new MongoDB\Client;
$result = $client->dropDatabase('demo'); $result = $client->dropDatabase('demo');
var_dump($result); var_dump($result);
``` ```
...@@ -98,12 +161,36 @@ object(MongoDB\Model\BSONDocument)#8 (1) { ...@@ -98,12 +161,36 @@ object(MongoDB\Model\BSONDocument)#8 (1) {
} }
``` ```
### Enumerating Databases ### See Also
* [MongoDB\Database::drop()](database.md#drop)
* [MongoDB Manual: dropDatabase command](http://docs.mongodb.org/manual/reference/command/dropDatabase/)
---
## listDatabases()
```php
function listDatabases(array $options = []): MongoDB\Model\DatabaseInfoIterator
``` ```
Returns information for all database on the server. Elements in the returned
iterator will be MongoDB\Model\DatabaseInfo objects.
### Supported Options
maxTimeMS (integer)
: The maximum amount of time to allow the query to run.
### Example
The following example lists all databases on the server:
```
<?php
$client = new MongoDB\Client; $client = new MongoDB\Client;
/* listDatabases() returns an iterator of MongoDB\Model\DatabaseInfo objects */
foreach ($client->listDatabases() as $databaseInfo) { foreach ($client->listDatabases() as $databaseInfo) {
var_dump($databaseInfo); var_dump($databaseInfo);
} }
...@@ -129,3 +216,139 @@ object(MongoDB\Model\DatabaseInfo)#7 (3) { ...@@ -129,3 +216,139 @@ object(MongoDB\Model\DatabaseInfo)#7 (3) {
bool(false) bool(false)
} }
``` ```
### See Also
* [MongoDB Manual: listDatabases command](http://docs.mongodb.org/manual/reference/command/listDatabases/)
---
## selectCollection()
```php
function selectCollection($databaseName, $collectionName, array $options = []): MongoDB\Collection
```
Select a collection on the server.
The Collection will inherit options (e.g. read preference, type map) from the
Client object unless otherwise specified.
### Supported Options
readConcern (MongoDB\Driver\ReadConcern)
: The default read concern to use for collection operations. Defaults to the
Client's read concern.
readPreference (MongoDB\Driver\ReadPreference)
: The default read preference to use for collection operations. Defaults to
the Client's read preference.
typeMap (array)
: Default type map for cursors and BSON documents. Defaults to the Client's
type map.
writeConcern (MongoDB\Driver\WriteConcern)
: The default write concern to use for collection operations. Defaults to the
Client's write concern.
### Example
The following example selects the "demo.users" collection:
```
<?php
$client = new MongoDB\Client;
$collection = $client->selectCollection('demo', 'users');
```
The following examples selects the "demo.users" collection with a custom read
preference:
```
<?php
$client = new MongoDB\Client;
$collection = $client->selectCollection(
'demo',
'users',
[
'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
]
);
```
### See Also
* [MongoDB\Collection::__construct()](collection.md#__construct)
* [MongoDB\Client::__get()](#__get)
---
## selectDatabase()
```php
function selectDatabase($databaseName array $options = []): MongoDB\Collection
```
Select a database on the server.
The Database will inherit options (e.g. read preference, type map) from the
Client object unless otherwise specified.
### Supported Options
readConcern (MongoDB\Driver\ReadConcern)
: The default read concern to use for database operations. Defaults to the
Client's read concern.
readPreference (MongoDB\Driver\ReadPreference)
: The default read preference to use for database operations. Defaults to the
Client's read preference.
typeMap (array)
: Default type map for cursors and BSON documents. Defaults to the Client's
type map.
writeConcern (MongoDB\Driver\WriteConcern)
: The default write concern to use for database operations. Defaults to the
Client's write concern.
### Example
The following example selects the "demo" database:
```
<?php
$client = new MongoDB\Client;
$db = $client->selectDatabase('demo');
```
The following examples selects the "demo" database with a custom read
preference:
```
<?php
$client = new MongoDB\Client;
$db = $client->selectDatabase(
'demo',
[
'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
]
);
```
### See Also
* [MongoDB\Database::__construct()](database.md#__construct)
* [MongoDB\Client::__get()](#__get)
---
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment