# MongoCollection::insert

(PECL mongo >=0.9.0)

MongoCollection::insert — Inserts a document into the collection

### Description

public MongoCollection::insert ( array|object `$document` [, array `$options` = array() ] ) : bool|array

All strings sent to the database must be UTF-8. If a string is not UTF-8, a MongoException will be thrown. To insert (or query for) a non-UTF-8 string, use MongoBinData.

### Parameters

`document`

  An array or object. 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. This special behavior does not mean that the parameter is passed by reference.

`options`

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

  - `"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 insertion if the `"w"` option is set. Otherwise, returns `TRUE` if the inserted array is not empty (a MongoException will be thrown if the inserted array is empty).

If an array is returned, the following keys may be present:

`ok`

  This should almost always be 1 (unless last_error itself failed).

`err`

  If this field is non-null, an error occurred on the previous operation. If this field is set, it will be a string describing the error that occurred.

`code`

  If a database error occurred, the relevant error code will be passed back to the client.

`errmsg`

  This field is set if something goes wrong with a database command. It is coupled with `ok` being 0. For example, if `w` is set and times out, errmsg will be set to "timed out waiting for slaves" and `ok` will be 0. If this field is set, it will be a string describing the error that occurred.

`n`

  If the last operation was an update, upsert, or a remove, the number of documents affected will be returned. For insert operations, this value is always `0`.

`wtimeout`

  If the previous option timed out waiting for replication.

`waited`

  How long the operation waited before timing out.

`wtime`

  If `w` was set and the operation succeeded, how long it took to replicate to `w` servers.

`upserted`

  If an upsert occurred, this field will contain the new record's `_id` field. For upserts, either this field or `updatedExisting` will be present (unless an error occurred).

`updatedExisting`

  If an upsert updated an existing element, this field will be true. For upserts, either this field or upserted will be present (unless an error occurred).

### 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
--- | ---
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 acknowledged write. Instead, this now has to be done with `array('w' => 1)` (the default behaviour of MongoClient).
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.2 | Changed second parameter to be an array of options. Pre-1.0.2, the second parameter was a boolean indicating the `"safe"` option.
PECL mongo 1.0.1 | Throw a MongoCursorException if the `"safe"` option is set and the insert fails.

### Examples

Example #1 MongoCollection::insert() `_id` example

An `_id` field will be added to the inserted document if not already present. Depending on how the parameter is passed, a generated `_id` may or may not be available to calling code.

`<?php
$m = new MongoClient();
$collection = $m->selectCollection('test', 'phpmanual');
// If an array literal is used, there is no way to access the generated _id
$collection->insert(array('x' => 1));
// The _id is available on an array passed by value
$a = array('x' => 2);
$collection->insert($a);
var_dump($a);
// The _id is not available on an array passed by reference
$b = array('x' => 3);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
// The _id is available if a wrapping function does not trigger copy-on-write
function insert_no_cow($collection, $document)
{
$collection->insert($document);
}
$c = array('x' => 4);
insert_no_cow($collection, $c);
var_dump($c);
// The _id is not available if a wrapping function triggers copy-on-write
function insert_cow($collection, $document)
{
$document['y'] = 1;
$collection->insert($document);
}
$d = array('x' => 5);
insert_cow($collection, $d);
var_dump($d);
?>`

The above example will output something similar to:

    array(2) {
      ["x"]=>
      int(2)
      ["_id"]=>
      object(MongoId)#4 (0) {
      }
    }
    array(1) {
      ["x"]=>
      int(3)
    }
    array(2) {
      ["x"]=>
      int(4)
      ["_id"]=>
      object(MongoId)#5 (0) {
      }
    }
    array(1) {
      ["x"]=>
      int(5)
    }

Example #2 MongoCollection::insert() acknowledged write example

This example shows inserting two elements with the same _id, which causes a MongoCursorException to be thrown, as `w` was set.

`<?php
$person = array("name" => "Joe", "age" => 20);
$collection->insert($person);
// now $person has an _id field, so if we save it
// again, we will get an exception
try {
$collection->insert($person, array("w" => 1));
} catch(MongoCursorException $e) {
echo "Can't save the same person twice!\n";
}
?>`

### See Also

- MongoCollection::batchInsert() - Inserts multiple documents into this collection
- MongoCollection::update() - Update records based on a given criteria
- MongoCollection::find() - Queries this collection, returning a MongoCursor for the result set
- MongoCollection::remove() - Remove records from this collection
- MongoDB core docs on » insert.