Skip to content

Commit e888db7

Browse files
jmikolajmikola
committed
Update documentation for 1.0.0
1 parent cbf0330 commit e888db7

File tree

5 files changed

+381
-343
lines changed

5 files changed

+381
-343
lines changed

‎docs/bulk.md

Lines changed: 78 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,98 @@
1-
# Bulk CRUD
1+
# Bulk CRUD Operations
22

33
```php
44
<?php
55

6-
$hannes = array(
7-
"name" => "Hannes",
8-
"nick" => "bjori",
9-
"citizen" => "Iceland",
10-
);
11-
$hayley = array(
12-
"name" => "Hayley",
13-
"nick" => "Alien Ninja",
14-
"citizen" => "USA",
15-
);
16-
$jonpall = array(
17-
"name" => "Jon Pall",
18-
"nick" => "unknown",
19-
"citizen" => "Iceland",
20-
);
21-
22-
/* Ordered bulk is executed in the same order as we add the operations to it.
23-
* If operation fails the execution stops and no further operations executed.
24-
* For unordered bulk, the operations can be executed in any order by the database
25-
* in an attempt to optimize its workload. An operation failure will not stop
26-
* the exection of the rest of the operations.
27-
* Default: true
28-
*/
29-
$ordered = true;
30-
31-
$bulk = new MongoDB\Driver\BulkWrite($ordered);
6+
$hannes = [
7+
"name" => "Hannes",
8+
"nick" => "bjori",
9+
"citizen" => "Iceland",
10+
];
11+
$hayley = [
12+
"name" => "Hayley",
13+
"nick" => "Alien Ninja",
14+
"citizen" => "USA",
15+
];
16+
$jonpall = [
17+
"name" => "Jon Pall",
18+
"nick" => "unknown",
19+
"citizen" => "Iceland",
20+
];
21+
22+
/* Ordered bulk operations (default) are executed in the same order that we add
23+
* the write operations. If an operation fails, execution stops and no further
24+
* operations are attempted. For unordered bulk operations, the operations may
25+
* be executed in any order by the database in an attempt to optimize its
26+
* workload. An operation failure within an unordered batch will not stop
27+
* execution of additional write operations in that batch. */
28+
$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
3229

3330
?>
3431
```
3532

36-
## CREATE
33+
## Create
3734

3835
```php
3936
<?php
4037

41-
/* Argument#1 The document (array/object) to insert.
42-
* Returns the generated BSON\ObjectID if no _id was provided
43-
*/
38+
/* Specify the document to insert (array or object) as the first argument. If a
39+
* document does not already have an "_id" field, a generated
40+
* MongoDB\BSON\ObjectId will be returned. */
4441
$hannes_id = $bulk->insert($hannes);
4542
$hayley_id = $bulk->insert($hayley);
4643
$jonpall_id = $bulk->insert($jonpall);
4744

4845
?>
4946
```
5047

51-
## UPDATE
48+
## Update
5249

5350
```php
5451
<?php
5552

56-
/* Arguments
57-
* #1: array, search criteria
58-
* #2: array, the object or operations to apply to the matching document
59-
* #3: array, wire protocol options:
60-
* limit: integer, 0 or 1,
61-
* 0: Apply to all matching documents
62-
* 1: Only apply to the first matching document
63-
* upsert: boolean
64-
* true: Insert new document matching the criteria
65-
* false: Do not insert new document if no matches are found
66-
*/
53+
/* Arguments:
54+
*
55+
* #1 (array|object): search criteria to select the document(s) for updating
56+
* #2 (array|object): replacement document or atomic operations to apply
57+
* #3 (array): update options
58+
* * limit (integer): Updates all matching documents when 0 (false).
59+
* Otherwise, only the first matching document is updated.
60+
* * upsert (boolean): If there is no matching document, create a new
61+
* document from $filter and $update. */
6762
$bulk->update(
68-
array("_id" => $hayley_id),
69-
array('$set' => array("citizen" => "Iceland")),
70-
array("limit" => 1, "upsert" => false)
63+
["_id" => $hayley_id],
64+
['$set' => ["citizen" => "Iceland"]],
65+
["limit" => 1, "upsert" => false]
7166
);
7267
$bulk->update(
73-
array("citizen" => "Iceland"),
74-
array('$set' => array("viking" => true)),
75-
array("limit" => 0, "upsert" => false)
68+
["citizen" => "Iceland"],
69+
['$set' => ["viking" => true]],
70+
["limit" => 0, "upsert" => false]
7671
);
7772
$bulk->update(
78-
array("name" => "Chuck Norris"),
79-
array('$set' => array("viking" => false)),
80-
array("limit" => 1, "upsert" => true)
81-
);
73+
["name" => "Chuck Norris"],
74+
['$set' => ["viking" => false]],
75+
["limit" => 1, "upsert" => true]
76+
];
8277

8378
?>
8479
```
8580

86-
## DELETE
81+
## Delete
8782

8883
```php
8984
<?php
9085

91-
/* Arguments
92-
* #1: array, search criteria
93-
* #2: array, wire protocol options:
94-
* limit: integer, 0 or 1,
95-
* 0: Delete all matching documents
96-
* 1: Only delete the first matching document
97-
*/
98-
$bulk->delete(array("_id" => $jonpall_id), array("limit" => 1));
86+
/* Arguments:
87+
*
88+
* #1 (array|object): search criteria to select the document(s) for deleting
89+
* #3 (array): delete options
90+
* * limit (integer): Deletes all matching documents when 0 (false).
91+
* Otherwise, only the first matching document is deleted. */
92+
$bulk->delete(
93+
["_id" => $jonpall_id],
94+
["limit" => 1]
95+
);
9996

10097
?>
10198
```
@@ -104,28 +101,36 @@ $bulk->delete(array("_id" => $jonpall_id), array("limit" => 1));
104101

105102
```php
106103
<?php
104+
105+
// Construct a write concern
106+
$wc = new MongoDB\Driver\WriteConcern(
107+
// Guarantee that writes are acknowledged by a majority of our nodes
108+
MongoDB\Driver\WriteConcern::MAJORITY,
109+
// But only wait 1000ms because we have an application to run!
110+
1000
111+
);
112+
107113
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
108-
$wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
109114
$result = $manager->executeBulkWrite("db.collection", $bulk, $wc);
110115

111116
printf("insertedCount: %d\n", $result->getInsertedCount());
112-
printf("matchedCount: %d\n", $result->getMatchedCount());
117+
printf("matchedCount: %d\n", $result->getMatchedCount());
113118
printf("modifiedCount: %d\n", $result->getModifiedCount());
114119
printf("upsertedCount: %d\n", $result->getUpsertedCount());
115-
printf("deletedCount: %d\n", $result->getDeletedCount());
120+
printf("deletedCount: %d\n", $result->getDeletedCount());
116121

117122
foreach ($result->getUpsertedIds() as $index => $id) {
118-
printf("upsertedId: '%s', index: %d\n", $id, $index);
123+
printf("upsertedId: '%s', index: %d\n", $id, $index);
119124
}
120125

121-
$query = new MongoDB\Driver\Query(array("viking" => false));
126+
$query = new MongoDB\Driver\Query(["viking" => false]);
122127
$cursor = $manager->executeQuery("db.collection", $query);
123-
/* Note that var_dump()ing the $cursor will print out all sorts of debug information
124-
* about the cursor, such as ReadPreferences used, the query executed, namespace,
125-
* query flags, and the current bulk information */
126-
var_dump(iterator_to_array($cursor));
128+
129+
/* Note that var_dump()-ing the $cursor directly will print out additional debug
130+
* information about the cursor, such as the read preferenced used, the query
131+
* executed, namespace, query flags, and information about the current batch of
132+
* results from the server. Instead, we'll simply var_dump() the results. */
133+
var_dump($cursor->toArray());
127134

128135
?>
129136
```
130-
131-

‎docs/commands.md

Lines changed: 70 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,118 @@
1-
# Running Commands
1+
# Executing Commands
22

3-
# Listing databases & collections
3+
# Listing databases and collections
44

55
```php
66
<?php
77

8-
/* Construct the MongoDB Manager */
8+
// Construct the MongoDB Manager
99
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
1010

11+
// Construct and execute the listDatabases command
12+
$listdatabases = new MongoDB\Driver\Command(["listDatabases" => 1]);
13+
$result = $manager->executeCommand("admin", $listdatabases);
1114

12-
$listdatabases = new MongoDB\Driver\Command(array("listDatabases" => 1));
13-
$retval = $manager->executeCommand("admin", $listdatabases);
14-
$databases = $retval->toArray();
15+
/* The command returns a single result document, which contains the information
16+
* for all databases in a "databases" array field. */
17+
$databases = current($result->toArray());
1518

16-
foreach($databases["databases"] as $database) {
19+
foreach ($databases["databases"] as $database) {
1720
echo $database->name, "\n";
1821

19-
$listcollections = new MongoDB\Driver\Command(array("listCollections" => 1));
20-
$retval = $manager->executeCommand($database->name, $listcollections);
21-
$collections = $retval->toArray();
22-
foreach($collections as $collection) {
23-
echo "\t- ", $collection->name, "\n";
22+
// Construct and execute the listCollections command for each database
23+
$listcollections = new MongoDB\Driver\Command(["listCollections" => 1]);
24+
$result = $manager->executeCommand($database->name, $listcollections);
25+
26+
/* The command returns a cursor, which we can iterate on to access
27+
* information for each collection. */
28+
$collections = $result->toArray();
29+
30+
foreach ($collections as $collection) {
31+
echo "\t * ", $collection->name, "\n";
2432
}
2533
}
2634

2735
?>
2836
```
2937

30-
# Create a User
38+
# Create a user
3139

3240
```php
3341
<?php
3442

35-
36-
/* Construct the MongoDB Manager */
43+
// Construct the MongoDB Manager
3744
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
3845

39-
40-
$command = array(
46+
// Construct the createUser command
47+
$createuser = new MongoDB\Driver\Command([
4148
"createUser" => "USERNAME2",
4249
"pwd" => "PASSWORD",
43-
"roles" => array(
44-
array("role" => "clusterAdmin", "db" => "admin"),
45-
array("role" => "readWriteAnyDatabase", "db" => "admin"),
46-
array("role" => "userAdminAnyDatabase", "db" => "admin"),
50+
"roles" => [
51+
["role" => "clusterAdmin", "db" => "admin"],
52+
["role" => "readWriteAnyDatabase", "db" => "admin"],
53+
["role" => "userAdminAnyDatabase", "db" => "admin"],
4754
"readWrite",
48-
),
49-
"writeConcern" => array("w" => "majority"),
50-
);
51-
$createuser = new MongoDB\Driver\Command($command);
55+
],
56+
"writeConcern" => ["w" => "majority"],
57+
]);
5258

5359
try {
5460
$result = $manager->executeCommand("admin", $createuser);
55-
$response = $result->toArray();
61+
$response = current($result->toArray());
62+
5663
if ($response["ok"]) {
57-
echo "User created\n";
64+
echo "User created successfully\n";
5865
}
59-
} catch(Exception $e) {
66+
} catch (MongoDB\Driver\Exception\Exception $e) {
6067
echo $e->getMessage(), "\n";
6168
}
6269

63-
6470
?>
6571
```
6672

67-
## Commands and ReadPreferences
73+
## Commands and read preferences
6874

6975
```php
7076
<?php
7177

72-
/* Some commands, like count, dbStats, aggregate, ... can be executed on secondaries.
73-
* Just like with normal queries, an instance of MongoDB\Driver\ReadPreference needs to
74-
* be constructed to prefer certain servers over others */
75-
$prefer = MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED;
76-
$tags = array(
77-
/* Prefer the West Coast datacenter in Iceland */
78-
array("country" => "iceland", "datacenter" => "west"),
79-
80-
/* Fallback to any datacenter in Iceland */
81-
array("country" => "iceland"),
82-
83-
/* If Iceland is offline, read from whatever is online! */
84-
array(),
78+
/* Some commands (e.g. count, aggregate) may be executed on secondaries. As with
79+
* normal queries, we can supply a MongoDB\Driver\ReadPreference object when
80+
* executing a command in order to prefer certain servers over others. */
81+
82+
// Construct a read preference
83+
$rp = new MongoDB\Driver\ReadPreference(
84+
/* We prefer to read from a secondary, but are OK with reading from the
85+
* primary if necessary (e.g. secondaries are offline) */
86+
MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED,
87+
// Specify some tag sets for our preferred nodes
88+
[
89+
// Prefer reading from our west coast datacenter in Iceland
90+
["country" => "iceland", "datacenter" => "west"],
91+
// Fall back to any datacenter in Iceland
92+
["country" => "iceland"],
93+
// If Iceland is offline, read from whatever is available
94+
[],
95+
]
8596
);
8697

87-
/* Construct the ReadPreference object from our options */
88-
$rp = new MongoDB\Driver\ReadPreference($prefer, $tags);
89-
90-
/* Construct the MongoDB Manager */
98+
// Construct the MongoDB Manager
9199
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
92100

93-
$query = array("citizen" => "Iceland");
94-
$count = new MongoDB\Driver\Command(array("count" => "collection", "query" => $query));
95-
$retval = $manager->executeCommand("db", $count, $rp);
96-
$response = $retval->toArray();
97-
if ($response["ok"]) {
98-
printf("db.collection has %d documents matching: %s\n",
99-
$response["n"],
100-
BSON\toJSON(BSON\fromArray($query))
101-
);
101+
$query = ["citizen" => "Iceland"];
102+
$count = new MongoDB\Driver\Command(["count" => "collection", "query" => $query]);
103+
104+
try {
105+
$result = $manager->executeCommand("db", $count, $rp);
106+
$response = current($result->toArray());
107+
108+
if ($response["ok"]) {
109+
printf("db.collection has %d document(s) matching: %s\n",
110+
$response["n"],
111+
MongoDB\BSON\toJSON(MongoDB\BSON\fromArray($query))
112+
);
113+
}
114+
} catch (MongoDB\Driver\Exception\Exception $e) {
115+
echo $e->getMessage(), "\n";
102116
}
103117

104118
?>

0 commit comments

Comments
 (0)