Saves a document to this collection

MongoCollection::remove
MongoCollection::setReadPreference
MongoCollection
PHP Manual

# MongoCollection::save

(PECL mongo >=0.9.0)

MongoCollection::save — Saves a document to this collection

### Description

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

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

### Parameters

`a`

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

  > Note:

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

    > Note: 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.

    > Note: 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.

  - Integer, defaults to MongoCursor::$timeout. If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.

    "socketTimeoutMS"

  - "w"

    See WriteConcerns. The default value for MongoClient is 1.

  - "wtimeout"

    How long to wait for WriteConcern acknowledgement. The default value for MongoClient is 10000 milliseconds.

    Warning

    Deprecated in favour of the "wTimeoutMS" option

  - "wTimeoutMS"

    How long to wait for WriteConcern acknowledgement. The default value for MongoClient is 10000 milliseconds.

  - "safe"

    Deprecated. Please use the WriteConcern w option.

  - "timeout"

    Integer, defaults to MongoCursor::$timeout. If acknowledged writes are used, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException will be thrown.

    Warning

    Deprecated in favour of the "socketTimeoutMS" option

### Return Values

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

### Errors/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.

### Changelog

Version | Description
--- | ---
1.5.0 | Renamed the "wtimeout" option to "wTimeoutMS".
1.5.0 | Renamed the "timeout" option to "socketTimeoutMS".
1.2.0 | Added "timeout" option.
1.0.11 | Disconnects on "not master" errors if "safe" is set.
1.0.9 | Added ability to pass integers to the "safe" option, which previously only accepted booleans. Added "fsync" option.
1.0.5 | Added `options` parameter.

### Examples

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);
?>`

The above example will output something similar to:

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

MongoCollection::remove
MongoCollection::setReadPreference
MongoCollection
PHP Manual