Skip to content

Commit e19bdf2

Browse files
jmikolajmikola
committed
Merge pull request #95 
2 parents 6ee316a + e3b335f commit e19bdf2

File tree

9 files changed

+649
-124
lines changed

9 files changed

+649
-124
lines changed

‎apigen.neon

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ charset:
88

99
main: MongoDB PHP library
1010
title: MongoDB PHP library
11-
baseUrl: http://mongodb.github.io/mongo-php-library
11+
baseUrl: http://mongodb.github.io/mongo-php-library/api
1212
googleCseId: null
1313
googleAnalytics: null
1414
templateTheme: bootstrap

‎docs/classes/client.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# MongoDB\Client
2+
3+
`MongoDB\Client` serves as an entry point for the library and driver. It is
4+
constructed with the same arguments as the driver's `MongoDB\Driver\Manager`
5+
class, which it composes. Additional reference may be found in the
6+
[`MongoDB\Driver\Manager::__construct`](http://php.net/manual/en/mongodb-driver-manager.construct.php])
7+
and
8+
[Connection String](https://docs.mongodb.org/manual/reference/connection-string/)
9+
documentation.
10+
11+
```
12+
/* By default, the driver connects to mongodb://localhost:27017 */
13+
$client = new MongoDB\Client;
14+
15+
/* Any URI options will be merged into the URI string */
16+
$client = new MongoDB\Client(
17+
'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet',
18+
['readPreference' => 'secondaryPreferred']
19+
);
20+
```
21+
22+
Driver options may be provided as the third argument. In addition to options
23+
supported by the extension, the PHP library allows you to specify a default
24+
type map to apply to the cursors it creates. A more thorough description of type
25+
maps may be found in the driver's
26+
[Persistence documentation](http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps).
27+
28+
```
29+
/* This example instructs the library to unserialize root and embedded BSON
30+
* documents as PHP arrays, like the legacy driver (i.e. ext-mongo). */
31+
$client = new MongoDB\Client(null, [], [
32+
'typeMap' => ['root' => 'array', 'document' => 'array'],
33+
);
34+
```
35+
36+
By default, the library will unserialize BSON documents and arrays as
37+
`MongoDB\Model\BSONDocument` and `MongoDB\Model\BSONArray` objects,
38+
respectively. Each of these model classes extends PHP's
39+
[`ArrayObject`](http://php.net/arrayobject) class and implements the driver's
40+
[`MongoDB\BSON\Serializable`](http://php.net/mongodb-bson-serializable) and
41+
[`MongoDB\BSON\Unserializable`](http://php.net/mongodb-bson-unserializable)
42+
interfaces.
43+
44+
## Selecting Databases and Collections
45+
46+
The Client class provides methods for creating Database or Collection instances
47+
(using its internal Manager instance). When selecting a Database or Collection,
48+
the child will inherit options (e.g. read preference, type map) from the Client.
49+
New options may also be provided to the `selectDatabase()` and
50+
`selectCollection()` methods.
51+
52+
```
53+
$client = new MongoDB\Client;
54+
55+
/* Select the "demo" database */
56+
$db = $client->selectDatabase('demo');
57+
58+
/* Select the "demo.users" collection */
59+
$collection = $client->selectCollection('demo', 'users');
60+
61+
/* selectDatabase() and selectCollection() also take an options array, which can
62+
* override any options inherited from the Client. */
63+
$db = $client->selectDatabase('demo', [
64+
'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
65+
]);
66+
67+
/* The property accessor may also be used to select a database without
68+
* specifying additional options. PHP's complex syntax may be used for selecting
69+
* databases whose names contain special characters (e.g. "-"). */
70+
$db = $client->demo;
71+
$db = $client->{'another-app'};
72+
```
73+
74+
## Database Management
75+
76+
The Client class has several methods for managing databases.
77+
78+
### Dropping Databases
79+
80+
```
81+
$client = new MongoDB\Client;
82+
83+
$result = $client->dropDatabase('demo');
84+
var_dump($result);
85+
```
86+
87+
The above example would output something similar to:
88+
89+
```
90+
object(MongoDB\Model\BSONDocument)#8 (1) {
91+
["storage":"ArrayObject":private]=>
92+
array(2) {
93+
["dropped"]=>
94+
string(4) "demo"
95+
["ok"]=>
96+
float(1)
97+
}
98+
}
99+
```
100+
101+
### Enumerating Databases
102+
103+
```
104+
$client = new MongoDB\Client;
105+
106+
/* listDatabases() returns an iterator of MongoDB\Model\DatabaseInfo objects */
107+
foreach ($client->listDatabases() as $databaseInfo) {
108+
var_dump($databaseInfo);
109+
}
110+
```
111+
112+
The above example would output something similar to:
113+
114+
```
115+
object(MongoDB\Model\DatabaseInfo)#4 (3) {
116+
["name"]=>
117+
string(5) "local"
118+
["sizeOnDisk"]=>
119+
float(65536)
120+
["empty"]=>
121+
bool(false)
122+
}
123+
object(MongoDB\Model\DatabaseInfo)#7 (3) {
124+
["name"]=>
125+
string(4) "test"
126+
["sizeOnDisk"]=>
127+
float(32768)
128+
["empty"]=>
129+
bool(false)
130+
}
131+
```

‎docs/classes/collection.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# MongoDB\Collection
2+
3+
`MongoDB\Collection` is perhaps the most useful class in this library. It
4+
provides methods for common operations on a collection, such as inserting
5+
documents, querying, updating, counting, etc.
6+
7+
A Collection may be constructed directly (using the extension's Manager class)
8+
or selected from the library's Client class. It supports the following options:
9+
10+
* [readConcern](http://php.net/mongodb-driver-readconcern)
11+
* [readPreference](http://php.net/mongodb-driver-readpreference)
12+
* [typeMap](http://php.net/manual/en/mongodb.persistence.php#mongodb.persistence.typemaps)
13+
* [writeConcern](http://php.net/mongodb-driver-writeconcern)
14+
15+
If any options are omitted, they will be inherited from the Manager constructor
16+
argument or object from which the Collection was selected.
17+
18+
Operations within the Collection class (e.g. `find()`, `insertOne()`) will
19+
generally inherit the Collection's options. One notable exception to this rule
20+
is that `aggregate()` (when not using a cursor) and the `findAndModify` variants
21+
do not yet support a type map option due to a driver limitation. This means that
22+
they will return BSON documents and arrays as `stdClass` objects and PHP arrays,
23+
respectively.
24+
25+
## Collection-level Operations
26+
27+
The Collection class has methods for collection-level operations, such as
28+
dropping the collection, CRUD operations, or managing the collection's indexes.
29+
30+
### Dropping the Collection
31+
32+
```
33+
$collection = (new MongoDB\Client)->demo->zips;
34+
35+
$result = $collection->drop();
36+
var_dump($result);
37+
```
38+
39+
The above example would output something similar to:
40+
41+
```
42+
object(MongoDB\Model\BSONDocument)#11 (1) {
43+
["storage":"ArrayObject":private]=>
44+
array(3) {
45+
["ns"]=>
46+
string(9) "demo.zips"
47+
["nIndexesWas"]=>
48+
int(1)
49+
["ok"]=>
50+
float(1)
51+
}
52+
}
53+
```
54+
55+
## CRUD Operations
56+
57+
CRUD is an acronym for Create, Read, Update, and Delete. The Collection class
58+
implements MongoDB's cross-driver
59+
[CRUD specification](https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst),
60+
which defines a common API for collection-level read and write methods.
61+
62+
Each method on the Collection class corresponds to a particular Operation class
63+
within the library. The Collection's method merely merges in relevant options
64+
(e.g. read preferences, type maps). Documentation for each CRUD method and its
65+
options may be found in either the CRUD specification or those Operation
66+
classes.
67+
68+
### API Differences from the Legacy Driver
69+
70+
The CRUD API has some notable differences from the legacy driver's
71+
[MongoCollection](http://php.net/mongocollection) class:
72+
73+
* `insert()` and `batchInsert()` have been renamed to `insertOne()` and
74+
`insertMany()`, respectively.
75+
* `update()` has been split into `updateOne()`, `updateMany()`, and
76+
`replaceOne()`.
77+
* `remove()` has been split into `deleteOne()` and `deleteMany()`.
78+
* `findAndModify()` has been split into `findOneAndDelete()`,
79+
`findOneAndReplace()`, and `findOneAndUpdate()`.
80+
* `save()`, which was syntactic sugar for an insert or upsert operation, has
81+
been removed in favor of explicitly using `insertOne()` or `replaceOne()`
82+
(with the `upsert` option).
83+
* `aggregate()` and `aggregateCursor()` have been consolidated into a single
84+
`aggregate()` method.
85+
* A general-purpose `bulkWrite()` method replaces the legacy driver's
86+
[`MongoWriteBatch`](http://php.net/mongowritebatch) class.
87+
88+
The general rule in designing our new API was that explicit method names were
89+
preferable to overloaded terms found in the old API. For instance, `save()` and
90+
`findAndModify()` had two or three very different modes of operation, depending
91+
on their arguments. These new methods names also distinguish between
92+
[updating specific fields](https://docs.mongodb.org/manual/tutorial/modify-documents/#update-specific-fields-in-a-document)
93+
and [full-document replacement](https://docs.mongodb.org/manual/tutorial/modify-documents/#replace-the-document).
94+
95+
### Finding One or More Document(s)
96+
97+
The `findOne()` and `find()` methods may be used to query for one or multiple
98+
documents.
99+
100+
```
101+
$collection = (new MongoDB\Client)->demo->zips;
102+
103+
$document = $collection->findOne(['_id' => '94301']);
104+
var_dump($document);
105+
```
106+
107+
The above example would output something similar to:
108+
109+
```
110+
object(MongoDB\Model\BSONDocument)#13 (1) {
111+
["storage":"ArrayObject":private]=>
112+
array(5) {
113+
["_id"]=>
114+
string(5) "94301"
115+
["city"]=>
116+
string(9) "PALO ALTO"
117+
["loc"]=>
118+
object(MongoDB\Model\BSONArray)#12 (1) {
119+
["storage":"ArrayObject":private]=>
120+
array(2) {
121+
[0]=>
122+
float(-122.149685)
123+
[1]=>
124+
float(37.444324)
125+
}
126+
}
127+
["pop"]=>
128+
int(15965)
129+
["state"]=>
130+
string(2) "CA"
131+
}
132+
}
133+
```
134+
135+
The `find()` method returns a
136+
[`MongoDB\Driver\Cursor`](http://php.net/mongodb-driver-cursor) object, which
137+
may be iterated upon to access all matched documents.
138+
139+
## Index Management
140+
141+
The Collection class implements MongoDB's cross-driver
142+
[Index Management](https://github.com/mongodb/specifications/blob/master/source/index-management.rst)
143+
and
144+
[Enumerating Indexes](https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.rst)
145+
specifications, which defines a common API for index-related methods.
146+
147+
### Creating Indexes
148+
149+
```
150+
$collection = (new MongoDB\Client)->demo->zips;
151+
152+
$result = $collection->createIndex(['state' => 1]);
153+
var_dump($result);
154+
```
155+
156+
The above example would output something similar to:
157+
158+
```
159+
string(7) "state_1"
160+
```
161+
162+
### Dropping Indexes
163+
164+
```
165+
$collection = (new MongoDB\Client)->demo->zips;
166+
167+
$result = $collection->dropIndex('state_1');
168+
var_dump($result);
169+
```
170+
171+
The above example would output something similar to:
172+
173+
```
174+
object(MongoDB\Model\BSONDocument)#11 (1) {
175+
["storage":"ArrayObject":private]=>
176+
array(2) {
177+
["nIndexesWas"]=>
178+
int(2)
179+
["ok"]=>
180+
float(1)
181+
}
182+
}
183+
```
184+
185+
### Enumerating Indexes
186+
187+
```
188+
/* listIndexes() returns an iterator of MongoDB\Model\IndexInfo objects */
189+
$collection = (new MongoDB\Client)->demo->zips;
190+
191+
foreach ($collection->listIndexes() as $indexInfo) {
192+
var_dump($indexInfo);
193+
}
194+
```
195+
196+
The above example would output something similar to:
197+
198+
```
199+
object(MongoDB\Model\IndexInfo)#4 (4) {
200+
["v"]=>
201+
int(1)
202+
["key"]=>
203+
array(1) {
204+
["_id"]=>
205+
int(1)
206+
}
207+
["name"]=>
208+
string(4) "_id_"
209+
["ns"]=>
210+
string(9) "demo.zips"
211+
}
212+
```

0 commit comments

Comments
 (0)