# MongoCollection::update

(PECL mongo >=0.9.0)

MongoCollection::update — Update records based on a given criteria

### Description

public MongoCollection::update ( array `$criteria` , array `$new_object` [, array `$options` = array() ] ) : bool|array

### Parameters

`criteria`

  Query criteria for the documents to update.

`new_object`

  The object used to update the matched documents. This may either contain update operators (for modifying specific fields) or be a replacement document.

`options`

  An array of options for the update operation. Currently available options include:

  - `"upsert"`

    If no document matches `$criteria`, a new document will be inserted.

    If a new document would be inserted and `$new_object` contains atomic modifiers (i.e. `$` operators), those operations will be applied to the `$criteria` parameter to create the new document. If `$new_object` does not contain atomic modifiers, it will be used as-is for the inserted document. See the upsert examples below for more information.

  - `"multiple"`

    All documents matching $criteria will be updated. MongoCollection::update() has exactly the opposite behavior of MongoCollection::remove(): it updates one document by default, not all matching documents. It is recommended that you always specify whether you want to update multiple documents or a single document, as the database may change its default behavior at some point in the future.

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

  - `"socketTimeoutMS"`

    This option specifies the time limit, in milliseconds, for socket communication. If the server does not respond within the timeout period, a MongoCursorTimeoutException will be thrown and there will be no way to determine if the server actually handled the write or not. A value of `-1` may be specified to block indefinitely. The default value for MongoClient is `30000` (30 seconds).

  - `"w"`

    See Write Concerns. The default value for MongoClient is `1`.

  - `"wTimeoutMS"`

    This option specifies the time limit, in milliseconds, for write concern acknowledgement. It is only applicable when `"w"` is greater than `1`, as the timeout pertains to replication. If the write concern is not satisfied within the time limit, a MongoCursorException will be thrown. A value of `0` may be specified to block indefinitely. The default value for MongoClient is `10000` (ten seconds).

  The following options are deprecated and should no longer be used:

  - `"safe"`

    Deprecated. Please use the write concern `"w"` option.

  - `"timeout"`

    Deprecated alias for `"socketTimeoutMS"`.

  - `"wtimeout"`

    Deprecated alias for `"wTimeoutMS"`.

### Return Values

Returns an array containing the status of the update if the `"w"` option is set. Otherwise, returns `TRUE`.

Fields in the status array are described in the documentation for MongoCollection::insert().

### Errors/Exceptions

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
--- | ---
PECL mongo 1.5.0 | Added the `"wTimeoutMS"` option, which replaces `"wtimeout"`. Emits `E_DEPRECATED` when `"wtimeout"` is used. Added the `"socketTimeoutMS"` option, which replaces `"timeout"`. Emits `E_DEPRECATED` when `"timeout"` is used. Emits `E_DEPRECATED` when `"safe"` is used.
PECL mongo 1.3.4 | Added `"wtimeout"` option.
PECL mongo 1.3.0 | Added `"w"` option. The `options` parameter no longer accepts a boolean to signify an upsert. Instead, this now has to be done with `array('upsert' => true)`.
PECL mongo 1.2.11 | Emits `E_DEPRECATED` when `options` is scalar.
PECL mongo 1.2.0 | Added `"timeout"` option.
PECL mongo 1.0.11 | Disconnects on "not master" errors if `"safe"` is set.
PECL mongo 1.0.9 | Added ability to pass integers to the `"safe"` option, which previously only accepted booleans. Added `"fsync"` option. The return type was changed to be an array containing error information if the `"safe"` option is used. Otherwise, a boolean is returned as before.
PECL mongo 1.0.5 | Added `"safe"` option.
PECL mongo 1.0.1 | Changed `options` parameter from boolean to array. Pre-1.0.1, the second parameter was an optional boolean value specifying an upsert.

### Examples

Example #1 MongoCollection::update()

Adding an address field to a document.

`<?php
$c->insert(array("firstname" => "Bob", "lastname" => "Jones" ));
$newdata = array('$set' => array("address" => "1 Smith Lane"));
$c->update(array("firstname" => "Bob"), $newdata);
var_dump($c->findOne(array("firstname" => "Bob")));
?>`

The above example will output something similar to:

    array(4) {
      ["_id"]=>
      object(MongoId)#6 (0) {
      }
      ["firstname"]=>
      string(3) "Bob"
      ["lastname"]=>
      string(5) "Jones"
      ["address"]=>
      string(12) "1 Smith Lane"
    }

Example #2 MongoCollection::update() upsert examples

Upserts can simplify code, as a single line can create the document if it does not exist (based on `$criteria`), or update an existing document if it matches.

In the following example, `$new_object` contains an atomic modifier. Since the collection is empty and upsert must insert a new document, it will apply those operations to the `$criteria` parameter in order to create the document.

`<?php
$c->drop();
$c->update(
array("uri" => "/summer_pics"),
array('$inc' => array("page hits" => 1)),
array("upsert" => true)
);
var_dump($c->findOne());
?>`

The above example will output something similar to:

    array(3) {
      ["_id"]=>
      object(MongoId)#9 (0) {
      }
      ["uri"]=>
      string(12) "/summer_pics"
      ["page hits"]=>
      int(1)
    }

If `$new_object` does not contain atomic modifiers (i.e. `$` operators), upsert will use `$new_object` as-is for the new document. This matches the behavior of a normal update, where not using atomic modifiers causes the document to be overwritten.

`<?php
$c->drop();
$c->update(
array("name" => "joe"),
array("username" => "joe312", "createdAt" => new MongoDate()),
array("upsert" => true)
);
var_dump($c->findOne());
?>`

The above example will output something similar to:

    array(3) {
      ["_id"]=>
      object(MongoId)#10 (0) {
      }
      ["username"]=>
      string(6) "joe312"
      ["createdAt"]=>
      object(MongoDate)#4 (0) {
      }
    }

Example #3 MongoCollection::update() multiple example

By default, MongoCollection::update() will only update the first document matching `$criteria` that it finds. Using the "multiple" option can override this behavior, if needed.

This example adds a "gift" field to every person whose birthday is in the next day.

`<?php
$today = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
$people->update(
array("birthday" => $today),
array('$set' => array('gift' => $surprise)),
array("multiple" => true)
);
?>`

### See Also

The PHP documentation on updates and the » MongoDB core docs.