Edit Report a Bug

    MongoCollection::save

    (PECL mongo >=0.9.0)

    MongoCollection::save — Guarda un documento en esta colección

    Descripción

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

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

    Parámetros

    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".

    Valores devueltos

    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á).

    Errores/Excepciones

    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.

    Historial de cambios

    Versión Descripción
    1.5.0

    Se añadió la opción "wTimeoutMS", la cual reemplaza a "wtimeout". Emite un error E_DEPRECATED al utilizar "wtimeout".

    Se añadió la opción "socketTimeoutMS", la cual reemplaza a "timeout". Emite un error E_DEPRECATED al utilizar "wtimeout".

    Emite un error E_DEPRECATED al utilizar "safe".

    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.

    Ejemplos

    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"
  }
}
    add a note add a note

    User Contributed Notes 1 note

    up
    -6
    cuisdy at gmail dot com
    12 years ago
    Same as with method insert(), it is worth noting that creating a reference to $obj will have the same effect as $obj being a reference itself, i.e. no _id field will be added.

    <?php

    $a     = &$obj;

    $m = new MongoClient;
    $collection = $m->test->phpmanual;

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

    // Suppose you create a reference for some reason
    $a = &$obj;

    $collection->save($obj);

    var_dump($obj);
    // prints: array(1) { ["x"]=> int(1) }
    ?>
    add a note add a note
    To Top