MongoCollection::save

(PECL mongo >=0.9.0)

MongoCollection::save — Saves a document to this collection

Descrierea

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

If the object is from the database, update the existing database object, otherwise insert this object.

Parametri

document

Array or object to save. If an object is used, it may not have protected or private properties.

Notă:

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"

    O valoare boolean-ă, valoarea implicită este FALSE. Dacă jurnalizarea e activată, ea funcționează exact ca "j". Dacă jurnalizarea nu este acticvată, atunci se forțează sincronizarea pe disc a operațiunii de inserare înainte de a întoarce succes. Dacă are valoarea TRUE, se presupune efectuarea unei inserări cu confirmare și setarea w va fi modificată în 0.

    Notă: Dacă jurnalizarea este activată, utilizatorii sunt încurajați să utilizeze opțiunea "j" în loc de "fsync". Nu utilizați "fsync" și "j" simultan, deoarece aceasta va rezulta în eroare.

  • "j"

    O valoare boolean-ă, cu valoarea implicită FALSE. Forțează sincronizarea cu jurnalul a operațiunii de inserare, înainte de a întoarce succes. Dacă are valoarea TRUE, se presupune efectuarea unei inserări cu confirmare și setarea w va fi modificată în 0.

    Notă: Dacă această opțiune e utilizată, iar jurnalizarea e dezactivată, MongoDB 2.6+ va emite o eroare și înscrierea va eșua; versiunile mai vechi ale serverului pur și simplu vor ignora opțiunea.

  • "socketTimeoutMS"

    Această opțiune specifică limita de timp în milisecunde pentru comunicarea prin socket. Dacă serverul nu răspunde în limita intervalului de timp, se va emite o MongoCursorTimeoutException și nu va fi nici o posibilitate de a determina dacă serverul a efectuat înscrierea, sau nu. Valoarea -1 poate fi specificată pentru a suspenda pentru o perioadă nedefinită. Valoarea implicită pentru MongoClient este 30000 (30 secunde).

  • "w"

    Vedeți WriteConcerns. Valoarea implicită pentru MongoClient este 1.

  • "wtimeout"

    Un pseudonim învechit pentru "wTimeoutMS".

  • "wTimeoutMS"

    Această opțiune specifică limita de timp în milisecunde pentru confirmarea write concern. Aceasta este aplicabilă doar atunci când "w" este mai mare decât 1, deoarece expirarea timpului ține de replicare. Dacă "write concern" nu este satisfăcută în limita intervalului de timp, se va emite o MongoCursorException. Valoarea 0 poate fi specificată pentru a suspenda pentru o perioadă nedefinită. Valoarea implicită pentru MongoClient este 10000 (zece secunde).

  • "safe"

    Învechită. Utilizați opțiunea WriteConcern w.

  • "timeout"

    Un pseudonim învechit pentru "socketTimeoutMS".

Valorile întoarse

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

Erori/Excepții

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.

Generează o excepție MongoCursorException dacă opțiunea "w" este stabilită și înscrierea eșuează.

Generează o excepție MongoCursorTimeoutException dacă opțiunea "w" este stabilită la o valoare mai mare decât unu și operațiunea durează mai mult de MongoCursor::$timeout milisecunde. Aceasta nu va întrerupe operațiunea pe server, este un timeout de partea clientului. Operațiunea din MongoCollection::$wtimeout este în milisecunde.

Istoricul schimbărilor

Versiune Descriere
1.5.0

Added "wTimeoutMS" option, which replaces "wtimeout". Emits E_DEPRECATED when "wtimeout" is used.

Added "socketTimeoutMS" option, which replaces "timeout". Emits E_DEPRECATED when "timeout" is used.

Emits E_DEPRECATED when "safe" is used.

1.2.0 Added "timeout" option.
1.0.11 Disconnects on "not master" errors if "safe" is set.
1.0.9

Added "fsync" option.

1.0.5 Added options parameter.

Exemple

Example #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);

?>

Exemplul de mai sus va afișa ceva similar cu:

array(2) {
  ["x"]=>
  int(1)
  ["_id"]=>
  object(MongoId)#4 (1) {
    ["$id"]=>
    string(24) "50b6afe544415ed606000000"
  }
}