オブジェクトをコレクションに保存する

説明

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

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

パラメータ

a

保存したい配列。

options

保存時のオプション。

"safe"

boolean あるいは整数値で、デフォルトは FALSE です。FALSE の場合、データベースからの応答を待たずにプログラムを続行します。 TRUE の場合、プログラムはデータベースからの応答を待ち、追加に失敗したときには MongoCursorException をスローします。

レプリケーションを使っていてマスタを変更している場合、もし "safe" を使っていればドライバはマスタとの接続を切断して例外をスローし、次の操作時に新しいマスタを探そうとします (新しいマスタに対して操作を再試行するかどうかはアプリケーション側で判断しなければなりません)。

レプリカセットで "safe" を 使わずに マスタを変更する場合は、ドライバがその変更について知るすべがありません。そのため、何もエラーを出さずに書き込みに失敗し続けます。

safe が整数値の場合は、指定した数のマシンで追加が成功するまでは成功したと見なしません (処理がタイムアウトした場合は例外をスローします。wtimeout を参照ください)。これは、コレクションに設定された w 変数をオーバーライドします。
"fsync"

boolean で、デフォルトは FALSE です。追加操作がディスク上に同期されるまで成功とは見なさないようにさせます。 TRUE の場合は "安全な" 追加操作が前提となり、 safe の設定を FALSE にオーバーライドします。
"timeout"

整数値。デフォルトは MongoCursor::$timeout です。 "safe" が設定されている場合に、クライアントがデータベースからの応答をどれだけ待つかを (ミリ秒単位で) 指定します。ここで指定した時間内にデータベースからの応答がない場合は MongoCursorTimeoutException がスローされます。

返り値

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

エラー / 例外

"safe" オプションが設定されていて保存に失敗した場合に MongoCursorException をスローします。

"safe" オプションが設定されているときに MongoCollection::$wtimeout ミリ秒以内に処理が終わらなければ MongoCursorTimeoutException をスローします。これはサーバ上の操作を終了させるわけではなく、あくまでもクライアント側のタイムアウトです。

変更履歴

バージョン	説明
1.0.5	"options" パラメータが追加されました。
1.0.9	"safe" オプションに整数値がわたせるようになり (以前は booleans のみでした)、さらに "fsync" オプションが追加されました。
1.0.11	"safe" が設定されている場合は、"not master" エラーで接続を切断するようになりました。
1.2.0	timeout オプションが追加されました。

例

例1 MongoCollection::save() の例


<?php

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

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

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

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

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

?>