MongoCollection::findAndModify
(PECL mongo >=1.3.0)
MongoCollection::findAndModify — ドキュメントを更新して返す
説明
public MongoCollection::findAndModify
( array $query
[, array $update
[, array $fields
[, array $options
]]] ) : array
findAndModify コマンドは、単一のドキュメントをアトミックに変更して返します。
デフォルトでは、返されるドキュメントには、この更新による変更内容が含まれません。
更新で変更した結果のドキュメントを返すには、new
オプションを使います。
パラメータ
query
クエリの検索条件。
update
更新条件。
fields
オプションで、返すフィールドを絞り込めます。
options
適用するオプションの配列。マッチしたドキュメントを DB から削除してから返すなどのオプションを指定できます。
オプション 説明 sort
arrayクエリが複数のドキュメントを選択したときに、どのドキュメントを変更するかを決めます。 findAndModify が変更するのは、この引数で指定した並び順で最初にあるドキュメントだけです。
remove
boolupdate
フィールドが存在するときは必須ではありません。true
にすると、選択したドキュメントを削除します。デフォルトはfalse
です。update
arrayremove
フィールドが存在するときは必須ではありません。選択したドキュメントを更新します。
new
bool必須ではありません。 true
にすると、変更前のドキュメントではなく変更後のドキュメントを返します。findAndModify メソッドは、remove 操作のときには
new
オプションを無視します。 デフォルトはfalse
です。upsert
bool必須ではありません。 update
と組み合わせて使います。true
にすると、クエリがドキュメントを返さないときに findAndModify コマンドが新しいドキュメントを作ります。 デフォルトはfalse
です。MongoDB 2.2 では、upsert がtrue
のときに findAndModify コマンドはnull
を返します。
返り値
元のドキュメントを返します。
new
が設定されている場合は変更後のドキュメントを返します。
例
例1 MongoCollection::findAndModify() の例
<?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);?>
上の例の出力は、 たとえば以下のようになります。
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" } }
例2 MongoCollection::findAndModify() のエラー処理
<?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());}?>
上の例の出力は、 たとえば以下のようになります。
13097 : exception: Unsupported projection option: $pop array(3) { ["errmsg"]=> string(46) "exception: Unsupported projection option: $pop" ["code"]=> int(13097) ["ok"]=> float(0) }