MongoCollection
PHP Manual

MongoCollection::save

(PECL mongo >=0.9.0)

MongoCollection::save — ドキュメントをコレクションに保存する

説明

public mixed MongoCollection::save ( array|object $a [, array $options = array() ] )

データベースから取得したオブジェクトの場合はデータベース上の既存のオブジェクトを更新し、 それ以外の場合はオブジェクトを追加します。

パラメータ

a

保存したい配列あるいはオブジェクト。オブジェクトを使う場合は、 protected や private のプロパティは保持できません。

注意:

_id のキーあるいはプロパティを持たない場合は、 新しい MongoId インスタンスを作ってそれを代入します。 この挙動に関する詳しい情報は MongoCollection::insert() を参照ください。

options

保存時のオプション。

  • "fsync"

    Boolean 型で、デフォルトは FALSE です。 ジャーナリングが有効な場合、これは "j" とまったく同じ動きをします。 ジャーナリングが有効でない場合は、追加をディスク上のデータベースファイルに同期させるまで成功したと見なさないようになります。 TRUE にすると確認つき書き込みが暗黙のうちに設定され、"w" の値を 0 にします。

    注意: ジャーナリングが有効な場合は、"fsync" のかわりに "j" を使いましょう。 "fsync" と "j" を同時に指定すると、エラーになります。

  • "j"

    デフォルトは FALSE です。これを指定すると、追加をジャーナルに同期させるまで成功したと見なさないようになります。TRUE にすると確認付き書き込みと見なされ、"w" の設定を 0 に上書きします。

    注意: このオプションを使っているときにジャーナリングを無効にすると、MongoDB 2.6 以降ではエラーが発生して書き込みに失敗します。古いバージョンのサーバーでは、単純にオプションの師弟を無視します。

  • 整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。

    "socketTimeoutMS"

  • "w"

    WriteConcerns を参照ください。MongoClient でのデフォルト値は 1 です。

  • "wtimeout"

    WriteConcern の確認をいつまで待つか。 MongoClient のデフォルトは 10000 ミリ秒です。

    警告

    非推奨です。かわりに "wTimeoutMS" オプションを使いましょう。

  • "wTimeoutMS"

    WriteConcern の確認をいつまで待つか。MongoClient のデフォルトは 10000 ミリ秒です。

  • "safe"

    非推奨。WriteConcern の w オプションを使いましょう。

  • "timeout"

    整数で、デフォルトは MongoCursor::$timeout です。確認付き書き込みを使っている場合、これはクライアントがデータベースからのレスポンスを待ち続ける時間 (ミリ秒) を表します。この時間内にデータベースからの反応がなければ、MongoCursorTimeoutException をスローします。

    警告

    非推奨です。かわりに "socketTimeoutMS" オプションを使いましょう。

返り値

w が設定されている場合は、 保存結果を含む配列を返します。設定されていない場合は、 配列が空でなかったかどうかをあらわす boolean 値を返します (空の配列は追加されません)。

エラー / 例外

追加したドキュメントが空だったり長さがゼロのキーが含まれていたりした場合に MongoException をスローします。 protected や private なプロパティを持つオブジェクトを追加しようとすると、 キーの長さがゼロのエラーを引き起こします。

"w" オプションが設定されていて書き込みが失敗した場合に MongoCursorException をスローします。

"w" オプションの値が 1 より大きく設定されていて、操作の完了までの時間が MongoCursor::$timeout ミリ秒をこえた場合に MongoCursorTimeoutException をスローします。サーバー上での操作は止めません。これはクライアント側でのタイムアウトです。MongoCollection::$wtimeout はミリ秒です。

変更履歴

バージョン 説明
1.5.0 オプション "wtimeout" の名前が "wTimeoutMS" に変わりました。
1.5.0 オプション "timeout" の名前が "socketTimeoutMS" に変わりました。
1.2.0 "timeout" オプションが追加されました。
1.0.11 "safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
1.0.9

"safe" オプションに整数値がわたせるようになりました (以前は boolean のみでした)。

"fsync" オプションが追加されました。

1.0.5 options パラメータが追加されました。

例

例1 MongoCollection::save() の例

<?php

$obj = array('x' => 1);

// $obj を db に追加します
$collection->save($obj);
var_dump($obj);

// 別のフィールドを追加します
$obj['foo'] = 'bar';

// $obj をもう一度追加することはできません。_id が重複しているからです
$collection->insert($obj);

// 新しいフィールドつきの $obj で上書きします
$collection->save($obj);

?>

上の例の出力は、 たとえば以下のようになります。

array(2) {
  ["x"]=>
  int(1)
  ["_id"]=>
  object(MongoId)#4 (1) {
    ["$id"]=>
    string(24) "50b6afe544415ed606000000"
  }
}
MongoCollection
PHP Manual