MongoCollection
PHP Manual

MongoCollection::save

(PECL mongo >=0.9.0)

MongoCollection::saveGuarda un objeto en esta colección

Descripción

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

Si el objeto fuera de la base de datos, se actualizaría. En caso contrario, se insertaría.

Parámetros

a

Array a guardar.

options

Opciones de guardado.

  • "safe"

    Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperará la respuesta de la base de datos y emitira una excepcion MongoCursorException si la inserción no tuviera éxito.

    Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro).

    Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará.

    Si safe fuera un entero, replicará la inserción a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

  • "fsync"

    Booleano, por omisión FALSE. Obliga a que la inserción se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una inserción segura (safe) y sobrescribirá el ajuste safe a FALSE.

  • "timeout"

    Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto tiempo (en milisegundos) esperará el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Si safe estuviera habilitado, devolvería 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á).

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" está habilitada y fallara al guardar.

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y a la operación llevara más de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción
1.0.5 Añadido el parámetro "options".
1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".
1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.
1.2.0 Añadida la opción "timeout".

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::save()

<?php

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

// insertar $obj en la base de datos
$collection->save($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);

?>

MongoCollection
PHP Manual