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)