(PECL mongo >=0.9.0)
MongoCollection::save — Guarda un documento en esta colección
Si el objeto fuera de la base de datos, se actualizará. En caso contrario, se insertará.
document
Array u objeto a guardar. Si se usa un objeto, este no puede tener propiedades protegidas o privadas.
Nota:
Si el parámetro no posee una clave o propiedad _id, se creará una nueva instancia de MongoId y se le asignará. Véase MongoCollection::insert() para información adicional sobre este comportamiento.
options
Opciones para el guardado.
"fsync"
Booleano, cuyo valor predeterminado es FALSE. Si el registro en el diario está habilitado, funciona exactamente igual que "j". Si no está habilidato, la operación de escriturá bloqueará hasta que se sincronice con los ficheros de la base de datos del disco. Si es TRUE, implica una inserción reconocida y sobrescribirá el ajuste "w" a 0.
Nota: Si está habilitada, se recomienda a los usuarios usar la opción "j" en lugar de "fsync". No use "fsync" y "j" simultáneamente, ya que resultará en un error.
"j"
Booleano, cuyo valor predeterminado es FALSE. Fuerza a la operación de escritura a bloquear hasta que sea sincronizada con el diario del disco. Si es TRUE, implica una escritura reconocida y sobrescribirá el ajuste "w" a 0.
Nota: Si se usa esta opción y el registro en el diario está deshabilitado, MongoDB 2.6+ emitirá un error y la escritura fallará; las versiones más antiguas del servidor simplemente ignoran esta opción.
"socketTimeoutMS"
Esta opción especifica el tiempo límite, en milisegundos, para las comunicaciones con socket. Si el servidor no responde en el periodo especificado, se lanzará una MongoCursorTimeoutException y no habrá forma de determinar si el servidor manejó realmente la escritura o no. Se podría especificar un valor de -1 para bloquear indefinidamente. El valor predeterminado para MongoClient es 30000 (30 segundos).
"w"
Véase WriteConcerns. El valor predeterminado de MongoClient es 1.
"wtimeout"
Alias obsoleto de "wTimeoutMS".
"wTimeoutMS"
Esta opción especifica el tiempo límite, en milisegundos, para el reconocimiento de un asunto de escritura. Solamente es aplicable cuando "w" sea mayor que 1, ya que el tiempo de espera está relacionado con la replecación. Si el asunto de escritura no se satisface dentro del tiempo límite, se lanzará una MongoCursorException. Se puede especificar un valor de 0 para bloquear indefinidamente. El valor predeterminado es 10000 (diez segundos).
"safe"
Obsoleto. Use la opción w de los asuntos de escritura.
"timeout"
Alias obsoleto de "socketTimeoutMS".
Si w estuviera habilitado, devolverá un array que contiene el estado de la
escritura. En cualquier otro caso, devuelve un booleano que representa si el array no estaba vacío
(un array vacío no se insertará).
Lanza una MongoException si el documento insertado está vacío o si contiene claves de longitud cero. Intentar insertar un objeto con propiedades protegidas o privadas causará un error de clave de longitud cero.
Lanza una MongoCursorException si la opción "w" está establecida y la escritura falla.
Lanza una MongoCursorTimeoutException si la opción "w" está establecida a un valor mayor que uno y la operación toma más de MongoCursor::$timeout milisegundos en completarse. Esto no pondrá fin a la operación en el servidor, es un tiempo límite del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.
| Versión | Descripción |
|---|---|
| 1.5.0 |
Se añadió la opción "wTimeoutMS", la cual reemplaza a
"wtimeout". Emite un error
Se añadió la opción "socketTimeoutMS", la cual reemplaza a
"timeout". Emite un error
Emite un error |
| 1.2.0 | Añadida la opción "timeout". |
| 1.0.11 | Se desconecta en errores "not master" si "safe" está establecido. |
| 1.0.9 |
Añadida la opción "fsync". |
| 1.0.5 | Añadido el parámetro options. |
Ejemplo #1 Ejemplo de MongoCollection::save()
<?php
$obj = array('x' => 1);
// insertar $obj en la base de datos
$collection->save($obj);
var_dump($obj);
// añadir otro campo
$obj['foo'] = 'bar';
// $obj no puede insertarse de nuevo; provoca un error de _id duplicado
$collection->insert($obj);
// la función save actualiza $obj con el nuevo campo
$collection->save($obj);
?>
El resultado del ejemplo sería algo similar a:
array(2) {
["x"]=>
int(1)
["_id"]=>
object(MongoId)#4 (1) {
["$id"]=>
string(24) "50b6afe544415ed606000000"
}
}