Skip to content

Commit 5059c7e

Browse files
jmikolajmikola
committed
Add write method examples to CRUD tutorial
1 parent 518476b commit 5059c7e

File tree

4 files changed

+391
-354
lines changed

4 files changed

+391
-354
lines changed

‎docs/tutorial/crud.md

Lines changed: 391 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,397 @@ The above example would output something similar to:
160160
90201: BELL GARDENS, CA
161161
```
162162

163+
## Inserting One Document
164+
165+
The [insertOne()][insertone] method may be used to insert a single document.
166+
This method returns an instance of `MongoDB\InsertOneResult`, which may be used
167+
to access the ID of the inserted document. Note that if a document does not
168+
contain an `_id` field at the time of insertion, the driver will generate a
169+
`MongoDB\BSON\ObjectID` to use as its ID.
170+
171+
[insertone]: ../classes/collection.md#insertone
172+
173+
```
174+
<?php
175+
176+
$collection = (new MongoDB\Client)->demo->users;
177+
$collection->drop();
178+
179+
$insertOneResult = $collection->insertOne(['name' => 'Bob']);
180+
181+
printf("Inserted %d document(s)\n", $insertOneResult->getInsertedCount());
182+
var_dump($insertOneResult->getInsertedId());
183+
```
184+
185+
The above example would output something similar to:
186+
187+
```
188+
Inserted 1 document(s)
189+
object(MongoDB\BSON\ObjectID)#10 (1) {
190+
["oid"]=>
191+
string(24) "5750905b6118fd170565aa81"
192+
}
193+
```
194+
195+
The following example inserts a document with an ID. Note that if an ID is not
196+
unique for the collection, the insert will fail due to a duplicate key error.
197+
198+
```
199+
<?php
200+
201+
$collection = (new MongoDB\Client)->demo->users;
202+
$collection->drop();
203+
204+
$insertOneResult = $collection->insertOne(['_id' => 1, 'name' => 'Alice']);
205+
206+
printf("Inserted %d document(s)\n", $insertOneResult->getInsertedCount());
207+
var_dump($insertOneResult->getInsertedId());
208+
```
209+
210+
The above example would output:
211+
212+
```
213+
Inserted 1 document(s)
214+
int(1)
215+
```
216+
217+
## Inserting Many Documents
218+
219+
The [insertMany()][insertmany] method may be used to insert multiple documents
220+
at a time. This method returns an instance of `MongoDB\InsertManyResult`, which
221+
may be used to access the IDs of the inserted documents.
222+
223+
[insertmany]: ../classes/collection.md#insertmany
224+
225+
```
226+
<?php
227+
228+
$collection = (new MongoDB\Client)->demo->users;
229+
$collection->drop();
230+
231+
$insertManyResult = $collection->insertMany([
232+
['name' => 'Bob'],
233+
['_id' => 1, 'name' => 'Alice'],
234+
]);
235+
236+
printf("Inserted %d document(s)\n", $insertManyResult->getInsertedCount());
237+
var_dump($insertManyResult->getInsertedIds());
238+
```
239+
240+
The above example would output something similar to:
241+
242+
```
243+
Inserted 2 document(s)
244+
array(2) {
245+
[0]=>
246+
object(MongoDB\BSON\ObjectID)#10 (1) {
247+
["oid"]=>
248+
string(24) "5750927b6118fd1ed64eb141"
249+
}
250+
[1]=>
251+
int(1)
252+
}
253+
```
254+
255+
## Updating One Document
256+
257+
The [updateOne()][updateone] method may be used to update a single document
258+
matching a filter. This method returns an instance of `MongoDB\UpdateResult`,
259+
which may be used to access statistics about the update operation.
260+
261+
[updateone]: ../classes/collection.md#updateone
262+
263+
This method has two required parameters: a query filter and an update document.
264+
The query filter is similar to what might be provided to [find()][find]. The
265+
update document consists of one or more [update operators][updateops].
266+
267+
[updateops]: https://docs.mongodb.com/manual/reference/operator/update/
268+
269+
```
270+
<?php
271+
272+
$collection = (new MongoDB\Client)->demo->users;
273+
$collection->drop();
274+
275+
$collection->insertOne(['name' => 'Bob', 'state' => 'ny']);
276+
$collection->insertOne(['name' => 'Alice', 'state' => 'ny']);
277+
$updateResult = $collection->updateOne(
278+
['state' => 'ny'],
279+
['$set' => ['country' => 'us']]
280+
);
281+
282+
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
283+
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
284+
```
285+
286+
The above example would output something similar to:
287+
288+
```
289+
Matched 1 document(s)
290+
Modified 1 document(s)
291+
```
292+
293+
Note that it is possible for a document to match the filter but not be modified
294+
by an update:
295+
296+
```
297+
<?php
298+
299+
$collection = (new MongoDB\Client)->demo->users;
300+
$collection->drop();
301+
302+
$collection->insertOne(['name' => 'Bob', 'state' => 'ny']);
303+
$updateResult = $collection->updateOne(
304+
['name' => 'Bob'],
305+
['$set' => ['state' => 'ny']]
306+
);
307+
308+
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
309+
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
310+
```
311+
312+
The above example would output something similar to:
313+
314+
```
315+
Matched 1 document(s)
316+
Modified 0 document(s)
317+
```
318+
319+
## Updating Many Documents
320+
321+
The [updateMany()][updatemany] method may be used to update multiple documents
322+
at a time. This method returns an instance of `MongoDB\UpdateResult`, which may
323+
be used to access statistics about the update operation.
324+
325+
[updatemany]: ../classes/collection.md#updatemany
326+
327+
This method has two required parameters: a query filter and an update document.
328+
The query filter is similar to what might be provided to [find()][find]. The
329+
update document consists of one or more [update operators][updateops].
330+
331+
```
332+
<?php
333+
334+
$collection = (new MongoDB\Client)->demo->users;
335+
$collection->drop();
336+
337+
$collection->insertOne(['name' => 'Bob', 'state' => 'ny', 'country' => 'us']);
338+
$collection->insertOne(['name' => 'Alice', 'state' => 'ny']);
339+
$collection->insertOne(['name' => 'Sam', 'state' => 'ny']);
340+
$updateResult = $collection->updateMany(
341+
['state' => 'ny'],
342+
['$set' => ['country' => 'us']]
343+
);
344+
345+
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
346+
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
347+
```
348+
349+
The above example would output something similar to:
350+
351+
```
352+
Matched 3 document(s)
353+
Modified 2 document(s)
354+
```
355+
356+
## Replacing One Document
357+
358+
The [replaceOne()][replaceone] method may be used to replace a single document
359+
matching a filter. This method returns an instance of `MongoDB\UpdateResult`,
360+
which may be used to access statistics about the replacement operation.
361+
362+
[replaceone]: ../classes/collection.md#replaceone
363+
364+
This method has two required parameters: a query filter and a replacement
365+
document. The query filter is similar to what might be provided to
366+
[find()][find]. The replacement document will be used to overwrite the matched
367+
document (excluding its ID, which is immutable) and must not contain
368+
[update operators][updateops].
369+
370+
Note that the very nature of a replacement operation makes it easy to
371+
inadvertently overwrite or delete fields in a document. When possible, users
372+
should consider updating individual fields with [updateOne()][updateone] or
373+
[updateMany()][updatemany].
374+
375+
```
376+
<?php
377+
378+
$collection = (new MongoDB\Client)->demo->users;
379+
$collection->drop();
380+
381+
$collection->insertOne(['name' => 'Bob', 'state' => 'ny']);
382+
$updateResult = $collection->replaceOne(
383+
['name' => 'Bob'],
384+
['name' => 'Robert', 'state' => 'ca']
385+
);
386+
387+
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
388+
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
389+
```
390+
391+
The above example would output something similar to:
392+
393+
```
394+
Matched 1 document(s)
395+
Modified 1 document(s)
396+
```
397+
398+
Note that it is possible for a document to match the filter but not be modified
399+
by a replacement (i.e. the matched document and replacement may be the same).
400+
401+
## Upserting a Document
402+
403+
An upsert is a variation of an update or replace operation, whereby a new
404+
document is inserted if the query filter does not match an existing document.
405+
An upsert may be specified via the `upsert` option for [updateOne()][updateone],
406+
[updateMany()][updatemany], or [replaceOne()][replaceone]. The logic by which
407+
the inserted document is created is discussed in the [MongoDB manual][upsert].
408+
409+
[upsert]: https://docs.mongodb.com/manual/reference/method/db.collection.update/#upsert-parameter
410+
411+
If a document has been upserted, its ID will be accessible via
412+
`MongoDB\UpdateResult::getUpsertedId()`.
413+
414+
The following example demonstrates an upsert via [updateOne()][updateone]:
415+
416+
```
417+
<?php
418+
419+
$collection = (new MongoDB\Client)->demo->users;
420+
$collection->drop();
421+
422+
$updateResult = $collection->updateOne(
423+
['name' => 'Bob'],
424+
['$set' => ['state' => 'ny']],
425+
['upsert' => true]
426+
);
427+
428+
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
429+
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
430+
var_dump($collection->findOne(['_id' => $updateResult->getUpsertedId()]));
431+
```
432+
433+
The above example would output something similar to:
434+
435+
```
436+
Matched 0 document(s)
437+
Modified 0 document(s)
438+
object(MongoDB\Model\BSONDocument)#16 (1) {
439+
["storage":"ArrayObject":private]=>
440+
array(3) {
441+
["_id"]=>
442+
object(MongoDB\BSON\ObjectID)#15 (1) {
443+
["oid"]=>
444+
string(24) "57509c4406d7241dad86e7c3"
445+
}
446+
["name"]=>
447+
string(3) "Bob"
448+
["state"]=>
449+
string(2) "ny"
450+
}
451+
}
452+
```
453+
454+
The following example demonstrates an upsert via [replaceOne()][replaceone]:
455+
456+
```
457+
<?php
458+
459+
$collection = (new MongoDB\Client)->demo->users;
460+
$collection->drop();
461+
462+
$updateResult = $collection->replaceOne(
463+
['name' => 'Bob'],
464+
['name' => 'Alice', 'state' => 'ny'],
465+
['upsert' => true]
466+
);
467+
468+
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
469+
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
470+
var_dump($collection->findOne(['_id' => $updateResult->getUpsertedId()]));
471+
```
472+
473+
The above example would output something similar to:
474+
475+
```
476+
Matched 0 document(s)
477+
Modified 0 document(s)
478+
object(MongoDB\Model\BSONDocument)#16 (1) {
479+
["storage":"ArrayObject":private]=>
480+
array(3) {
481+
["_id"]=>
482+
object(MongoDB\BSON\ObjectID)#15 (1) {
483+
["oid"]=>
484+
string(24) "57509c6606d7241dad86e7c4"
485+
}
486+
["name"]=>
487+
string(5) "Alice"
488+
["state"]=>
489+
string(2) "ny"
490+
}
491+
}
492+
```
493+
494+
## Deleting One Document
495+
496+
The [deleteOne()][deleteone] method may be used to delete a single document
497+
matching a filter. This method returns an instance of `MongoDB\DeleteResult`,
498+
which may be used to access statistics about the delete operation.
499+
500+
[deleteone]: ../classes/collection.md#deleteone
501+
502+
This method has two required parameters: a query filter. The query filter is
503+
similar to what might be provided to [find()][find].
504+
505+
```
506+
<?php
507+
508+
$collection = (new MongoDB\Client)->demo->users;
509+
$collection->drop();
510+
511+
$collection->insertOne(['name' => 'Bob', 'state' => 'ny']);
512+
$collection->insertOne(['name' => 'Alice', 'state' => 'ny']);
513+
$deleteResult = $collection->deleteOne(['state' => 'ny']);
514+
515+
printf("Deleted %d document(s)\n", $deleteResult->getDeletedCount());
516+
```
517+
518+
The above example would output something similar to:
519+
520+
```
521+
Deleted 1 document(s)
522+
```
523+
524+
## Deleting Many Documents
525+
526+
The [deleteMany()][deletemany] method may be used to delete multiple documents
527+
at a time. This method returns an instance of `MongoDB\DeleteResult`, which may
528+
be used to access statistics about the delete operation.
529+
530+
[deletemany]: ../classes/collection.md#deletemany
531+
532+
This method has two required parameters: a query filter. The query filter is
533+
similar to what might be provided to [find()][find].
534+
535+
```
536+
<?php
537+
538+
$collection = (new MongoDB\Client)->demo->users;
539+
$collection->drop();
540+
541+
$collection->insertOne(['name' => 'Bob', 'state' => 'ny']);
542+
$collection->insertOne(['name' => 'Alice', 'state' => 'ny']);
543+
$deleteResult = $collection->deleteMany(['state' => 'ny']);
544+
545+
printf("Deleted %d document(s)\n", $deleteResult->getDeletedCount());
546+
```
547+
548+
The above example would output something similar to:
549+
550+
```
551+
Deleted 2 document(s)
552+
```
553+
163554
## Aggregation
164555

165556
The [Aggregation Framework][aggregation] may be used to issue complex queries

0 commit comments

Comments
 (0)