MongoCollection::save
(PECL mongo >=0.9.0)
MongoCollection::save — Saves a document to this collection
Beschreibung
public MongoCollection::save
(
array|object $document
[,
array $options
= array()
] ) :
mixed
Parameter-Liste
-
document
-
Array or object to save. If an object is used, it may not have protected
or private properties.
Hinweis:
If the parameter does not have an _id
key or
property, a new MongoId instance will be created
and assigned to it. See MongoCollection::insert() for
additional information on this behavior.
-
options
-
Options for the save.
"fsync"
Boolean, defaults to FALSE
. If journaling is enabled, it works exactly like "j"
. If journaling is not enabled, the write operation blocks until it is synced to database files on disk. If TRUE
, an acknowledged insert is implied and this option will override setting "w"
to 0
.
Hinweis: If journaling is enabled, users are strongly encouraged to use the "j"
option instead of "fsync"
. Do not use "fsync"
and "j"
simultaneously, as that will result in an error.
"j"
Boolean, defaults to FALSE
. Forces the write operation to block until it is synced to the journal on disk. If TRUE
, an acknowledged write is implied and this option will override setting "w"
to 0
.
Hinweis: If this option is used and journaling is disabled, MongoDB 2.6+ will raise an error and the write will fail; older server versions will simply ignore the option.
"socketTimeoutMS"
This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a MongoCursorTimeoutException will be thrown and there will be no way to determine if the server actually handled the write or not. A value of -1
may be specified to block indefinitely. The default value for MongoClient is 30000
(30 seconds).
"w"
See Write Concerns. The default value for MongoClient is 1
.
"wtimeout"
Deprecated alias for "wTimeoutMS"
.
"wTimeoutMS"
This option specifies the time limit, in milliseconds, for write concern acknowledgement. It is only applicable when "w"
is greater than 1
, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a MongoCursorException will be thrown. A value of 0
may be specified to block indefinitely. The default value for MongoClient is 10000
(ten seconds).
"safe"
Deprecated. Please use the write concern "w"
option.
"timeout"
Deprecated alias for "socketTimeoutMS"
.
Rückgabewerte
If w
was set, returns an array containing the status of the save.
Otherwise, returns a boolean representing if the array was not empty (an empty array will not
be inserted).
Fehler/Exceptions
Throws MongoException if the inserted document is
empty or if it contains zero-length keys. Attempting to insert an object with
protected and private properties will cause a zero-length key error.
Throws MongoCursorException if the "w"
option is set and the write fails.
Throws MongoCursorTimeoutException if the "w"
option is set to a value greater than one and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server, it is a client-side timeout. The operation in MongoCollection::$wtimeout is milliseconds.
Beispiele
Beispiel #1 MongoCollection::save() example
<?php
$obj = array('x' => 1);
// insert $obj into the db
$collection->save($obj);
var_dump($obj);
// add another field
$obj['foo'] = 'bar';
// $obj cannot be inserted again, causes duplicate _id error
$collection->insert($obj);
// save updates $obj with the new field
$collection->save($obj);
?>
Das oben gezeigte Beispiel erzeugt
eine ähnliche Ausgabe wie:
array(2) {
["x"]=>
int(1)
["_id"]=>
object(MongoId)#4 (1) {
["$id"]=>
string(24) "50b6afe544415ed606000000"
}
}