# MongoCollection::findAndModify

(PECL mongo >=1.3.0)

MongoCollection::findAndModify — Update a document and return it

### Description

public MongoCollection::findAndModify ( array `$query` [, array `$update` [, array `$fields` [, array `$options` ]]] ) : array

The findAndModify command atomically modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the new option.

### Parameters

`query`

  The query criteria to search for.

`update`

  The update criteria.

`fields`

  Optionally only return these fields.

`options`

  An array of options to apply, such as remove the match document from the DB and return it.

  Option | Description
  --- | ---
  sort array | Determines which document the operation will modify if the query selects multiple documents. findAndModify will modify the first document in the sort order specified by this argument.
  remove bool | Optional if update field exists. When `TRUE`, removes the selected document. The default is `FALSE`.
  update array | Optional if remove field exists. Performs an update of the selected document.
  new bool | Optional. When `TRUE`, returns the modified document rather than the original. The findAndModify method ignores the new option for remove operations. The default is `FALSE`.
  upsert bool | Optional. Used in conjunction with the update field. When `TRUE`, the findAndModify command creates a new document if the query returns no documents. The default is false. In MongoDB 2.2, the findAndModify command returns `NULL` when upsert is `TRUE`.

### Return Values

Returns the original document, or the modified document when new is set.

### Errors/Exceptions

Throws MongoResultException on failure.

### Examples

Example #1 MongoCollection::findAndModify() example

`<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
$col->insert(array(
"name" => "Next promo",
"inprogress" => false,
"priority" => 0,
"tasks" => array( "select product", "add inventory", "do placement"),
) );
$col->insert(array(
"name" => "Biz report",
"inprogress" => false,
"priority" => 1,
"tasks" => array( "run sales report", "email report" )
) );
$col->insert(array(
"name" => "Biz report",
"inprogress" => false,
"priority" => 2,
"tasks" => array( "run marketing report", "email report" )
),
array("w" => 1)
);
$retval = $col->findAndModify(
array("inprogress" => false, "name" => "Biz report"),
array('$set' => array('inprogress' => true, "started" => new MongoDate())),
null,
array(
"sort" => array("priority" => -1),
"new" => true,
)
);
var_dump($retval);
?>`

The above example will output something similar to:

    array(6) {
      ["_id"]=>
      object(MongoId)#7 (1) {
        ["$id"]=>
        string(24) "5091b5b244415e8cc3000002"
      }
      ["inprogress"]=>
      bool(true)
      ["name"]=>
      string(10) "Biz report"
      ["priority"]=>
      int(2)
      ["started"]=>
      object(MongoDate)#8 (2) {
        ["sec"]=>
        int(1351726514)
        ["usec"]=>
        int(925000)
      }
      ["tasks"]=>
      array(2) {
        [0]=>
        string(20) "run marketing report"
        [1]=>
        string(12) "email report"
      }
    }

Example #2 MongoCollection::findAndModify() error handling

`<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
try {
$retval = $col->findAndModify(
array("inprogress" => false, "name" => "Next promo"),
array('$pop' => array("tasks" => -1)),
array("tasks" => array('$pop' => array("stuff"))),
array("new" => true)
);
} catch(MongoResultException $e) {
echo $e->getCode(), " : ", $e->getMessage(), "\n";
var_dump($e->getDocument());
}
?>`

The above example will output something similar to:

    13097 : exception: Unsupported projection option: $pop
    array(3) {
      ["errmsg"]=>
      string(46) "exception: Unsupported projection option: $pop"
      ["code"]=>
      int(13097)
      ["ok"]=>
      float(0)
    }

### See Also

- The MongoDB » findAndModify command docs