(PECL mongo >=0.9.0)
MongoCollection::insert — Inserta un documento en la colección
$a
[, array $options = array()
] )Todas las cadenas de texto que se envíen a la base de datos deben estar en UTF-8. Si un string no estuviera en UTF-8, se lanzaría una excepción MongoException. Para insertar (o para consultar) un texto que no sea UTF-8, utilice MongoBinData.
a
Un array u objeto. Si se utiliza un objeto, este no puede tener propiedades protegidas o privadas.
Nota:
Si el parámetro no posee una clave _id o propiedad, se creará una nueva instancia de MongoId y se le asignará. Este comportamiento especial no implica que el parámetro sea pasado por referencia.
options
Opciones para la inserción.
"w"
Véase WriteConcerns. El valor predeterminado de MongoClient es 1.
"fsync"
Booleano, su valor predeterminado es FALSE. Fuerza a la inserción a estar sincronizada con el disco antes de devolver éxito. Si es TRUE, está implicada una inserción declarada y sobrescribirá el ajuste w a 0.
"timeout"
Entero, su valor predeterminado es MongoCursor::$timeout. Si se establece a "safe", establece cuánto espera el cliente (en milisegundos) a un respuesta de la base de datos. Si la base de datos no responde dentro del periodo del tiempo de espera, será lanzada una MongoCursorTimeoutException.
"safe"
Obsoleto. Use la opción w de WriteConcern.
Devuelve un array que contiene el estado de la inserción si la
opción "w" está establecida. De lo contrario, devuelve TRUE si el
array insertado no está vacío (se lanzará una MongoException
si el array insertado está vacío).
Si se devuelve un array, las siguientes claves podrían estar presentes:
ok
Debería ser casi siempre 1 (a menos que last_error falle por sí mismo).
err
Si este campo es diferente de null, un error ocurrido en la operación anterior. Si este campo está establecido, será una cadena describiendo el error que ocurrió.
code
Si ocurrión un error de base de datos, el código de error relevante será devuelto al cliente.
errmsg
Este campo está establecido si algo va mal con un comando de base de datos. Está asociado con ok igual a 0. Por ejemplo, si se establece w y se agota el tiempo, errmsg será establecido a "timed out waiting for slaves" y ok será 0. Si este campo es establecido, será una cadena describiendo el error ocurrido.
n
Si la última operación fue de inserción, una upsert, o una eliminación, será devuelto el número de objetos afectados. Para operaciones de inserción, este valor siempre es 0.
wtimeout
Si la opción anterior agota el tiempo, espera una réplica.
waited
Cuánto esperará la operación antes de agotarse el tiempo.
wtime
Si w fue establecido y la operación tiene éxito, cuánto toma la réplica a los servidores w.
upserted
Si ocurre un upsert, este campo contendrá el nuevo campo _id del registro. Para upserts, estará presente este campo o updatedExisting (a menos que ocurra un error).
updatedExisting
Si un upsert actualiza un elemento existente, este campo será "true". Para upserts, estará presente este campo o upserted (a menos que ocurra un error).
Lanza una excepción de tipo MongoException si el documento insertado está vacío o si contiene claves de longitud cero. Intentar insertar un objeto con propiedades protegidas o privadas causará un error de clave de longitud cero.
Lanza una MongoCursorException si la opción "w" está establecida y la escritura falla.
Lanza una MongoCursorTimeoutException si la opción "w" está establecida a un valor mayor que uno y la operación toma más de MongoCursor::$timeout milisegundos en completarse. Esto no pondrá fin a la operación en el servidor, es un tiempo de espera del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.
| Versión | Descripción |
|---|---|
| 1.3.0 |
El parámetro options ya no acepta un booleano
para indicar una escritura aceptada. En su lugar, ahora esto tiene que hacerse con
array('w' => 1) (El comportamiento predeterminado de
MongoClient).
|
| 1.2.0 | Se añadió el parámetro "timeout". |
| 1.0.11 | Se desconecta en errores "not master" si "safe" está establecido. |
| 1.0.9 |
Añadida la capacidad de pasar enteros a la opción "safe", la cual anteriormente únicamente aceptaba booleanos. Añadida la opción "fsync". Cambiado el tipo devuelto por un array que contiene información si se utiliza la opción "safe". De otro modo, se devuelve un booleano como antes. |
| 1.0.5 | Cambiado el segundo parámetro a un array de opciones. Antes de 1.0.5, el segundo parámetro era un booleano indicando la opción "safe". |
| 1.0.1 | Lanza una MongoCursorException si la opción "safe" está establecida y la inserción falla. |
Ejemplo #1 Ejemplo de MongoCollection::insert() con _id
Un campo _id será añadido al documento insertado si no estuviera ya presente. Dependiendo de cómo el parámetro sea pasado, estará disponible o no un _id generado para llamar al código.
<?php
$m = new MongoClient();
$colección = $m->selectCollection('test', 'phpmanual');
// Si se usa un array literal, no hay forma de acceder al _id generado
$colección->insert(array('x' => 1));
// El _id está disponible en un array pasado por valor
$a = array('x' => 2);
$colección->insert($a);
var_dump($a);
// El _id no está disponible en un array pasado por referencia
$b = array('x' => 3);
$ref = &$b;
$colección->insert($ref);
var_dump($ref);
// El _id está disponible si una función envolvente no desencadena una copia durante la escritura
function insert_no_cow($colección, $documento)
{
$colección->insert($documento);
}
$c = array('x' => 4);
insert_no_cow($colección, $c);
var_dump($c);
// El _id no está disponible si una función envolvente desencadena una copia durante la escritura
function insert_cow($colección, $documento)
{
$documento['y'] = 1;
$colección->insert($documento);
}
$d = array('x' => 5);
insert_cow($colección, $d);
var_dump($d);
?>
El resultado del ejemplo sería algo similar a:
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)
}
Ejemplo #2 Ejemplo de escritura aceptada con MongoCollection::insert()
Este ejemplo muestra cómo al insertar dos elementos con el mismo _id, se provoca
que se lance una excepción MongoCursorException, ya que
w está habilitado.
<?php
$persona = array("nombre" => "Joe", "edad" => 20);
$colección->insert($persona);
// ahora $persona tiene un campo _id, así que si intentamos guardarlo
// de nuevo, obtendremos una excepción
try {
$collection->insert($persona, array("w" => 1));
} catch(MongoCursorException $e) {
echo "No se puede guardar dos veces la misma persona!\n";
}
?>