ドキュメントを更新して返す

# 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 boolean | update フィールドが存在するときは必須ではありません。 `TRUE` にすると、選択したドキュメントを削除します。デフォルトは `FALSE` です。
  update array | remove フィールドが存在するときは必須ではありません。 選択したドキュメントを更新します。
  new boolean | 必須ではありません。`TRUE` にすると、変更前のドキュメントではなく変更後のドキュメントを返します。 findAndModify メソッドは、remove 操作のときには new オプションを無視します。 デフォルトは `FALSE` です。
  upsert boolean | 必須ではありません。update と組み合わせて使います。 `TRUE` にすると、クエリがドキュメントを返さないときに findAndModify コマンドが新しいドキュメントを作ります。 デフォルトは `FALSE` です。MongoDB 2.2 では、upsert が `TRUE` のときに findAndModify コマンドは `NULL` を返します。

### 返り値

元のドキュメントを返します。 new が設定されている場合は変更後のドキュメントを返します。

### エラー / 例外

失敗した場合に MongoResultException をスローします。

### 例

例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)
    }

### 参考

- MongoDB の » findAndModify コマンド のドキュメント