MONGOCOLLECTION.FINDANDMODIFY(3) 1 MONGOCOLLECTION.FINDANDMODIFY(3)
MongoCollection::findAndModify - Update a document and return it
SYNOPSIS
public array MongoCollection::findAndModify (array $query, [array $update], [array $fields], [array $options])
DESCRIPTION
The findAndModify command atomically modifies and returns a single document. By default, the returned document does not include the modi-
fications made on the update. To return the document with the modifications made on the update, use the $new option.
PARAMETERS
o $query
- The query criteria to search for.
o $update
- The update criteria.
o $fields
- Optionally only return these fields.
o $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 boolean | |
| | |
| | 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 boolean | |
| | |
| | Optional. When TRUE, returns the modified docu- |
| | ment rather than the original. The findAndModify |
| | method ignores the $new option for remove opera- |
| | tions. The default is FALSE. |
| | |
|$upsert boolean | |
| | |
| | Optional. Used in conjunction with the $update |
| | field. When TRUE, the findAndModify command cre- |
| | ates a new document if the query returns no docu- |
| | ments. 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(), "
";
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.
PHP Documentation Group MONGOCOLLECTION.FINDANDMODIFY(3)