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
Show whitespace changes
Inline Side-by-side
Showing with 275 additions and 52 deletions
docs/classes/client.md
View file @ ba1c74f9
# MongoDB\Client
`MongoDB\Client` serves as an entry point for the library and driver. It is
constructed with the same arguments as the driver's `MongoDB\Driver\Manager`
class, which it composes. Additional reference may be found in the
[`MongoDB\Driver\Manager::__construct`](http://php.net/manual/en/mongodb-driver-manager.construct.php])
and
[Connection String](https://docs.mongodb.org/manual/reference/connection-string/)
documentation.
The MongoDB\Client class serves as an entry point for the library. It is the
preferred class for connecting to a MongoDB server or cluster of servers and
serves as a gateway for accessing individual databases and collections. It is
analogous to the driver's [MongoDB\Driver\Manager][manager] class, which it
composes.
[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(
'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
supported by the extension, the PHP 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](http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps).
By default, the library will unserialize BSON documents and arrays as
MongoDB\Model\BSONDocument and MongoDB\Model\BSONArray objects, respectively.
The following example demonstrates how to have the library unserialize
everything as a PHP array, as was done in the legacy
[mongo extension][ext-mongo]:
[ext-mongo]: http://php.net/mongo
```
/* This example instructs the library to unserialize root and embedded BSON
* documents as PHP arrays, like the legacy driver (i.e. ext-mongo). */
$client = new MongoDB\Client(null, [], [
'typeMap' => ['root' => 'array', 'document' => 'array'],
<?php
$client = new MongoDB\Client(
null,
[],
['typeMap' => ['root' => 'array', 'document' => 'array', 'array' => 'array']]
);
```
By default, the library will unserialize BSON documents and arrays as
`MongoDB\Model\BSONDocument` and `MongoDB\Model\BSONArray` objects,
respectively. Each of these model classes extends PHP's
[`ArrayObject`](http://php.net/arrayobject) class and implements the driver's
[`MongoDB\BSON\Serializable`](http://php.net/mongodb-bson-serializable) and
[`MongoDB\BSON\Unserializable`](http://php.net/mongodb-bson-unserializable)
interfaces.
### See Also
* [MongoDB\Driver\Manager::__construct()][manager-construct]
* [MongoDB Manual: Connection String][connection-string]
---
## __get()
```php
function __get($databaseName): MongoDB\Database
```
Select a database.
## Selecting Databases and Collections
The Database will inherit options (e.g. read preference, type map) from the
Client object. Use [selectDatabase()](#selectdatabase) to override any options.
The Client class provides methods for creating Database or Collection instances
(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.
**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;
/* Select the "demo" database */
$db = $client->selectDatabase('demo');
$demo = $client->demo;
$anotherApp = $client->{'another-app'};
```
/* Select the "demo.users" collection */
$collection = $client->selectCollection('demo', 'users');
### See Also
/* selectDatabase() and selectCollection() also take an options array, which can
* override any options inherited from the Client. */
$db = $client->selectDatabase('demo', [
'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
]);
* [MongoDB\Client::selectDatabase()](#selectdatabase)
* [PHP Manual: Property Overloading](http://php.net/oop5.overloading#object.get)
---
/* The property accessor may also be used to select a database without
* specifying additional options. PHP's complex syntax may be used for selecting
* databases whose names contain special characters (e.g. "-"). */
$db = $client->demo;
$db = $client->{'another-app'};
## dropDatabase
```php
function dropDatabase($databaseName, array $options = []): array|object
```
## Database Management
Drop a database. Returns the command result document.
### Supported Options
The Client class has several methods for managing databases.
typeMap (array)
: Type map for BSON deserialization. This will only be used for the returned
command result document.
### Dropping Databases
### Example
The following example drops the "demo" database:
```
<?php
$client = new MongoDB\Client;
$result = $client->dropDatabase('demo');
var_dump($result);
```
......@@ -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;
/* listDatabases() returns an iterator of MongoDB\Model\DatabaseInfo objects */
foreach ($client->listDatabases() as $databaseInfo) {
var_dump($databaseInfo);
}
......@@ -129,3 +216,139 @@ object(MongoDB\Model\DatabaseInfo)#7 (3) {
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