MongoCollection::group
MongoCollection::remove
MongoCollection
PHP Manual

# MongoCollection::insert

(PECL mongo >=0.9.0)

MongoCollection::insert — Inserts an array into the collection

### Description

public mixed MongoCollection::insert ( array `$a` [, array `$options` = 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

`a`

  An array.

`options`

  Options for the insert.

  - "safe"

    Check that the insert succeeded.

### Return Values

If `safe` was set, returns an array containing the status of the insert. Otherwise, returns a boolean representing if the array was not empty (an empty array will not be inserted).

### Errors/Exceptions

Throws MongoCursorException if the "safe" option is set and the insert fails. (Version 1.0.1+)

### Changelog

Version | Description
--- | ---
1.0.5 | Changed second parameter to an array of options. Pre-1.0.5, the second parameter was a boolean indicating the "safe" option.

### Examples

Example #1 MongoCollection::insert() _id example

Inserting an object will add an _id field to it, unless it is passed by reference.

`<?php
$a = array('x' => 1);
$collection->insert($a);
var_dump($a)
$b = array('x' => 1);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
?>`

The above example will output something similar to:

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

Example #2 MongoCollection::insert() safe example

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

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

### See Also

MongoDB core docs on » insert.

MongoCollection::group
MongoCollection::remove
MongoCollection
PHP Manual