diff --git a/reference/mongo/mongocollection/findandmodify.xml b/reference/mongo/mongocollection/findandmodify.xml new file mode 100644 index 0000000000..bdd55ae079 --- /dev/null +++ b/reference/mongo/mongocollection/findandmodify.xml @@ -0,0 +1,288 @@ + + + + + + MongoCollection::findAndModify + Update a document and return it + + + + &reftitle.description; + + public voidMongoCollection::findAndModify + arrayquery + arrayupdate + arrayfields + arrayoptions + + + 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. + + + + + + &reftitle.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 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 document rather than the + original. The findAndModify method ignores the new option for + remove operations. The default is &false;. + + + + upsert boolean + + 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;. + + + + + + + + + + + + + + + + + + &reftitle.returnvalues; + + Returns the original document, or the modified document when + new is set. + + + + + &reftitle.errors; + + Throws MongoResultException on failure. + + + + + &reftitle.examples; + + <methodname>MongoCollection::findAndModify</methodname> example + +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("safe" => true) +); + + + +$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); +?> +]]> + + &example.outputs.similar; + + + 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" + } +} +]]> + + + + <methodname>MongoCollection::findAndModify</methodname> error handling + +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()); +} + +?> +]]> + + &example.outputs.similar; + + + string(46) "exception: Unsupported projection option: $pop" + ["code"]=> + int(13097) + ["ok"]=> + float(0) +} +]]> + + + + + + &reftitle.seealso; + + The MongoDB findAndModify command docs + + + + + + +