Implement Collection modify() and remove() via findAndModify

[thekid]

This pull requests adds new methods to the Collection class:

• modify() - much like upsert, with the difference that it also returns the modified document.
• remove() - same as delete but returns the document as it existed before deletion

These methods are slower by nature because of the document being part of the response payload. If you're not interested in the modified / deleted documents, simply use upsert and delete.

Example

The following code becomes more concise:

  $statements= ['$set' => ['slug' => $slug, ...$entity]];
- $arguments= [
-   'query'  => ['slug' => $slug],
-   'update' => $statements,
-   'new'    => true,  // Return modified document
-   'upsert' => true,
- ];
- $value= $this->entries->run('findAndModify', $arguments)->value()['value'];
- $doc= $value ? new Document($value) : null; 
+ $doc= $this->entries->modify(['slug' => $slug], $statements, upsert: true)->document();

See also

• https://www.mongodb.com/docs/manual/reference/command/findAndModify/
• https://stackoverflow.com/questions/10778493/whats-the-difference-between-findandmodify-and-update-in-mongodb

[thekid]

Released in https://github.com/xp-forge/mongodb/releases/tag/v2.2.0

[thekid]

Real-life example from https://github.com/thekid/crews:

   #[Put]
   public function describe(#[Value] User $user, ObjectId $group, #[Param] string $description) {
     // Shortened for brevity: Verify user is group owner
-    $result= $this->groups->run('findAndModify', [
-      'query'  => ['_id' => $group],
-      'update' => ['$set' => ['description' => $description]],
-      'new'    => true,  // Return modified document
-      'upsert' => false,
-    ]);
-    return View::named('group#description')->with($result->value()['value']);
+    $result= $this->groups->modify($group, ['$set' => ['description' => $description]]);
+    return View::named('group#description')->with($result->document());
   }