Driver nativo MongoDB

Manual
Este manual trata algunos detalles sobre cmo usar MongoDB, aunque es ms una referencia del driver PHP. Para ms informacin sobre cmo disear un esquema, qu significa cada trmino, o cmo configurar el servidor de bases de datos, revise la documentacin de MongoDB.

Instalacin
El controlador MongoDB para PHP debe funcionar en cualquier sistema: Windows, Mac OS X, Unix, y Linux; pequeas y grandes mquinas; y plataformas de 32- y 64-bits; PHP 5.1, 5.2, y 5.3. Esta extensin PECL no se distribuye con PHP. Esta pgina proporciona informacin especifica acerca de la instalacin en diferentes sistemas y solucin de problemas que otros usuarios han resuelto.

Instalacin en *NIX Instalacin manual OS X Gentoo Fedora Instalacin en Windows Instrucciones de instalacin de terceros

Instalacin en *NIX
Ejecute:
$ sudo pecl install mongo

Si se est usando CentOS o Redhat, Csoke Arpad ha creado paquetes RPMs para estas distribuciones. Agregar la siguiente lnea en el fichero php.ini:
extension=mongo.so

Si pecl se quedar sin memoria al instalar, asegrese de que memory_limit en php.ini sea de al menos de 32MB.

Instalacin manual
Driver nativo MongoDB 2

Para los desarrolladores de controloladores y gente interesada en las ltimas correcciones, puede compilar el controlador desde las ltimas versiones en Github. Ir a Github y presione en el botn "download". Ejecute:
$ $ $ $ $ tar zxvf mongodb-mongodb-php-driver-<commit_id>.tar.gz cd mongodb-mongodb-php-driver-<commit_id> phpize ./configure sudo make install

Realice los siguientes cambios en php.ini:

Asegrese de que la variable extension_dir este apuntando a la ubicacin de mongo.so. El build se mostrar donde se encuetre instalado el controlador de PHP, la salida ser algo similar a esto:
Installing '/usr/lib/php/extensions/no-debug-zts-20060613/mongo.so'

Asegrese de que este en el mismo directorio en donde PHP se encuentre, ejecute:

$ php -i | grep extension_dir extension_dir => /usr/lib/php/extensions/no-debug-zts-20060613 => /usr/lib/php/extensions/no-debug-zts-20060613

Si no es as, cambia extension_dir en php.ini o mueva mongo.so Para cargar la extensin en el arranque de PHP, agregar una lnea:
extension=mongo.so

OS X
Si su sistema no puede encontrar autoconf, necesitas instalar Xcode (disponible en el DVD de instalacin). Si usa XAMPP, debe compilar el driver con el siguiente comando:
sudo /Applications/XAMPP/xamppfiles/bin/pecl install mongo

Si usa MAMP ( o XAMPP y el comando anterior no funciona), los binarios precompilados estn disponibles en Github (descargue la ltima versin con "osx" junto con el nombre que corresponda a la versin de PHP). Extraer mongo.so desde el fichero y aadalo al directorio de extensiones de MAMP o XAMPP. Agregar
extension=mongo.so

al fichero php.ini y reinicie el servidor.

Gentoo
Gentoo tiene un paquete para el driver de PHP que se llama dev-php5/mongo que puede ser instalado con:
$ sudo emerge -va dev-php5/mongo

Si se utiliza PECL, quiz obtiene un error de versin incorrecta en libtool. Compile desde las fuentes que necesite y ejecute aclocal y autoconf. Driver nativo MongoDB 3

$ phpize && aclocal && autoconf && ./configure && make && make install

Red Hat
Incluye Fedora y CentOS En estos sistemas, la configuracin por omisin de Apache no permite a las peticiones establecer conexiones de red, haciendo que el driver genere errores de "Permiso denegado" cuando se intenta conectar a la base de datos. Si este fuera el caso, pruebe a ejecutar:
$ /usr/sbin/setsebool -P httpd_can_network_connect 1

Y finalmente reinicie Apache. (Este comportamiento tambin se da con SELinux.)

Instalacin en Windows
Los binarios precompilados para cada versin estn disponibles en Github para una gran variedad de combinaciones de versiones, seguridad en hilos, y bibliotecas VC. Descomprima el fichero y copie php_mongo.dll en el directorio de extensiones de PHP ("ext" por omisin). El ltimo (no publicado) cdigo se compila en archivos binarios en Windows en cada commit. El fichero zip cuenta los ficheros php_mongo.dll y version.txt. Por favor mantega el fichero version.txt de modo que si presenta una pregunta o problema, pueda proporcionar a los desarrolladores la versin exacta en uso. (El nmero es largo y sin sentido, pero tendr sentido para los desarrolladores) Para obtener las ltimas correcciones (y posiblemente errores), descargue el binario correspondiente a la versin instalada de PHP:

PHP 5.2 VC6 Non-Thread-Safe Mongo extension PHP 5.2 VC6 Thread-Safe Mongo extension PHP 5.3 VC6 Non-Thread-Safe Mongo extension PHP 5.3 VC6 Thread-Safe Mongo extension PHP 5.3 VC8 Non-Thread-Safe Mongo extension PHP 5.3 VC8 Thread-Safe Mongo extension PHP 5.3 VC9 Non-Thread-Safe Mongo extension PHP 5.3 VC9 Thread-Safe Mongo extension Agregar la siguiente lnea al fichero php.ini:
extension=php_mongo.dll

Instrucciones de instalacin de terceros

Driver nativo MongoDB

Un gran nmero de personas han creado excelentes tutoriales de instalacin de controlador de PHP.

PHP 5.3.1 con Xdebug, MongoDB y Lithium en Ubuntu 9.10 / Apache 2.2 Un excelente video que te llevar paso a paso en la instalacin de Apache, PHP, Xdebug, MongoDB, y Lithium por Jon Adams. Instalando MongoDB y el controlador de PHP en Ubuntu 9.04 Artculo en castellano por Javier Aranda ( Traduccin en ingls ). OS X: Instalando MongoDB y el controlador de PHP Por Matt Butcher.

Tutorial Introduccin
Gracias al driver de PHP para MongoDB de 10gen. Cdigo de ejemplo para conectar, insertar documentos, consultar documentos, recorrer el resultado de una consulta, y desconectar de MongoDB. Encontrar ms detalles en cada uno de los pasos del siguiente tutorial.
<?php // conectar $m = new Mongo(); // seleccionar una base de datos $db = $m->comedy; // seleccionar una coleccin (equivalente a una tabla en una base de datos relacional) $collection = $db->cartoons; // aadir un registro $obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" ); $collection->insert($obj); // aadir un nuevo registro, con un distinto "perfil" $obj = array( "title" => "XKCD", "online" => true ); $collection->insert($obj); // encontrar todo lo que haya en la coleccin $cursor = $collection->find(); // recorrer el resultado foreach ($cursor as $obj) { echo $obj["title"] . "\n"; } ?>

Mostrar: Driver nativo MongoDB 5

Calvin and Hobbes XKCD

Estableciendo una Conexin

Para conectar al servidor de bases de datos, utilice alguna de las siguientes formas:
<?php $connection = new Mongo(); // conecta a localhost:27017 $connection = new Mongo( "example.com" ); // conecta a un host remoto (puerto por omisin: 27017) $connection = new Mongo( "example.com:65432" ); // conecta a un host remoto en el puerto facilitado ?>

No es necesario desconectar explcitamente de la base de datos. Cuando $connection queda fuera de mbito, la conexin se cierra automticamente y todos sus recursos se liberan.

Ver tambin
El captulo connecting cubre los distintos tipos de conexiones. Tanto la documentacin de la API de la clase Mongo como Mongo::__construct() proporcionan un exhaustivo repaso a todas las opciones disponibles, y un gran nmero de ejemplos.

Obteniendo una Base de Datos

Para seleccionar una base de datos, utilice.
<?php $db = $connection->dbname; ?>

La base de datos no debe necesariamente haber sido ya creada, sino que pueden crearse con slo seleccionarlas. Tenga cuidado con los errores tipogrficos! Podra, por inadvertencia, crear una nueva base de datos, provocando errores:
<?php $db = $connection->mybiglongdbname; // hacemos algo $db = $connection->mybiglongdbname; // ahora estamos conectando a una nueva base de datos! ?>

Driver nativo MongoDB

Ver Tambin
La documentacin API de la clase MongoDB contiene ms informacin sobre los objetos de bases de datos.

Obteniendo Una Coleccin

Para obtener una conexin se utiliza la misma sintaxis que para obtener una base de datos:
<?php $db = $connection->baz; $collection = $db->foobar; // o de forma resumida: $collection = $connection->baz->foobar; ?>

Las colecciones son anlogos a las tablas (para aqullos que estn familiarizados con bases de datos relacionales).

Ver Tambin
La documentacin API de la clase MongoCollection contiene ms informacin sobre objetos de colecciones.

Insertando un Documento
Los objetos bsicos para almacenar en una coleccin de una base de datos son los arrays asociativos. Un "documento" cualquiera podra ser:
<?php $doc = array( "nombre" => "MongoDB", "tipo" => "database", "contador" => 1, "info" => (object)array( "x" => 203, "y" => 102), "versiones" => array("0.9.7", "0.9.8", "0.9.9") ); ?>

Tenga en cuenta que puede tener array y objetos anidados. Para insertar este documento, utilice MongoCollection::insert():
<?php $collection->insert( $doc );

Driver nativo MongoDB

?>

Ver Tambin
La documentacin API de MongoCollection::insert() contiene ms informacin sobre la insercin de datos.

Localizando documentos usando MongoCollection::findOne()

Para comprobar que el documento que insertamos en el paso anterior se encuentra ah, podemos realizar una operacin MongoCollection::findOne() para obtener un nico documento de la coleccin. Este mtodo es til cuando slo hay un documento que concuerde con la consulta, o cuando slo se est interesado en un resultado.
<?php $obj = $collection->findOne(); var_dump( $obj ); ?>

Mostrar:
array(6) { ["_id"]=> object(MongoId)#8 (1) { ["$id"]=> string(24) "4e2995576803fab768000000" } ["nombre"] string(7) "MongoDB" ["tipo"]=> string(8) "database" ["contador"]=> int(1) ["info"]=> array(2) { ["x"]=> int(203) ["y"]=> int(102) } ["versiones"]=> array(3) { [0]=> string(5) "0.9.7" [1]=> string(5) "0.9.8" [2]=> string(5) "0.9.9" } }

Hay un campo _id que se ha aadido automticamente al documento. _id es el campo de Driver nativo MongoDB 8

la "clave primaria". Si el documento no especifica una, el driver la aadir automticamente. Si se ha especificado un campo _id, debe ser nico en toda la coleccin. Por ejemplo:
<?php $db->foo->insert(array("_id" => 1), array("safe" => true)); // esto emitir una excepcin $db->foo->insert(array("_id" => 1), array("safe" => true)); // aqu no habra problemas, ya que es otra coleccin $db->bar->insert(array("_id" => 1), array("safe" => true)); ?>

Tenga en cuenta que estas inserciones proporcionan un segundo array: array("safe" => true). Este campo especifica las opciones de insercin. Por omisin, el driver no espera para escribir a que la base de datos responda, por lo que el driver no capturara el _id. Como se ha especificado una escritura "safe" (segura), el driver esperar la respuesta de la base de datos y ver que la escritura no se ha llevado a cabo. En general, todas las escrituras deben usar la opcin "safe" (en los ejemplos anteriores se ha omitido para simplificarlos).

Ver Tambin
MongoCollection::findOne() contiene ms informacin sobre cmo localizar datos. MongoId ofrece ms detalles de los identificadores nicos. La seccin writes trata las escrituras seguras en mayor profundidad, as como las funciones de escritura como MongoCollection::insert(), MongoCollection::update(), o MongoCollection::remove().

Aadiendo Mltiples Documentos

Para hacer ms interesante el tema de las consultas, vamos a aadir varios documentos a la coleccin. Estos documentos sern simplemente de la forma array( "i" => value ); y podemos hacerlo de un modo muy eficiente en un bucle:
<?php for($i=0; $i<100; $i++) { $collection->insert( array( "i" => $i ) ); } ?>

Tenga en cuenta que podemos insertar en una misma coleccin arrays con conjuntos de claves diferente. A esta caracterstica nos refereemos cuando decimos que MongoDB es independiente de esquemas.

Driver nativo MongoDB

Contando los Documentos de una Coleccin

Ahora que hemos insertado 101 documentos (los 100 del bucle, junto con el primero), podemos comprobar si los tenemos todos usando el mtodo MongoCollection::count().
<?php echo $collection->count(); ?>

y debe mostrar 101.

Usando un Cursor para Obtener Todo de los Documentos

Paraa obtener todos los documentos, usaremos MongoCollection::find(). El mtodo find() devuelve un objeto MongoCursor que nos permite recorrer el conjunto de documentos que concuerdan con nuestra consulta. De ese modo, para consultar todos los documentos y mostrarlos por pantalla:
<?php $cursor = $collection->find(); foreach ($cursor as $id => $value) { echo "$id: "; var_dump( $value ); } ?>

y mostrar los 101 documentos de la coleccin. $id es el campo _id del documento (transformado a string) y $value es el documento en s.

Ver Tambin
La documentacin API de MongoCollection::find() contiene ms informacin sobre cmo localizar datos.

Estableciendo el Criterio de la Consulta

Podemos crear una consulta para pasar al mtodo MongoCollection::find() y as obtener un subconjunto de documentos de nuestra coleccin. Por ejemplo, si quisiramos encontrar el documento cuyo valor en el campo "i" es 71, haramos lo siguiente:
<?php $query = array( "i" => 71 ); $cursor = $collection->find( $query ); while( $cursor->hasNext() ) { var_dump( $cursor->getNext() ); } ?>

Driver nativo MongoDB

10

y debera mostrar un nico documento

array(2) { ["_id"]=> object(MongoId)#6 (0) { } ["i"]=> int(71) ["_ns"]=> "testCollection" }

Consultando un Conjunto de Documentos con una Consulta

Podemos usar la consulta para obtener un conjunto de documentos de nuestra coleccin. Por ejemplo, si quisiramos obtener todos los documentos en los que "i" > 50, podramos poner:
<?php $query = array( "i" => array( '$gt' => 50 ) ); //fjese en las comillas simples de '$gt' $cursor = $coll->find( $query ); while( $cursor->hasNext() ) { var_dump( $cursor->getNext() ); } ?>

lo cual mostrara los documentos en que i > 50. Podemos tambin consultar un rango, digamos 20 < i <= 30:
<?php $query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) ); $cursor = $coll->find( $query ); while( $cursor->hasNext() ) { var_dump( $cursor->getNext() ); } ?>

Recuerde escapar siempre el smbolo $ o utilizar comillas simples. Si no, PHP lo interpretar como la variable $gt.

Creando un ndice
MongoDB soporta ndices, y es muy fcil aadirlos a una coleccin. Para crear un ndice, debe indicar el nombre del campo y la direccin: ascendente (1) o descendente (-1). A continuacin, creamos un ndice ascendente en el campo "i":
<?php

Driver nativo MongoDB

11

$coll->ensureIndex( array( "i" => 1 ) ); // creamos un ndice en "i" $coll->ensureIndex( array( "i" => -1, "j" => 1 ) ); // ndice de "i" descendente, "j" ascendente ?>

A medida que los datos crecen, la indexacin se vuelve crtica para un buen rendimiento de lectura. Si no est familiarizado con las indexaciones, revise la documentacin de MongoCollection::ensureIndex() y l a documentacin de indexacin de MongoDB.

Tabla de correlacin de SQL a Mongo

Esta es una versin especfica de PHP de la tabla de correlacin de SQL a Mongo de la documentacin principal.

Sentencia SQL

Sentencia en el Lenguaje de Consulta Mongo Implcito, o utilice MongoDB::createCollection(). $db->users->insert(array("a" => 1, "b" => 1)); $db->users->find(array(), array("a" => 1, "b" => 1)); $db->users->find(array("age" => 33));

CREATE TABLE USERS (a Number, b Number) INSERT INTO USERS VALUES(1,1)

SELECT a,b FROM users

SELECT * FROM users WHERE age=33

SELECT a,b FROM users WHERE age=33 $db->users->find(array("age" => 33), array("a" => 1, "b" => 1)); SELECT a,b FROM users WHERE age=33 $db->users->find(array("age" => 33), array("a" => 1, "b" => 1)); SELECT a,b FROM users WHERE age=33 $db->users->find(array("age" => 33), ORDER BY name array("a" => 1, "b" => 1))->sort(array("name" => 1)); SELECT * FROM users WHERE age>33 $db->users->find(array("age" => array('$gt' => 33))); $db->users->find(array("age" => array('$lt' => 33)));

SELECT * FROM users WHERE age<33

SELECT * FROM users WHERE name LIKE $db->users->find(array("name" => new "%Joe%" MongoRegex("/Joe/")));

Driver nativo MongoDB

12

SELECT * FROM users WHERE name LIKE $db->users->find(array("name" => new "Joe%" MongoRegex("/^Joe/"))); SELECT * FROM users WHERE age>33 AND age<=40 SELECT * FROM users ORDER BY name DESC CREATE INDEX myindexname ON users(name) CREATE INDEX myindexname ON users(name,ts DESC) SELECT * FROM users WHERE a=1 and b='q' SELECT * FROM users LIMIT 10 SKIP 20 $db->users->find(array("age" => array('$gt' => 33, '$lte' => 40))); $db->users->find()->sort(array("name" => -1)); $db->users->ensureIndex(array("name" => 1)); $db->users->ensureIndex(array("name" => 1, "ts" => -1)); $db->users->find(array("a" => 1, "b" => "q")); $db->users->find()->limit(10)->skip(20);

SELECT * FROM users WHERE a=1 or b=2 $db->users->find(array('$or' => array(array("a" => 1), array("b" => 2)))); SELECT * FROM users LIMIT 1 EXPLAIN SELECT * FROM users WHERE z=3 $db->users->find()->limit(1); $db->users->find(array("z" => 3))->explain()

SELECT DISTINCT last_name FROM users $db->command(array("distinct" => "users", "key" => "last_name")); SELECT COUNT(*y) FROM users SELECT COUNT(*y) FROM users where AGE > 30 SELECT COUNT(AGE) from users $db->users->count(); $db->users->find(array("age" => array('$gt' => 30)))->count(); $db->users->find(array("age" => array('$exists' => true)))->count(); $db->users->update(array("b" => "q"), array('$set' => array("a" => 1))); $db->users->update(array("b" => "q"), array('$inc => array("a" => 2))); $db->users->remove(array("z" => "abc"));

UPDATE users SET a=1 WHERE b='q'

UPDATE users SET a=a+2 WHERE b='q'

DELETE FROM users WHERE z="abc"

Conexin
Driver nativo MongoDB 13

La Conexin a MongoDB es tan fcil como usar new Mongo, pero hay muchas ms opciones y configuraciones adicionales. La pgina Mongo::__construct() cubre todas las opciones del API, pero est pgina ofrece ms detalles y consejos para casos de uso prcticos.

Acceso a la conexin
Si MongoDB se inicia con la opcin --auth, las conexiones deben ser autenticadas antes de ser usadas. Se puede hacer a nivel de cada base de datos con MongoDB::authenticate():
<?php $m = new Mongo(); $db = $m->admin; $db->authenticate($username, $password); ?>

Hay una gran desventaja al usar este mtodo: si la conexin a la base de datos se cae y luego se reconecta, la conexin ya no estar autentificada. Si se utiliza la forma de conexin mediante cadena, como se describe en Mongo::__construct(), la base de datos se autentificar al conectarse y se autentificar de nuevo si la conexin se cae y se restablece. Hace lo mismo que el cdigo anterior, a excepcin que las reconexiones a la base de datos sern automticamente autentificadas:
<?php $m = new Mongo("mongodb://${username}:${password}@localhost"); ?>

Por omisin, el controlador autentificar al usuario en la base de datos. Para autentificarse con diferentes base de datos, se especifica el nombre de la base de datos despus del host. Este ejemplo iniciar la sesin al usuario en la base de datos "blog":
<?php $m = new Mongo("mongodb://${username}:${password}@localhost/blog"); ?>

Grupos replica
Para conectarse a un grupo rplica, se debe especificar uno o ms miembros del grupo usando la opcin replicaSet.
<?php

Driver nativo MongoDB

14

$m = new Mongo("mongodb://localhost:27017", array("replicaSet" => true)); ?>

Se require la versin 1.0.9+ del driver para conectar a un grupo rplica (versiones anteriores del driver no auto-detectarn el master o no se reconectarn correctamente). El driver de PHP har una peticin a los servidor(es) de base de datos listados para descubrir cual es el master. Mientras se pueda conectar almenos a uno de los servidores listados y pueda encontrar el master, la conexin se establecer con xito. Si no se puede realizar una conexin a ninguno de los servidores listados o no puede encontrar el master, MongoConnectionException devolver una excepcin. Si el master no se encuentra disponible, los slaves no promocionarn un nuevo master por algunos segundos. Durante ese tiempo, el controlador no podr realizar ninguna operacin en la base de datos (excepto las conexiones a los slaves que seguirn disponibles para operaciones de lectura) Por lo tanto, si se intenta hacer cualquier tipo de consulta de lectura o escritura mientras esto suceda, se devolver una excepcin. Una vez el master es elegido, al realizar una lectura o escritura el driver detectar cual es el nuevo master. Establecer la conexin como como primaria y continuar operando normalmente. Para obtener ms informacin acerca de grupos replica, consulte la documentacin del ncleo.

Connexiones persistentes
Crear una nueva conexin cada vez a la base de datos es muy lento. Para minimizar el nmero de conexiones que se necesite, se pueden usar las conexiones persistentes. Una conexin persistente es guardada por PHP, para que pueda usarse la misma conexin en mltiples peticiones. Por ejemplo, este simple programa para conectarse 1000 veces a la base de datos:
<?php for ($i=0; $i<1000; $i++) { $m = new Mongo(); } ?>

Esto tarda aprximadamente 18 segundos en ejecutarse. Pero si lo cambiamos para que utilice una conexin persistente:
<?php for ($i=0; $i<1000; $i++) { $m = new Mongo("localhost:27017", array("persist" => "x")); }

Driver nativo MongoDB

15

?>

...tardar menos de 0.02 segundos en ejecutarse, ya que solo se realiza una sola conexin a la base de datos. Las conexiones persistentes necesitan indicarse usando la variable de identificacin (tal y como se muestra "x" en el ejemplo anterior). Para que la conexin persistente pueda usarse, el hostname, puerto, variable persist y el usuario y contrasea (si es necesario) debe coincidir con una conexin persistente ya existente. De lo contrario, se crear una nueva conexin los datos proporcionados. Las conexiones persistentes son altamente recomendables y se deberan usar siempre en produccin a no ser que exista una razn con fundamento para hacer lo contrario. La mayora de razones por las cuales no son recomendadas para bases de datos relacionales son totalmente irrelevantes para MongoDB. Las conexiones persistentes sern el tipo de conexin por omisin en 1.0.12. Para crear conexiones no persistentes, se deber pasar "persist" => false a Mongo::__construct().

Soporte de Domain Socket

Si se est ejecutando MongoDB en local con la versin 1.0.9 o superior del driver, se puede conectar a la base de datos va fichero. MongoDB automticamente abre un fichero socket al iniciarse: /tmp/mongodb-<port>.sock. Para conectarse al fichero socket, especifique la ruta de la conexin MongoDB:
<?php $m = new Mongo("mongodb:///tmp/mongo-27017.sock"); ?>

Si se quiere utilizar autenticacin en la conexin (tal y como se indica ms arriba) usando un fichero socket, se debe especificar el puerto 0 para que el analizador de la cadena de conexin sepa donde acaba la cadena de conexin.
<?php $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); ?>

Escrituras Operaciones Seguras

Por omisin, el driver no espera a que la base de datos responda para realizar las escrituras (inserciones, actualizaciones, y eliminacioens). Esto significa que las escrituras pueden llevars a cabo extremadamente rpido, pero no puede saberse si realmente han Driver nativo MongoDB 16

tenido o no xito. Existen varias razones para que una escritura falle: si hay problemas de red, si el servidor de bases de datos se cae, o simplemente que la escritura era invlida (p.ej., escribir en una coleccin del sistema). Para obtener una respuesta de la base de datos, utilice la opcin safe, disponible en todos los tipos de escritura. Esta opcin se asegura de que la base de datos realiza la escritura antes de notificar del xito. Si la escritura falla, emitir una excepcin MongoCursorException(), explicando la razn del fallo. Durante la etapa de desarrollo, deben usarse siempre escrituras seguras (para prevenir errores involuntarios, como errores de claves duplicadas y similares). En el entorno de produccin, pueden usarse escrituras no seguras sobre datos "no importantes". Los datos no importantes dependen de la aplicacin, pero se suele tratar de datos automticos (en lugar de datos generados por el usuario), como un contador de clics o las coordenadas GPS, donde se puede obtener miles de registros por segundo. Para llevar a cabo escrituras seguras sin que ello suponga un impacto en el rendimiento, se recomienda realizar la escritura segura al finalizar una serie de escrituras. Por ejemplo:
$collection->insert($someDoc); $collection->update($criteria, $newObj); $collection->insert($somethingElse); $collection->remove($something, array("safe" => true));

De este modo, si la ltima escritura lanza una excepcin, sabr que hay un problema con la base de datos. Hay ms opciones disponible para asegurar la seguridad de las escrituras. Puede especificarse "fsync" => true para forzar a la base de datos a fsync (sincronizar) todas las escrituras en disco realizadas hasta ahora (por omisin, MongoDB sincroniza en disco las escrituras una vez por minuto). La forma ms segura de realizar una escritura consiste en usar rplicas y en especificar el nmero de servidores en que se harn las escrituras antes de obtener el xito. (En produccin siempre deben usarse rplicas, revise la seccin de Conexin para ms informacin sobre conjuntos de rplicas.)
$collection->insert($someDoc, array("safe" => 3));

Si indica "safe" => N, el servidor MongoDB se asegurar de que al menos N servidores tienen una copia de la escritura antes de notificar el xito. De modo que, si N es 3, el maestro y al menos 2 esclavos deben haber realizado las escrituras.

Actualizando Objetos Anidados

Supogamos que queremos cambiar el nombre del autor de un comentario en este documento:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "content" : "this is a blog post.", "comments" : [

Driver nativo MongoDB

17

{ "author" : "Mike", "comment" : "I think that blah blah blah...", }, { "author" : "John", "comment" : "I disagree." } ] }

Para cambiar un campo interno, usamos $set (de manera que el resto de campos no se eliminen) con el ndice del comentario a cambiar:
<?php $blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim")))); ?>

El Operador Posicional
El operador posicional $es til a la hora de actualizar objetos en arrays. En el ejemplo anterior, por ejemplo, podramos no conocer el ndice del comentario que necesitamos modificar, slo sabemos que queremos cambiar "John" a "Jim". Podemos usar $para lograrlo.
<?php $blog->update( array("comments.author" => "John"), array('$set' => array('comments.$.author' => "Jim"))); ?>

Consultas Distribuyendo consultas a esclavos

Nota 1.1.0+ Si se est utilizando un conjunto de rplicas y un driver versin 1.1.0 o superior, ste puede hacer que senven las consultas automticamente a los esclavos. Este comportamiento no existe en las versiones anteriores del driver y no puede ser usado en un maestro-esclavo "normal".

Por omisin, el driver enviar todas las consultas al maestro. Si se habilita la opcin "slaveOkay", el driver enviar todas las consultas a un servidor no primario, siempre y Driver nativo MongoDB 18

cuando fuera posible. La opcin "slaveOkay" puede habilitarse a cualquier "nivel": conexin, base de datos, coleccin, y cursor. Cada clase hereda el ajuste "slaveOkay" de su clase superior, de modo que si hiciramos:
<?php $db->setSlaveOkay(true); $c = $db->myCollection; $cursor = $c->find(); ?>

la consulta se ejecutara contra un esclavo (la coleccin hereda "slaveOkay" de la base de datos y el cursor lo hereda de la coleccin).

Cmo se escogen los esclavos

Cada instancia de Mongo escoge su propio esclavo utilizando el esclavo disponible con el menor tiempo de respuesta. Es decir, si tuviramos un cliente PHP en Europa y otro en Australia y tuviramos un secundario en cada uno de estos centros de datos, podramos:
<?php // P es el primario // en el cliente de Australia $m1 = new Mongo("mongodb://P", array("replicaSet" => true)); $m1->foo->bar->find()->slaveOkay()->getNext(); echo "el esclavo de m1 es ".$m1->getSlave()."\n"; // en el cliente de Europa $m2 = new Mongo("mongodb://P", array("replicaSet" => true)); $m2->foo->bar->find()->slaveOkay()->getNext(); echo "el esclavo de m2 es ".$m2->getSlave()."\n"; ?>

probablemente se termine con algo as:

el esclavo de m1 es: australianHost el esclavo de m2 es: europeanHost

Tenga en cuenta que se debe realiza una consulta antes de elegir un esclavo: los esclavos se eligen de forma tarda por el driver. Mongo::getSlave() devolver NULL hasta que se utilice un esclavo. Puede consultarse el estado actual del conjunto de miembros que ve el servidor ejecutando Mongo::getHosts(). Si no pudiera leerse ningun servidor no primario, el driver enviara la lectura al primario (incluso con "slaveOkay" habilitado). Un servidor se considera legible si su estado es 2 (SECONDARY) y su salud es 1. Puede comprobarse esto con Mongo::getHosts(). Driver nativo MongoDB 19

Si disfruta tocando botones que probablemente no debera tocar, puede solicitar al driver un nuevo esclavo usando Mongo::switchSlave(). Esto escogera un nuevo esclavo (si hubiera alguno disponible), pero no debera usarse salvo que se sepa bien qu se est haciendo.

Notas aleatorias
Las escrituras siempre se envian al primario. Los comandos de la base de datos, incluso los comandos de slo lectura, tambin se envan siempre al primario. La salud y estado de un esclavo se comprueba cada 5 secundos o al realizarse la siguiente operacin antes de que venzan los 5 segundos. Tambin se volver a comprobar la configuracin cuando el driver tenga problemas accediendo a algn servidor. Tenga en cuenta que un servidor no primario podra encontrarse detrs de un primario en las operaciones, por lo que su software deber tolerar datos "desfasados" (o si no tendr que usar w en todas las escrituras).

Consultando por _id

A cada objeto que se inserta se le asigna automticamente un campo _id nico, a menudo til para usar en consultas. Supongamos que queremos localizar el documento que acabamos de insertar. Las inserciones aaden un campo _id al documento, de modo que podemos consultar en base a l:
<?php $person = array("name" => "joe"); $people->insert($person); // ahora $joe tiene un campo _id $joe = $people->findOne(array("_id" => $person['_id'])); ?>

Salvo que se indique lo contrario, el campo _id ser de tipo MongoId. El error ms frecuente consiste en usar una cadena de texto que concuerde con un MongoId. Debe tenerse presente que son dos tipos de datos distintos, y no concuerdan, del mismo modo que el texto "array()" no es lo mismo que un array vaco. Por ejemplo:
<?php $person = array("name" => "joe"); $people->insert($person); // convertimos el _id a texto $pid = $person['_id'] . "";

Driver nativo MongoDB

20

// FALLO - $pid es un texto, no un MongoId $joe = $people->findOne(array("_id" => $pid)); ?>

Arrays
Los arrays son especiales por varias razones. En primer lugar, hay dos tipos de arrays que MongoDB utiliza: arrays "normales" y arrays asociativos. Los arrays asociativos pueden tener cualquier combinacin de claves y valores. Los arrays "normales" se definen como arrays con un ndice numrico ascendente que comienza por 0 y se incrementa en uno por cada elemento. Estos son, normalmente, los arrays de PHP ms comunes. Por ejemplo, si se quisiera guardar una lista de premios en un documento, podramos poner:
<?php $collection->save(array("awards" => array("gold", "silver", "bronze"))); ?>

Las consultas pueden llegar hasta los arrays en busca de elementos. Supongamos que queremos encontrar todos los documentos que contienen un elemento de un array con un determinado valor. Por ejemplo, documentos con un premio "gold", como por ejemplo:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", "bronze"]}

Esto puede lograrse con una nica consulta, ignorando el hecho de que "awards" es un array:
<?php $cursor = $collection->find(array("awards" => "gold")); ?>

Supongamos que estamos consultando un objeto ms complejo, si cada elemento del array fuera un objeto en s mismo, como en:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : [ { "first place" : "gold" }, { "second place" : "silver" }, { "third place" : "bronze" }

Driver nativo MongoDB

21

] }

Incluso aqu, ignorando que se trata de un array, podemos usar la misma notacin para consultar al subobjeto:
<?php $cursor = $collection->find(array("awards.first place" => "gold")); ?>

Debe tenerse en cuenta que no importa que haya espacios en los nombres de campos (pese a que sea mejor no usarlos, slo por mantenerlo ms legible). Puede tambin usarse un array para consultar un determinado nmero de posibles valores. Por ejemplo, si buscramos documentos "gold" o "copper", podramos hacer:
<?php $cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper")))); ?>

Actualizaciones
Las actualizaciones quizs sean las operaciones ms complicadas de las disponibles en MongoDB. Combinan una consulta junto con una accin, modificando los documentos que concuerdan con los criterios de seleccin. Son tambin muy potentes, permitiendo cambiar rpidamente los documentos y reemplazarlos. Se realiza al momento (siempre y cuando sea posible), minimizando el consumo de recursos.

Modificacin o reemplazo de documentos

Existen dos tipos de actualizaciones: actualizaciones de modificacin y actualizaciones de reemplazado. Las actualizaciones de modificacin contienen operandos $ y cambian los campos de un documento: pueden incrementar contadores, agregar elementos a un array, o modificar el tipo de dato de un campo. Por ejemplo, una actualizacin de modificacin puede aadir un nuevo campo a un documento.
/** supongamos un documento as: * {"username" : "...", "password" : "...", "email" : "..."} */ $coll->update(array("username" => "joe"), array('$set' => array("twitter" => "@joe4153"))); /** ahora el documento sera as: * {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"} */

Driver nativo MongoDB

22

Las actualizaciones de reemplazado modifican todo el documento seleccionado por otro nuevo. Generalmente no es tan eficientes como usar operandos $, pero pueden ser muy tiles en operaciones complejas o en actualizaciones que no se pueden expresar en trminos de operandos $. Por ejemplo, una actualizacin de reemplazado puede cambiar por completo la estructura de un documento.
/** supongamos un documento as: * {"username" : "...", "password" : "...", "email" : "..."} */ $coll->update(array("username" => "joe"), array("userId" => 12345, "info" => array( "name" => "joe", "twitter" => "@joe4153", "email" => "..."), "likes" => array())); /** ahora el documento quedara as: * { * "userId" : 12345, * "info" : { * "name" : "joe", * "twitter" : "@joe4153", * "email" : "..." * }, * "likes" : [] * } */

Actualizando Objetos Anidados

Supongamos que queremos cambiar el nombre del autor de un comentario en este documento:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "content" : "this is a blog post.", "comments" : [ { "author" : "Mike", "comment" : "I think that blah blah blah...", }, { "author" : "John", "comment" : "I disagree." } ] }

Para cambiar el campo interno, usamos $set (de manera que no se eliminen el resto de campos) con el ndice del comentario a cambiar:
<?php $blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim")))); ?>

Driver nativo MongoDB

23

El Operador Posicional
El operador posicional $es til a la hora de actualizar objetos en arrays. En el ejemplo anterior, por ejemplo, podramos no conocer el ndice del comentario que necesitamos modificar, slo sabemos que queremos cambiar "John" a "Jim". Podemos usar $para lograrlo.
<?php $blog->update( array("comments.author" => "John"), array('$set' => array('comments.$.author' => "Jim"))); ?>

Opciones en php.ini
El comportamiento de estas funciones se ve afectado por la configuracin de php.ini.

Opciones de configuracin Mongo Nombre mongo.native_long mongo.long_as_object mongo.default_host mongo.default_port mongo.auto_reconnect mongo.allow_persistent mongo.chunk_size mongo.cmd mongo.utf8 mongo.allow_empty_keys Por defecto false * false "localhost" 27017 true true 262144 "$" "1" false Cambiable PHP_INI_ALL PHP_INI_ALL PHP_INI_ALL PHP_INI_ALL PHP_INI_SYSTEM PHP_INI_SYSTEM PHP_INI_SYSTEM PHP_INI_ALL PHP_INI_ALL PHP_INI_ALL

Para mayor detalles y definiciones de los modos de PHP_INI_*, vea D&oacute;nde realizar un ajuste de configuraci&oacute;n. He aqu una breve explicacin de las directivas de configuracin.

Driver nativo MongoDB

24

mongo.native-long

int Este valor por omisin cambiar a TRUE en 2.0.0, por lo que deber asegurarse al establecer el valor deseado (probablemente TRUE ) de manera que el comportamiento del driver no se vea afectado al actualizar. En plataformas de 64 bits, el ajuste mongo.native_long permite almacenar enteros de 64 bits en MongoDB. Si no se habilitara, slo se podrn almacenar enteros de 32 bits. El tipo de dato MongoDB usado en este caso es el BSON LONG, en lugar del BSON INT, que es el que funciona cuando se deshabilita este ajuste. Este ajuste tambin cambia el modo en que los BSON LONG se comportan cuando se consultan en MongoDB. Cuando mongo.native_long no est habilitado, el driver convierte todos los BSON LONG al tipo double de PHP, por lo que podra provocar prdida de precisin. En plataformas de 32 bits, el ajuste mongo.native_log no tiene efecto al almacenar enteros en MongoDB: los enteros se almacenan como BSON INT. Sin embargo, cuando este ajuste est habilitado y se consulta un BSON LONG en MongDB, se emitir una excepcin MongoCursorException alertando de que no se puede evitar la prdida de precisin en la lectura. Se recomienda que, en sistemas de 32 bits, adems de esto se habilite mongo.long_as_object. string Devuelve eun BSON_LONG como una instancia de MongoInt64 (en lugar de usar el tipo primitivo). string Nombre de host por omisin en caso de que no se especifique en el constructor. string Puerto TCP por omisin al conectar al servidor de bases de datos en caso de que no se especifique ningn puerto. El puerto por omisin es 27017. bool Indica si se debe reconectar o no a la base de datos al perder la conexin. bool Indica si se permiten o no conexiones persistentes. int Nmero de bytes por bloque. Se usa al fragmentar ficheros GridFS. Este valor debe ser al menos 100 veces menor que 4 megabytes (mx: 4194204) y se recomienda que sea incluso menor.

mongo.long_as_object

mongo.default_host

mongo.default_port

mongo.auto_reconnect

mongo.allow_persistent

mongo.chunk_size

mongo.cmd

string Carcter que se utiliza en lugar de $ en los modificadores y comparaciones. En vista de que es fcil olvidar escapar el carcter "$", puede elegirse cualquier otro en su lugar. Escoja un carcter que no aparezca en sus nombres de clave, como por ejemplo ":":
mongo.cmd = ":"

Ahora, para hacer una comparacin, sera:

<?php $query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) ); ?>

Puede cambiarse tambin en tiempo de ejecucin usando ini_set("mongo.cmd", ":"). Driver nativo MongoDB 25

Por supuesto, tambin pueden usarse comillas simples o la barra \ para escapar el carcter $.
mongo.utf8

int Indica si se debe lanzar una excepcin con textos que no sean UTF8. Hasta la versin 1.0.4, el driver de PHP ignoraba las cadenas no UTF8, incluso cuando no se esperaba que se fueran a insertar. Desde 1.0.4, el driver emite una MongoException. Para facilitar la transicion en las aplicaciones que insertan textos no UTF8, puede deshabiltiarse esta opcin, emulando el comportamiento anterior en que no se emitan excepciones. Sin embargo, esta opcin ser eliminada en la versin 1.1.0, de manera que siempre se emitirn excepciones en textos no UTF8. int Aadido en la versin 1.0.11. Indica si se permiten un texto vaco ("") como nombre de claves. Por omisin, el driver emitir una excepcin al proporcionar un texto vaco como clave en la base de datos. Es muy fcil pasar esto por alto al usar comillas dobles con operandos $, por lo que se recomienda dejar el valor por omisin. Sin embargo, si fuera necesario almacenar claves vacas, puede asignarse true a esta opcin, de manera que el driver permita usar un texto vaco a la base de datos.

mongo.allow_empty_keys

Seguridad Ataques de Inyeccin de Peticin

Al pasar parmetros $_GET a una consulta, debemos asegurarnos de que se han convertido en strings. Un usuario puede insertar un array asociativo en una peticin GET, provocando consultas $ no deseadas. Un ejemplo aparentemente inofensivo: supongamos que estamos buscando informacin de un usuario con la peticin http://www.example.com?username=bob. La aplicacin realiza la consulta $collection->find(array("username" => $_GET['username'])). Alguien podra alterarlo realizando una consulta a http://www.example.com?username[$ne]=foo, con lo que PHP lo convertir automticamente a un array asociativo, creando la consulta $collection->find(array("username" => array('$ne' => "foo"))), que devolver todos los usuarios con nombre distinto de "foo" (probablemente, todos). Es sencillo defenderse de un ataque como ste: hay que asegurarse de que los parmetros $_GET son del tipo esperado antes de enviarlos a la base de datos (en este caso, convertirlos a string). Tenga en cuenta que este tipo de ataque se puede usar con cualquier interaccin con una base de datos que localice documentos, incluyendo actualizaciones, busquedas con modificacin, y eliminaciones. Gracias a Phil por apuntar esto.

Driver nativo MongoDB

26

Para ms informacin sobre ataques tipo inyeccin SQL con MongoDB revise la documentacin principal.

Ataques de Inyeccin de Cdigo

Si se est usando JavaScript, debemos asegurarnos que cualquier variable que cruce los lmites PHP-JavaScript se pasa en el campo scope de MongoCode, y no interpolado en el cdigo JavaScript. Esto sucede al llamar a MongoDB::execute(), consultas $where, MapReduces, agrupaciones, y cualquier otra situacin en que se proporcione cdigo JavaScript a la base de datos.

Nota MapReduce ignora el campo scope de MongoCode, pero hay una opcin scope disponible en el comando que puede utilizarse en su lugar.

Por ejemplo, supongamos que tenemos un cdigo JavaScript para saludar a los usuarios en los registros de la base de datos. Podramos:
<?php // no haga esto! $username = $_POST['username']; $db->execute("print('Hola, $username!');"); ?>

Pero, qu ocurrira si un usuario malicioso metiera cdigo JavaScript?

<?php // no haga esto! // $username tiene como valor "'); db.users.drop(); print('" $db->execute("print('Hola, $username!');"); ?>

Ahora MongoDB ejecuta el cdigo JavaScript "print('Hola, '); db.users.drop(); print('!');". Este ataque es fcil de evitar: utilice scope al pasar variables de PHP a Javascript:
<?php $scope = array("user" => $username); $db->execute(new MongoCode("print('Hello, '+user+'!');", $scope)); ?>

Esto aade la variable user al mbito de JavaScript. Si ahora alguien quisiera aadir cdigo malicioso, MongoDB imprimira, sin causar daos, Hello, '); db.dropDatabase(); print('!. Driver nativo MongoDB 27

El uso de scope ayuda a prevenir que se ejecutene en la base de datos entradas maliciosas. Sin embargo, debe asegurarse de que su cdigo no cambie y ejecute los datos de entrada. Por ejemplo, nunca utilice la funcin eval de JavaScript con los datos de entrada de un usuario:
<?php // no haga esto! // $jsShellInput es "db.users.drop();" $scope = array("input" => $jsShellInput); $db->execute(new MongoCode("eval(input);", $scope)); ?>

Use siempre scope y nunca permita que la base de datos ejecute como cdigo los datos de entrada del usuario.

Solucin a problemas
En caso de que tuviera problemas, existe un gran nmero de recursos que consultar.

IRC El canal IRC oficial de MongoDB es irc.freenode.net/#mongodb. ste es el mtodo mas rpido para conseguir ayuda... siempre y cuando haya gente conectada. Listas de correo La lista de correo de MongoDB es un buen (y por lo general rpido) mtodo para encontrar respuestas. Seguimiento de fallos Ha encontrado un fallo? Echa algo en falta? Tiene alguna pregunta? Archvela en el bug track del driver de PHP. Puede habilitar la depuracin verbosa compilando el driver con el flag de depuracin.
$ ./configure CFLAGS=-DDEBUG

DEBUG habilita todas las depuraciones. Se pueden habilitar tambin flags de depuracin especficos. En el ltimo cdigo fuente, los flags disponibles son: DEBUG_CONN Depuracin de conexiones.

Ejecutando los Test del Driver

El paquete PECL no incluyen los test, pero estn disponible es Github. Hay dos tipos de test: Los test de PHP y los test en C.

TEst PHPUnit
Para ejecutarlos, debe descargar el driver de Github (los test se encuentran en el Driver nativo MongoDB 28

directorio tests/ ). Tambin necesitar PHPUnit para ejecutar los test. PHPUnit tambin se puede instalar mediante PEAR (hay un par de prerrequisitos que podr consultar en las instrucciones de instalacin). Algunos test esperarn que se produzcan alertas y errores, por lo que se debe asignar error_reporting en php.ini a E_STRICT | E_ALL para que pasen estos test. En caso contrario, se obtendrn errores que indicaran que el test esperaba que se emitiera una alerta o error. Para ejecutarlos, asegrese de que el servidor de MongoDB se est ejecutando en local en el puerto 27017. Antes de notificar de un error, por favor, asegrese de que ha ejecutado los test contra la ltima versin de desarrollo de MongoDB: a veces hay errores para funcionalidades que ya no se encuentran en la versin estable. La suite de pruebas usa la base de datos "phpunite". En caso de que utilice en su aplicacin una base de datos llamada "phpunit", asegrese de indicar a MongoDB un nuevo directorio de datos antes de ejecutar los test. Asegrese de que se encuentra en el directorio principal del cdigo fuente del driver que descarg de Github. Ejecute:
$ phpunit tests/MongoSuite.php

Tests C
Los test en C comprueban sobre todo funciones internas que no estn expuertas a PHP. Si deseara ejecutar estos test, deber compilar PHP con la bandera --enable-embed. Despus, acceda al directorio tests y ejecute make. Se crear un binario llamado unit. Llame a unit para ejecutar los test. Estos test no necesitan ninguna base de datos para funcionar. Cuando se pase un test, se imprimir un ".". Si un test falla, se informar y se dentrn las pruebas. Por favor, notifique cualquier error. Si make no pudiera localizar su biblioteca empotrada PHP (libphp5.so) o los ficheros de cabeceras, deber especificar un valor en la variable PHP_PATH. Ejecute make clean todos los objetos usados para los tests. Si ejecuta estos test con valgrind, no debera obtener ningn error de acceso no vlido a memoria, ni tampoco el mensaje de "no leaks are possible" que se muestra al final.

Notificando Errores
Por favor, notifique cualquier fallo o error en el bugtracker. Podra haber test que se omitan. Esto es normal, por lo que puede ignorarlo. Los nuevos test siempre son bienvenidos! Por favor, no dude en contribuir con nuevos test de cualquier tipo que pongan a prueba cualquier funcionalidad.

Driver nativo MongoDB

29

Clases del ncleo

Las clases del ncleo son la parte ms importante del controlador.

Driver nativo MongoDB

30

La clase Mongo

Introduccin
Conexin entre PHP y MongoDB. Esta clase se utiliza para crear y administrar conexiones. Un uso tpico es:
<?php $m = new Mongo(); // conectar $db = $m->foo; // obtener la base de datos con nombre "foo" ?>

Consulte Mongo::__construct() y la seccin connecting para ms informacin sobre cmo establecer conexiones.

Clases sinopsis

Mongo

Mongo { /* Constantes */ const string Mongo::VERSION; const string Mongo::DEFAULT_HOST = "localhost"; const int Mongo::DEFAULT_PORT = 27017; /* Fields */ public boolean connected = FALSE; public string status = NULL; protected string server = NULL; protected boolean persistent = NULL; /* Mtodos */

Driver nativo MongoDB

31

public bool Mongo::close ( void ) public bool Mongo::connect ( void ) protected bool Mongo::connectUtil ( void ) Mongo::__construct ( [ string $server = "mongodb://localhost:27017" [, array $ options = array("connect" => TRUE ) ] ] ) public array Mongo::dropDB ( mixed $db ) public MongoDB Mongo::__get ( string $dbname ) public array Mongo::getHosts ( void ) public static int Mongo::getPoolSize ( void ) public string Mongo::getSlave ( void ) public bool Mongo::getSlaveOkay ( void ) public array Mongo::listDBs ( void ) public array Mongo::poolDebug ( void ) public MongoCollection Mongo::selectCollection ( string $db, string $collection ) public MongoDB Mongo::selectDB ( string $name ) public static bool Mongo::setPoolSize ( int $size ) public bool Mongo::setSlaveOkay ( [ bool $ok = true ] ) public string Mongo::switchSlave ( void ) public string Mongo::__toString ( void ) }

Constantes predefinidas Constantes de Mongo

Mongo::VERSION Versin del driver PHP. Puede estar precedida por "+" o "-" si se encuentra entre varias versiones. Mongo::DEFAULT_HOST "localhost" Host de conexin en caso de que no se especifique ninguno.

Driver nativo MongoDB

32

Mongo::DEFAULT_PORT 27017 Puerto de conexin si no se especifica ningn otro.

Fields
status Si se trata de una conexin persistente, si la conexin se ha creado para este objeto, o si est siendo reutilizada. Si no se trata de una conexin persistente, este campo debe estar a NULL.

Ver tambin
Documentacin de MongoDB sobre conexiones.

Driver nativo MongoDB

33

Mongo::close
Mongo::close -- Cierra la conexin

Descripcin
public bool Mongo::close ( void ) Salvo en circunstancias excepcionales, no es necesario invocar a este mtodo. Cuando la instancia de Mongo quede fuera de mbito, el driver cerrar la conexin con la base de datos automticamente. En caso de que los objetos no salgan de mbito entre las peticiones, quizs se deee invocar a este mtodo al final de la ejecucin para eliminar todas las conexiones residuales. Sin embargo, es probable que sea ms eficiente utilizar una conexin persistente, que crear automticamente una conexin cuando sea necesaria y la utilizara para tntas peticiones como fuera posible. Si se est conectado a un conjunto de rplicas, close() slo cerrar la conexin a la primaria.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Indica si la conexin se cerr o no con xito.

Driver nativo MongoDB

34

Mongo::connect
Mongo::connect -- Conecta a un servidor de bases de datos

Descripcin
public bool Mongo::connect ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Indica si la conexin tuvo xito.

Errores/Excepciones
Lanza MongoConnectionException si falla la conexin a la base de datos.

Driver nativo MongoDB

35

Mongo::connectUtil
Mongo::connectUtil -- Conecta con un servidor de bases de datos

Descripcin
protected bool Mongo::connectUtil ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Indica si la conexin tuvo xito.

Errores/Excepciones
Emite MongoConnectionException si falla la conexin a la base de datos.

Driver nativo MongoDB

36

Mongo::__construct
Mongo::__construct -- Crear un nuevo objeto de conexin a base de datos

Descripcin
Mongo::__construct ( [ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE ) ] ] ) Si no se pasa ningn parmetro, conecta a "localhost:27017" (o lo que se indicara en php.ini en mongo.default_host y en mongo.default_port ).
server debe tener la forma: mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db

La cadena de conexin siempre comienza con mongodb://, para indicar que es una cadena de conexin de esta forma. Si se especifica username y password, el constructor autenticar la conexin con la base de datos antes de devolver el control. Son parmetros opcionales, y si se especifican, deben estar seguidos por una @. Al menos debe proporcionarse un host (el puerto es opcional, por omisin es 27017) y se puede conectar a tantos como se desee. Los nombres de host se separan por comas, y el constructor notificar xito si al menos se conecta a uno de ellos. Si no se pudo conectar a ninguno, emitir una excepcin MongoConnectionException. Finalmente, si se especific usuario y contrasea, se puede especificar tambin la base de datos contra la que se autentica. Si db no se especifica, se utilizar "admin".

Parmetros
server

Nombre del servidor.

options

Array con las opciones de conexin. Las opciones disponibles actualmente son: "connect" Si el constructor debe o no conectar antes de devolver el control. Por omisin, TRUE. "timeout" Tiempo mximo que esperar el driver para conectar a la base de datos (en milisegundos). "replicaSet" Nombre del conjunto de rplicas al que conectar. Si se indicara, se averiguar al maestro usando el comando de base de datos ismaster en cada semilla, de manera que el driver pudiera finalizar conectando a un servidor que ni siquiera estaba en la lista. Para ms detalles, revise el ejemplo de abajo sobre Driver nativo MongoDB 37

rplicas. "username" En lugar de incluirlo en la lista de host, se puede especificar aqu el nombre de usuario. Es til en caso de que un nombre de usuario incluya un ":". Esto reemplaza un nombre de usuario situado en la lista de host. "password" En lugar de incluirlo en la lista de host, se puede especificar aqu la contrasea. Es til en caso de que una contrasea incluya una "@". Esto reemplaza una contrasea establecida en la lista de hosts. "db" La base de datos para autenticarse se puede especificar aqu, en lugar de incluirlo en la lista de hosts. Esto reemplaza una base de datos dada en la lista de hosts.

Valores devueltos
Devuelve un nuevo objeto de conexin a base de datos.

Errores/Excepciones
Emite MongoConnectionException si intentara conectar a la base de datos en todos hosts proporcionados, y fallara. Tambin emitir MongoConnnectionException si el nombre de usuario o contrasea fueran invlidos. Revise la documentacin de MongoConnectionException para conocer las excepciones y sus causas.

Historial de cambios

Versin 1.2.0

Descripcin

Eliminada la opcin de persistencia, ya que ahora todas las conexiones lo son. Se puede seguir usando, pero no tendr ningn efecto.
"persist"

Si la conexin debe o no ser presistente. Si se habilita, la conexin lo ser. Su representacin en forma de string se usa como id de la conexin, de modo que dos instancias de Mongo que se inicialicen con array("persist" => "foobar") compartirn la misma conexin, mientras que una instancia inicializada con array("persist" => "barbaz") usar una conexin a base de datos diferente.

Driver nativo MongoDB

38

Ahora el parmetro "replicaSet" espera un strings, y no un booleano (aunque todava se aceptara un booleano).

1.0.2

Cambiado el constructor para que acepte un array de opciones. Antes de 1.0.2, el constructor tena los siguientes parmetros:
server

Nombre de servidor.
connect

Parmetro booleano opcional para especificar si el constructor debe o no conectar a la base de datos antes de devolver el control. Por omisin, TRUE.
persistent

Si la conexin debe o no ser persistente.

paired

Si la conexin debe vincularse.

1.0.9 1.2.0

Aadida la opcin replicaSet. Aadidas las opciones username y password.

Ejemplos
Ejemplo #1 - Ejemplo de conjunto de rplicas con Mongo::__construct() Este ejemplo muestra cmo conectar el driver a un conjunto de rplicas. Asume que hay un conjunto de tres servidores: sf1.example.com, sf2.example.com, y ny1.example.com. El maestro puede ser cualquiera de ellos.
<?php // lista de nombes de servidores separadas por comas $m1 = new Mongo("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet")); // slo es necesaria una semilla, y el driver obtendr la lista completa y encontrar // al maestro de esta semilla $m2 = new Mongo("mongodb://ny1.example.com", array("replicaSet" => "myReplSet")); ?>

Driver nativo MongoDB

39

Si el maestro falla, el driver averiguar qu servidor secundario se convierte en el nuevo maestro y comenzar a usar automticamente la conexin. La recuperacin automtica no funcionar correctametne si no se especificara replicaSet. Al menos debe haber una semilla funcionando de la lista de semillas para que el driver se conecte al conjunto de rplicas. Si se incluyen semillas de dos juegos de replicas separados, el comporamiento ser inesperado. Para ms informacin, revise la documentation sobre conjuntos de rplicas.

Ejemplo #2 - Conectando a un socket de dominio En la versin 1.0.9 o superior, se puede usar un socket de dominio UNIX para conectar a una instancia de MongoDB local. Es ligeramente ms rpido que una conexin de red. En la versin 1.5.0, el servidor MongoDB abre automticamente un socket en /tmp/mongodb-<port>.sock. Puede coenctarse a l especificando la ruta en la cadena de conexin:
<?php // Servidor MongoDB funcionando en local en el puerto 20000 $m = new Mongo("mongodb:///tmp/mongodb-20000.sock"); ?>

Se puede combinar con las opciones que se desee:

<?php // al conectar al socket de dominio, retrocede a la conexin a localhost $m = new MongoDB("mongodb:///tmp/mongodb-27017.sock,localhost:27017"); ?>

Ejemplo #3 - Ejemplo de autenticacin con Mongo::__construct() El usuario debe existir en la base de datos admin antes de intentar autenticarlo. Puede crearse uno con la consola de Mongo ejecutando:
> use admin switched to db admin > db.addUser("testUser", "testPass"); { "_id" : ObjectId("4b21272fd9ab21611d19095c"), "user" : "testUser", "pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59" }

Driver nativo MongoDB

40

>

Tras crear un usuario con, en este caso, el nombre "testUser" y la contrasea "testPass", puede crearse una conexin autenticada:
<?php $m = new Mongo("mongodb://testUser:testPass@localhost"); ?>

Driver nativo MongoDB

41

Mongo::dropDB
Mongo::dropDB -- Drops a database [deprecated]

Descripcin
public array Mongo::dropDB ( mixed $db )

Advertencia Deprecated Use MongoDB::drop() instead.

Parmetros
db

The database to drop. Can be a MongoDB object or the name of the database.

Valores devueltos
Returns the database response.

Driver nativo MongoDB

42

Mongo::__get
Mongo::__get -- Gets a database

Descripcin
public MongoDB Mongo::__get ( string $dbname ) This is the cleanest way of getting a database. If the database name has any special characters, Mongo::selectDB() will need to be used. However, in most cases, this should be sufficient.
<?php $mongo = new Mongo(); // the following two lines are equivalent $db = $mongo->selectDB("foo"); $db = $mongo->foo; ?>

Parmetros
dbname

The database name.

Valores devueltos
Returns a new db object.

Errores/Excepciones
Throws a generic exception if the database name is invalid.

Driver nativo MongoDB

43

Mongo::getHosts
Mongo::getHosts -- Updates status for all hosts associated with this

Descripcin
public array Mongo::getHosts ( void ) This method can only be used with a connection to a replica set. It returns the status of all of the hosts in the set. See the query section of this manual for information on distributing reads to slaves.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns an array of information about the hosts in the set. Includes each host's hostname, its health (1 is healthy), its state (1 is primary, 2 is secondary, 0 is anything else), the amount of time it took to ping the server, and when the last ping occurred. For example, on a three-member replica set, it might look something like:
array(2) { ["A:27017"]=> array(4) { ["health"]=> int(1) ["state"]=> int(2) ["ping"]=> int(369) ["lastPing"]=> int(1309470644) } ["B:27017"]=> array(4) { ["health"]=> int(1) ["state"]=> int(1) ["ping"]=> int(139) ["lastPing"]=> int(1309470644) } ["C:27017"]=> array(4) { ["health"]=> int(1) ["state"]=> int(2)

Driver nativo MongoDB

44

["ping"]=> int(1012) ["lastPing"]=> int(1309470644) } }

In the example above, B and C are secondaries (state 2). B is likely to be selected for queries if slaveOkay is set, as it has a lower ping time (and thus is likely closer or handling less load) than C.

Driver nativo MongoDB

45

Mongo::getPoolSize
Mongo::getPoolSize -- Get pool size for connection pools

Descripcin
public static int Mongo::getPoolSize ( void )

Advertencia This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::getSize() instead.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns the current pool size.

Ejemplos
Ejemplo #1 - Changing pool size This returns the default pool size, sets a new pool size, then prints the new pool size and the pool debugging information. Note that changing the pool size only affects new connection pools, it does not change old ones.
<?php $connection = new Mongo("host1"); // pool size is -1 echo "pool size is: ".Mongo::getPoolSize()."\n"; echo "setting pool size to 200\n"; Mongo::setPoolSize(200); // pool size is 200 echo "pool size is: ".Mongo::getPoolSize()."\n"; $conn2 = new Mongo("host2"); // remaining for host1 is -2 // remaining for host2 is 199 var_dump(Mongo::poolDebug());

Driver nativo MongoDB

46

?>

Ver tambin

Mongo::setPoolSize() Mongo::poolDebug() The connection documentation.

Driver nativo MongoDB

47

Mongo::getSlave
Mongo::getSlave -- Returns the address being used by this for slaveOkay reads

Descripcin
public string Mongo::getSlave ( void ) This finds the address of the slave currently being used for reads. It is a read-only method: it does not change anything about the internal state of the object. When you create a connection to the database, the driver will not immediately decide on a slave to use. Thus, after you connect, this function will return NULL even if there are slaves available. When you first do a query with slaveOkay set, at that point the driver will choose a slave for this connection. At that point, this function will return the chosen slave. See the query section of this manual for information on distributing reads to slaves.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
The address of the slave this connection is using for reads. This returns NULL if this is not connected to a replica set or not yet initialized.

Driver nativo MongoDB

48

Mongo::getSlaveOkay
Mongo::getSlaveOkay -- Consultar el valor slaveOkay de esta conexin

Descripcin
public bool Mongo::getSlaveOkay ( void ) Revise la seccin de consultas de este manual para saber cmo distribuir lecturas a esclavos.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el valor de slaveOkay de esta instancia.

Driver nativo MongoDB

49

Mongo::listDBs
Enumera todas las bases de datos disponibles

Descripcin
public array Mongo::listDBs ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve un array asociativo de tres campos. El primero es databases, que a su vez contiene otro array. Cada elemento del array es un array asociativo que se corresponde con una base de datos, ofreciendo el nombre de la base de datos, tamao y si est o no vaca. Los otros dos campos son totalSize (tamao total en bytes) y ok, que ser 1 cuando este mtodo se ejecute con xito.

Ejemplos
Ejemplo #1 - Ejemplo de Mongo::listDBs Ejemplo que muestra cmo usar listDB y la estructura de datos devuelta.
<?php $mongo = new Mongo(); $dbs = $mongo->listDBs(); print_r($dbs); ?>

El resultado del ejemplo sera algo similar a:

Array ( [databases] => Array ( [0] => Array ( [name] => doctrine [sizeOnDisk] => 218103808 [empty] => ) ) [totalSize] => 218103808 [ok] => 1 )

Driver nativo MongoDB

50

Mongo::poolDebug
Mongo::poolDebug -- Returns information about all connection pools.

Descripcin
public array Mongo::poolDebug ( void )

Advertencia This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::info() instead.

Returns an array of information about all connection pools.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Each connection pool has an identifier, which starts with the host. For each pool, this function shows the following fields:
in use

The number of connections currently being used by Mongo instances.

in pool

The number of connections currently in the pool (not being used).

remaining

The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of Mongo before we exhausted this pool (assuming no instances of Mongo went out of scope, returning their connections to the pool). A negative number means that this pool will spawn unlimited connections. Before a pool is created, you can change the max number of connections by calling Mongo::setPoolSize(). Once a pool is showing up in the output of this function, its size cannot be changed.
timeout

The socket timeout for connections in this pool. This is how long connections in this pool will attempt to connect to a server before giving up.

Driver nativo MongoDB

51

Mongo::selectCollection() Obtiene una coleccin de base datos

Descripcin
public MongoCollection Mongo::selectCollection ( string $db, string $collection )

Parmetros
db

Nombre de la base de datos.

collection

Nombre de la coleccin.

Valores devueltos
Devuelve un nuevo objeto de coleccin.

Errores/Excepciones
Emite InvalidArgumentException si el nombre de la base de datos o de la coleccin fuera invlido.

Ejemplos
Ejemplo #1 - Ejemplo de Mongo::selectCollection()
<?php $m = new Mongo(); $c1 = $m->selectCollection("foo", "bar.baz"); // lo cual es equivalente a $c2 = $m->selectDB("foo")->selectCollection("bar.baz"); // $c1 y $c2 representan la misma conexin ?>

Driver nativo MongoDB

52

Mongo::selectDB
Mongo::selectDB -- Obtener una base de datos

Descripcin
public MongoDB Mongo::selectDB ( string $name )

Parmetros
name

El nombre de la base de datos.

Valores devueltos
Devuelve un nuevo objeto de base de datos.

Errores/Excepciones
Emite InvalidArgumentException si el nombre de la base de datos no es vlido.

Driver nativo MongoDB

53

Mongo::setPoolSize
Mongo::setPoolSize -- Set the size for future connection pools.

Descripcin
public static bool Mongo::setPoolSize ( int $size )

Advertencia This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::setSize() instead.

Sets the max number of connections new pools will be able to create.

Parmetros
size

The max number of connections future pools will be able to create. Negative numbers mean that the pool will spawn an infinite number of connections.

Valores devueltos
Returns the former value of pool size.

Ejemplos

Ejemplo #1 - Mongo::setPoolSize() example If you set the pool size to n and then create n connections, attempting to create an n+1 st connection will throw a MongoConnectionException.
<?php // only allow one connection to a server Mongo::setPoolSize(1); // creates one connection to localhost:27017 $m1 = new Mongo(); // attempt to create a second connection to localhost:27017 // only one connection is allowed, so this will throw an exception $m2 = new Mongo();

Driver nativo MongoDB

54

?>

El resultado del ejemplo sera algo similar a:

Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10 Stack trace: #0 /path/to/php/script.php(10): Mongo->__construct() #1 {main} thrown in /path/to/php/script.php on line 10

Ver tambin

Mongo::getPoolSize() Mongo::poolDebug() The connection documentation.

Driver nativo MongoDB

55

Mongo::setSlaveOkay
Mongo::setSlaveOkay -- Cambia el ajuste de slaveOkay de esta conexin

Descripcin
public bool Mongo::setSlaveOkay ( [ bool $ok = true ] ) Revise la seccin de consultas de este manual para conocer cmo distribuir lecturas entre esclavos.

Parmetros
ok

Indica si las lecturas deben o no enviarse a los miembros secundarios del conjunto de rplicas, para todas aquellas consultas que se realicen con esta instancia de Mongo.

Valores devueltos
Devuelve el valor anterior de slaveOkay que tena esta instancia.

Driver nativo MongoDB

56

Mongo::switchSlave
Mongo::switchSlave -- Elije un nuevo esclavo para lecturas slaveOkay

Descripcin
public string Mongo::switchSlave ( void ) Elije un esclavo aleatoriamente para crear una conexin de lectura. Se invoca automticamente por el driver por lo que no se debe necesitar hacerlo a mano. Realiza una llamada a Mongo::getHosts() (para recargar el estado de los hosts) y a Mongo::getSlave() (para obtener el valor devuelto). Revise la seccin de consultas de este manual para obtener ms informacin sobre lescturas distribuidas en esclavos.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
La direccin del esclavo que est usando esta conexi para realizar lecturas. Podra ser la misma que la anterior, ya que se eligen aleatoriamente. Si slo hubiera un secundario (o slo el primario) nicamente se devolvera una direccin. Por ejemplo, si tuviramos un conjunto de rplicas de tres miembros, con un primario, secundario, y un rbitro, este mtodo siempre devolvera la direccin del secundario. Si ste no estvuiera disponible, este mtodo devolvera la direccin del primario. Si ste tampoco estuviera disponible, se emitira una excepcin, ya que un rbitro no puede realizar operaciones de lectura.

Errores/Excepciones
Si se le llama desde una conexin sin conjuntos de rplicas, emite MongoException (cdigo de error 15). Tambin emite MongoException si no pudiera encontrar ningn elemento (primario o secundario) del que leer (cdigo de error 16).

Driver nativo MongoDB

57

Mongo::__toString
Mongo::__toString -- Representacin en forma de texto de esta conexin

Descripcin
public string Mongo::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nombre de host y el puerto de esta conexin.

Driver nativo MongoDB

58

Clase MongoDB

Introduccin
Las instancias de esta clase se utilizan para interactuar con la base de datos. Para seleccionar una base de datos:
<?php $m = new Mongo(); // conectar $db = $m->selectDB("ejemplo"); ?>

Los nombres de bases de datos pueden utilizar prcticamente cualquier carcter del rango ASCII. Sin embargo no pueden contener ni " ", "." ni un texto vaco. El nombre "system" tambin est reservado. Hay algunos nombres poco usuales de bases de datos que s son vlidos: "null", "[x,y]", "3", "\"", "/". A diferencia de los nombres de colecciones, los nombres bases de datos pueden contener "$".

Clases sinopsis

MongoDB

MongoDB { /* Constantes */ const int MongoDB::PROFILING_OFF = 0; const int MongoDB::PROFILING_SLOW = 1; const int MongoDB::PROFILING_ON = 2; /* Campos */ public integer w = 1; public integer wtimeout = 10000; /* Mtodos */

Driver nativo MongoDB

59

public array MongoDB::authenticate ( string $username, string $password ) public array MongoDB::command ( array $command ) MongoDB::__construct ( Mongo $conn, string $name ) public MongoCollection MongoDB::createCollection ( string $name [, bool $capped = FALSE [, int $size = 0 [, int $max = 0 ] ] ] ) public array MongoDB::createDBRef ( string $collection, mixed $a ) public array MongoDB::drop ( void ) public array MongoDB::dropCollection ( mixed $coll ) public array MongoDB::execute ( mixed $code [, array $args = array() ] ) public bool MongoDB::forceError ( void ) public MongoCollection MongoDB::__get ( string $name ) public array MongoDB::getDBRef ( array $ref ) public MongoGridFS MongoDB::getGridFS ( [ string $prefix = "fs" ] ) public int MongoDB::getProfilingLevel ( void ) public bool MongoDB::getSlaveOkay ( void ) public array MongoDB::lastError ( void ) public array MongoDB::listCollections ( void ) public array MongoDB::prevError ( void ) public array MongoDB::repair ( [ bool $preserve_cloned_files = FALSE [, bool $ backup_original_files = FALSE ] ] ) public array MongoDB::resetError ( void ) public MongoCollection MongoDB::selectCollection ( string $name ) public int MongoDB::setProfilingLevel ( int $level ) public bool MongoDB::setSlaveOkay ( [ bool $ok = true ] ) public string MongoDB::__toString ( void ) }

Constantes predefinidas
Driver nativo MongoDB 60

Niveles de Logs de MongoDB

MongoDB::PROFILING_OFF 0 Profiling deshabilitado. MongoDB::PROFILING_SLOW 1 Profiling habilitado para operaciones lentas (>100 ms). MongoDB::PROFILING_ON 2 Profiling habilitado para todas las operaciones.

Campos
w1 Nmero de servidores en los que replicar los cambios antes de retornar xito. Se hereda por las instancias de MongoCollection que deriven de este objeto. w slo est disponible en versiones 1.5.1+ del servidor MongoDB y 1.0.8+ del driver. w se usa cada vez que se realiza una operacin "segura" ( MongoCollection::insert(), MongoCollection::update(), MongoCollection::remove(), MongoCollection::save(), y MongoCollection::ensureIndex() soportan la opcin segura). Con el valor por omisin (1), una operacin segura devolver el control cuando el servidor de bases de datos obtenga la operacin. Si el servidor se cayera antes de que la operacin se replicara a un esclavo, podra perderse la operacin de forma permanente. De esta forma, se puede especificar en w un valor superior a 1 para garantizar que al menos un esclavo ha recibido la operacin antes de que se considere que ha habido xito. Por ejemplo, si w fuera 2, tanto el servidor principal como un esclavo tendrn un registro de la operacin. Si no, el driver emitir una excepcin MongoCursorException. Puede ser tentador establecer en w el total de esclavos + maestro, pero entonces, si un esclavo se cayera, la operacin fallara y se emitira una excepcin, por lo que suele ser ms seguro establecer w=2 (maestro + 1 esclavo). wtimeout 10000 Nmero de milisegundos a esperar a que las rplicas de MongoDB::$w tengan lugar. Se hereda por las instancias de MongoCollection que deriven de este objeto. w slo est disponible en las versiones 1.5.1+ del servidor MongoDB y en las 1.0.8+ del driver. A no ser que se establezca un valor en wtimeout, el servidor esperar eternamente a que se replique a w servidores para finalizar. Por omisin el driver esperar 10 segundos. Puede modificarse este valor para alterar este comportamiento.

Ver tambin
Documentacin de MongoDB de bases de datos.

Driver nativo MongoDB

61

MongoDB::authenticate
MongoDB::authenticate -- Iniciar sesin en esta base de datos

Descripcin
public array MongoDB::authenticate ( string $username, string $password ) Este mtodo hace que esta conexin sea autenticada. Si el servidor de bases de datos tiene la autenticacin habilitada (de forma predeterminada, no lo est), deber iniciar sesin antes de poder hacer cualquier cosa. En general, deber se recomienda utilizar la autenticacin que incorpora Mongo::__construct() antes que este mtodo. Si se autentica sobre la conexin, y la conexin se cae y se reconecta durante la sesin, automticamente ser re-autenticado. Si se autentica manualmente usando este mtodo, y la conexin se cae, deber llamar a este mtodo de nuevo cuando la conexin vuelva. Este mtodo es equivalente a ejecutar:
<?php $salted = "${username}:mongo:${password}"; $hash = md5($salted); $nonce = $db->command(array("getnonce" => 1)); $saltedHash = md5($nonce["nonce"]."${username}${hash}"); $result = $db->command(array("authenticate" => 1, "user" => $username, "nonce" => $nonce["nonce"], "key" => $saltedHash )); ?>

Una vez que una conexin ha sido autenticada, slo puede ser des-autenticada mediante el comando de base de datos "logout":
<?php $db->command(array("logout" => 1)); ?>

Parmetros
username

Nombre de usuario.

Driver nativo MongoDB

62

password

La contrasea (en texto plano).

Valores devueltos
Devuelve la respuesta de la base de datos. Si el inicio de sesin tuvo xito, devolver:
<?php array("ok" => 1); ?>

Si algo fue mal, devolver:

<?php array("ok" => 0, "errmsg" => "auth fails"); ?>

("auth fails" puede ser otro mensaje, dependiendo de la versin de la base de datos y de qu fuera mal).

Ver tambin
Documentacin de MongoDB sobre autenticacin.

Driver nativo MongoDB

63

MongoDB::command
MongoDB::command -- Ejecuta un comando de base de datos

Descripcin
public array MongoDB::command ( array $command ) Prcticamente todo lo que no son operaciones CRUD se puede realizar con un comando de base de datos. Necesita conocer la versin de la base de datos? Hay un comando para ello. Necesita hacer una agregacin? Hay un comando para ello. Necesia habilitar registros de mensajes? Se puede hacer una idea. Este mtodo es equivalente a:
<?php public function command($data) { return $this->selectCollection('$cmd')->findOne($data); } ?>

Parmetros
command

Consulta que se enviar.

Historial de cambios

Versin 1.2.0

Descripcin Aadido el parmetro options con una nica opcin: timeout.

Valores devueltos
Devuelve la respuesta de la base de datos.

Ejemplos

Driver nativo MongoDB

64

Ejemplo #1 - Ejemplo de MongoDB::command() con "distinct" Localizando todos los valores distintos de una clave.
<?php $gente = $db->gente; $gente->insert(array("nombre" $gente->insert(array("nombre" $gente->insert(array("nombre" $gente->insert(array("nombre" => => => => "Joe", "edad" => 4)); "Sally", "edad" => 22)); "Dave", "edad" => 22)); "Molly", "edad" => 87));

$edades = $db->command(array("distinct" => "gente", "key" => "edad")); foreach ($edades['values'] as $edad) { echo "$edad\n"; } ?>

El resultado del ejemplo sera algo similar a:

4 22 87

Ejemplo #2 - Ejemplo de MongoDB::command() con MapReduce Obtener todos los usuarios con al menos un evento "sale" (venta), y cuntas veces han tenido ventas cada uno de esos usuarios.
<?php // documento de eventos de ejemplo $events->insert(array("user_id" => $id, "type" => $type, "time" => new MongoDate(), "desc" => $description)); // construccin del mapa y funcin reductora $map = new MongoCode("function() { emit(this.user_id,1); }"); $reduce = new MongoCode("function(k, vals) { ". "var sum = 0;". "for (var i in vals) {". "sum += vals[i];". "}". "return sum; }"); $sales = $db->command(array( "mapreduce" => "events", "map" => $map, "reduce" => $reduce,

Driver nativo MongoDB

65

"query" => array("type" => "sale"), "out" => array("merge" => "eventCounts"))); $users = $db->selectCollection($sales['result'])->find(); foreach ($users as $user) { echo "Usuario {$user['_id']} tuvo {$user['value']} venta(s).\n"; } ?>

El resultado del ejemplo sera algo similar a:

Usuario 47cc67093475061e3d9536d2 tuvo 3 venta(s). Usuario 49902cde5162504500b45c2c tuvo 14 venta(s). Usuario 4af467e4fd543cce7b0ea8e2 tuvo 1 venta(s).

Nota Usando MongoCode Este ejemplo utiliza MongoCode, que puede utilizar tambin un argumento de mbito. Sin embargo, por el momento, MongoDB no soporta el uso de mbitos en MapReduce. Si deseara utilizar variables en el lado de cliente con las funciones MapReduce, puede aairlas al mbito global usando el campo opcional de mbito con el comando de la base de datos. Consulte la documentacin de MapReduce para ms informacin.

Nota El argumento out Antes de 1.8.0, el argumento out era opcional. Si no se iba a usar, los resultados de MapReduce se escriban a una coleccin temporal, que se eliminaba cuando se cerrara la conexin. A partir de la versin 1.8.0, el argumento out es obligatorio. Consulte la documentacin de MapReduce para ms informacin.

Si va a usar MapReduce, Prajwal Tuldhar ha creado una API para usuarios de Mongo PHP que ofrece una interfaz ms elegante que el comando 'al desnudo'. Puede descarlo desde Github y hay un art-culo de blog sobre cmo usarlo.

Ver tambin
Documentacin de MongoDB sobre comandos de base de datos y comando individuales: findAndModify, getLastError, y repair (existen muchos ms, stos son slo unos pocos ejemplos).

Driver nativo MongoDB

66

MongoDB::__construct
MongoDB::__construct -- Crea una nueva base de datos

Descripcin
MongoDB::__construct ( Mongo $conn, string $name ) Este mtodo no est hecho para ser llamado directamente. La forma recomendada de crear una instancia de MongoDB es mediante Mongo::__get() o mediante Mongo::selectDB(). Si va a ignorar el prrafo anterior y desea llamar directamente al constructor, puede hacerlo as:
<?php $m = new Mongo(); $db = new MongoDB($m, 'mydbname'); ?>

Pero no lo haga. Es mucho mas elegante as:

<?php $m = new Mongo(); $db = $m->mydbname; // o, si el nombre contiene caracteres raros: $db = $m->selectDB('my,db:name'); ?>

Parmetros
Mongo conn Conexin a la base de datos.
name

Nombre de la base de datos.

Valores devueltos
Devuelve la base de datos.

Errores/Excepciones

Driver nativo MongoDB

67

Lanza una excepcin por defecto si el nombre no fuera vlido.

Driver nativo MongoDB

68

MongoDB::createCollection
MongoDB::createCollection -- Crea una coleccin

Descripcin
public MongoCollection MongoDB::createCollection ( string $name [, bool $capped = FALSE [, int $size = 0 [, int $max = 0 ] ] ] ) Este mtodo se usa para crear colecciones "capped" (de tamao fijo) y otras colecciones que requieren opciones especiales. Es idntico a ejecutar:
<?php $collection = $db->command(array("create" => $name, "size" => $size, "capped" => $capped, "max" => $max)); ?>

Consulte MongoDB::command() para ms informacin sobre comandos de base de datos.

Parmetros
name

Nombre de la coleccin.
capped

Si la coleccin debe ser o no de tamao fijo.

size

Si la coleccin fuera de tamao fijo, aqu indicamos su tamao en bytes.

max

Si la coleccin fuera de tamao fijo, aqu establecemos el nmero mximo de elementos que podr almacenar.

Valores devueltos
Devuelve un objeto de coleccin que representa la nueva coleccin.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::createCollection() para coleccin de tamao fijo Una coleccin "capped" es un tipo especial de coleccin que tiene un tamao fijo o un nmero fijo de elementos. Una vez que la coleccin est "llena", los elementos ms viejos se eliminan cada vez que aadimos nuevos. Estas colecciones pueden ser muy

Driver nativo MongoDB

69

tiles para usos como registro de mensajes, donde quizs se desee mantener una determinada cantidad de espacio para mensajes sin preocuparse por si crece demasiado. Este ejemplo crea una coleccin de mensajes de error muy pequea, que mantendr hasta 10 documentos.
<?php $log = $db->createCollection("logger", true, 10*1024, 10); for ($i = 0; $i < 100; $i++) { $log->insert(array("level" => WARN, "msg" => "mensaje de error #$i", "ts" => new MongoDate())); } $msgs = $log->find(); foreach ($msgs as $msg) { echo $msg['msg']."\n"; } ?>

El resultado del ejemplo sera algo similar a:

mensaje mensaje mensaje mensaje mensaje mensaje mensaje mensaje mensaje mensaje de de de de de de de de de de error error error error error error error error error error #90 #91 #92 #93 #94 #95 #96 #97 #98 #99

Driver nativo MongoDB

70

MongoDB::createDBRef
MongoDB::createDBRef -- Crea una referencia a base de datos

Descripcin
public array MongoDB::createDBRef ( string $collection, mixed $a ) Este mtodo es una interfaz flexible que permite crear referencias a bases de datos (vea MongoDBRef ).

Parmetros
collection

Coleccin a la que apuntar la referencia de base de datos.

a

Objeto o _id al que crear la referencia. Si se pasara un objeto o un array asociativo, se crear una referencia usando su campo _id.

Valores devueltos
Devuelve un array de referencia a base de datos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::createDBRef() Ejemplo que muestra cmo crear una referencia a base de datos a partir de un documento.
<?php $articulos = $db->articulos; $articulo = array( 'titulo' => 'Articulo de prueba', 'descripcion' => 'Descripcion de articulo de prueba' ); $articulos->insert($articulo); $ref = $db->createDBRef('articulos', $articulo); print_r($articulo); print_r($ref); ?>

El resultado del ejemplo sera algo similar a: Driver nativo MongoDB 71

Array ( [title] => Articulo de prueba [description] => Descripcion de articulo de prueba [_id] => MongoId Object ( ) ) Array ( [$ref] => articulos [$id] => MongoId Object ( ) )

Ahora, $ref puede ser almacenado en otro documento, y consultado ms adelante con MongoDB::getDBRef o con MongoCollection::getDBRef.

Ejemplo #2 - Ejemplo de MongoDB::createDBRef() Ejemplo que muestra cmo crear una referencia a base de datos a partir de un id.
<?php $id = new MongoId('47cc67093475061e3d9536d2'); $ref = $db->createDBRef('articulos', $id); ?>

Driver nativo MongoDB

72

MongoDB::drop
MongoDB::drop -- Borra esta base de datos

Descripcin
public array MongoDB::drop ( void ) Borra la base de datos que est en uso. Es equivalente a ejecutar:
<?php public function drop() { $this->command(array("dropDatabase" => 1)); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la respuesta de la base de datos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::drop() Este ejemplo muestra cmo borrar una base de datos mongo.
<?php $db = $mongo->foo; $response = $db->drop(); print_r($response); ?>

El resultado del ejemplo sera algo similar a:

Array ( [dropped] => foo.$cmd [ok] => 1 )

Driver nativo MongoDB

73

MongoDB::dropCollection
MongoDB::dropCollection -- Borra una coleccin [obsoleto]

Descripcin
public array MongoDB::dropCollection ( mixed $coll )

Advertencia Obsoleto Utilice en su lugar MongoCollection::drop(). Esta funcin tiene fugas de memoria en versiones 1.0.7 y anteriores!

Parmetros
coll

MongoCollection o nombre de la coleccin a borrar.

Valores devueltos
Devuelve la respuesta de la base de datos.

Driver nativo MongoDB

74

MongoDB::execute
MongoDB::execute -- Ejecuta cdigo JavaScript en el servidor de bases de datos

Descripcin
public array MongoDB::execute ( mixed $code [, array $args = array() ] ) El servidor de bases de datos de Mongo contiene un motor JavaScript. Este mtodo permite ejecutar cualquier cdigo JavaScript en la base de datos. Puede resultar til si se desea trabajar ligeramente sobre algunas colecciones, o procesar algunos resultados en el lado del servidor para reducir la cantidad de datos que se enviar al cliente. Al ejecutar JavaScript en la base de datos se hace un bloqueo de escrituras, lo cual significa que se bloquean otras operaciones. Asegrese de que tiene esto en consideracin antes de ejecutar scripts costosos. Este mtodo es una envoltura de un comando de base de datos. Bsicamente, sera:
<?php public function execute($code, $args) { return $this->command(array('$eval' => $code, args => $args)); } ?>

Si se tuviera una nica sentencia en una nica lnea, MongoDB devuelve un valor. Esto puede provocar comportamientos inesperados. Por ejemplo, el siguiente cdigo devuelvo "foo":
<?php $db->execute('"foo";'); ?>

Sin embargo, este cdigo devuelve NULL:

<?php $db->execute('"bar"; "foo";'); // ms de una sentencia $db->execute('db.foo.count( );'); // ms de una lnea ?>

Para evitar estos comportamientos, lo mejor es no dejar que MongoDB decida qu devolver, usando en su lugar una sentencia "return" explcita. Podramos cambiar los ejemplos superiores por lo siguiente:
<?php

Driver nativo MongoDB

75

$db->execute('"bar"; return "foo";'); $db->execute('return db.foo.count( );'); ?>

Ahora, la primera sentencia devolver "foo" y la segunda devolver un contador de la coleccin "foo".

Parmetros
code

MongoCode o texto a ejecutar.

args

Argumentos que se deben pasar a code.

Valores devueltos
Devuelve el resultado de la evaluacin.

Ejemplos
Ejemplo #1 - Ejemplo sencillo de MongoDB::execute()
<?php $response = $db->execute("function() { return 'Hola, mundo!'; }"); echo $response['retval']; ?>

El resultado del ejemplo sera algo similar a:

Hola, mundo!

Ejemplo #2 - Ejemplo de parmetros en MongoDB::execute() Pasaremos a la funcin JavaScript valores del array del parmetro opcional.
<?php $response = $db->execute("function(despedida, nombre) { return despedida+', '+nombre+'!'; }", array("Hasta pronto", "Juan")); echo $response['retval'];

Driver nativo MongoDB

76

?>

El resultado del ejemplo sera algo similar a:

Hasta pronto, Juan!

Ejemplo #3 - Ejemplo de mbito Si en lugar de un string, usramos un MongoCode en el primer parmetro, podr pasarse un mbito en el cual se ejecutar JavaScript.
<?php $func = "function(despedida, nombre) { ". "return despedida+', '+nombre+', dice '+despedidor;". "}"; $scope = array("despedidor" => "Fran"); $code = new MongoCode($func, $scope); $response = $db->execute($code, array("Hasta pronto", "Juan")); echo $response['retval']; ?>

El resultado del ejemplo sera algo similar a:

Hasta pronto, Juan, dice Fran

Driver nativo MongoDB

77

MongoDB::forceError() Crea un error de base de datos

Descripcin
public bool MongoDB::forceError ( void ) Este mtodo no es muy til para el uso normal de MongoDB. Obliga a que se produzca un error de base de datos. Esto quiere decir que MongoDB::lastError() devolver un error de base de datos genrico despus de ejecutar este comando. Este comando es idntico a la ejecucin de:
<?php public function forceError() { return $this->command(array('forceerror' => 1)); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la respuesta de base de datos.

Driver nativo MongoDB

78

MongoDB::__get
MongoDB::__get -- Obtiene una coleccin

Descripcin
public MongoCollection MongoDB::__get ( string $name ) sta es la forma ms fcil de obtener uan coleccin a partir de un objeto de base de datos. Si el nombre de la coleccin contiene caracteres extraos, se usar en su lugar MongoDB::selectCollection().
<?php $mongo = new Mongo(); // las dos siguientes lneas son equivalentes $collection = $mongo->selectDB("foo")->selectCollection("bar"); $collection = $mongo->foo->bar; ?>

Parmetros
name

Nombre de la coleccin.

Valores devueltos
Devuelve la coleccin.

Driver nativo MongoDB

79

MongoDB::getDBRef
MongoDB::getDBRef -- Captura el documento que est siendo apuntado por una referencia de base de datos

Descripcin
public array MongoDB::getDBRef ( array $ref )

Parmetros
ref

Referencia de base de datos.

Valores devueltos
Devuelve el documento apuntado por la referencia.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::getDBRef() Ejemplo que demuestra cmo obtener una referencia a una base de datos y cules son los datos de entrada esperados.
<?php $ref = array( '$ref' => 'profiles', '$id' => '47cc67093475061e3d9536d2' ); $profile = $db->getDBRef($ref); ?>

Revise MongoDB::createDBRef() para ms informacin sobre cmo crear referencias a bases de datos.

Driver nativo MongoDB

80

MongoDB::getGridFS
MongoDB::getGridFS -- Obtiene un objeto para trabajar con ficheros almacenados en esta base de datos

Descripcin
public MongoGridFS MongoDB::getGridFS ( [ string $prefix = "fs" ] )

Parmetros
prefix

Prefijo de la coleccin de ficheros y bloques.

Valores devueltos
Devuelve un nuevo objeto gridfs para esta base de datos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::getGridFS() Este ejemplo muestra cmo obtener una instancia de MongoGridFS.
<?php $db = $mongo->my_db; $prefix = 'files'; $collection = $db->getGridFS($prefix); ?>

Lea ms sobre MongoGridFS para aprender cmo almacenar ficheros con MongoDB.

Driver nativo MongoDB

81

MongoDB::getProfilingLevel
MongoDB::getProfilingLevel -- Obtiene el nivel de perfilado (profiling) de la base de datos

Descripcin
public int MongoDB::getProfilingLevel ( void ) Devuelve el nivel de perfilado actual de la base de datos. El perfilador de la base de datos rastrea el tiempo de ejecucin de consultas. Si se habilita (digamos, usando MongoDB::setProfilingLevel() o por consola), puede consultar cunta consultas tardan ms que un determinado nmero de milisegundos, o el tiempo que tardan toda las consultas. Tenga presente que el perfilado ralentiza las consultas. Por eso, es mejor utilizarlo en entornos de desarrollo o de pruebas antes que en aplicaciones donde el tiempo sea crucial. Esta funcin es equivalente a:
<?php public function getProfilingLevel() { return $this->command(array('profile' => -1)); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nivel de perfilado.

Ver tambin
Documentacin de MongoDB sobre profiling y MongoDB::setProfilingLevel().

Driver nativo MongoDB

82

MongoDB::getSlaveOkay
MongoDB::getSlaveOkay -- Devuelve el valor de slaveOkay de esta base de datos

Descripcin
public bool MongoDB::getSlaveOkay ( void ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el valor de slaveOkay para esta instancia.

Driver nativo MongoDB

83

MongoDB::lastError
MongoDB::lastError -- Comprueba si hubo un error en la ltima operacin de base de datos llevada a cabo

Descripcin
public array MongoDB::lastError ( void ) Este mtodo es equivalente a:
<?php public function lastError() { return $this->command(array('getlasterror' => 1)); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el error, si lo hubo.

Ejemplos
Ejemplo #1 - Ejemplo de error NULL de MongoDB::lastError()
<?php $db->resetError(); var_dump($db->lastError()); ?>

El resultado del ejemplo sera algo similar a:

array(3) { ["err"]=> NULL ["n"]=> int(0) ["ok"]=> float(1) }

Driver nativo MongoDB

84

Ejemplo #2 - Ejemplo de error de clave duplicada con MongoDB::lastError()

<?php $c = $db->selectCollection("foo"); // insertar dos documentos con el mismo _id $c->insert(array("_id" => 1)); $c->insert(array("_id" => 1)); var_dump($db->lastError()); ?>

El resultado del ejemplo sera algo similar a:

array(3) { ["err"]=> string(64) "E11000 duplicate key errorindex: foo.foo.$_id_ }" ["n"]=> int(0) ["ok"]=> float(1) }

dup key: { : 1

Driver nativo MongoDB

85

MongoDB::listCollections
MongoDB::listCollections -- Devuelve la lista de colecciones de esta base de datos

Descripcin
public array MongoDB::listCollections ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve una lista de MongoCollections.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::listCollections() El siguiente ejemplo muestra cmo borrar cada una de las colecciones de la base de datos.
<?php $m = new Mongo(); $db = $m->selectDB("sample"); $list = $db->listCollections(); foreach ($list as $collection) { echo "borrando $collection... "; $collection->drop(); echo "se fue\n"; } ?>

El resultado del ejemplo sera algo similar a:

borrando sample.blog.posts... se fue borrando sample.critical.docs... se fue borrando sample.taxes... se fue ...

Driver nativo MongoDB

86

MongoDB::prevError
MongoDB::prevError -- Comprueba el ltimo error emitido durante una operacin de base de datos

Descripcin
public array MongoDB::prevError ( void ) En general, se recomienda utilizar MongoDB::lastError() en lugar de este mtodo. Este mtodo devuelve el ltimo error de base de datos que tuvo lugar, y hace cuntas operaciones sucedi. Ha quedado prcticamente obsoleto.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el error y hace cuntas operaciones sucedi.

Driver nativo MongoDB

87

MongoDB::repair
MongoDB::repair -- Repara y compacta esta base de datos

Descripcin
public array MongoDB::repair ( [ bool $preserve_cloned_files = FALSE [, bool $ backup_original_files = FALSE ] ] ) Crea una nueva copia de todos los datos de la base de datos. Eliminar cualquier dato corrupto y la compactar y aumentar los trampos vacos que encuentre. Esta operacin es muy lenta en bases de datos extensas. Generalmente se ejecuta desde la consola o desde la lnea de comandos, y no por el driver. Es equivalente a la funcin:
<?php public function repair() { return $this->command(array('repairDatabase' => 1)); } ?>

Parmetros
preserve_cloned_files

Indica si los ficheros clonados deben mantenerse cuando la reparacin falle.

backup_original_files

Si se debe guardar una copia de seguridad de los ficheros originales.

Valores devueltos
Devuelve la respuesta de la base de datos.

Ver tambin
Documentacin de MongoDB sobre reparacin.

Ejemplos

Driver nativo MongoDB

88

Ejemplo #1 - Ejemplo de MongoDB::repair() Este ejemplo muestra cmo reparar y compactar una base de datos.
<?php $db = $mongo->foo; $response = $db->repair(); print_r($response); ?>

El resultado del ejemplo sera algo similar a:

Array ( [ok] => 1 )

Driver nativo MongoDB

89

MongoDB::resetError
MongoDB::resetError -- Limpia cualquier error de la base de datos que se haya apuntado

Descripcin
public array MongoDB::resetError ( void ) Generalmente, este mtodo no se utiliza. Reinicia el seguimiento de errores de la base de datos (que puede ser incrementado con MongoDB::forceError(), que tampoco se utiliza normalmente). Es equivalente a ejecutar:
<?php public function resetError() { return $this->command(array('reseterror' => 1)); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la respuesta de la base de datos.

Driver nativo MongoDB

90

MongoDB::selectCollection
MongoDB::selectCollection -- Obtiene una coleccin

Descripcin
public MongoCollection MongoDB::selectCollection ( string $name )

Parmetros
name

Nombre de la coleccin.

Valores devueltos
Devuelve la coleccin.

Driver nativo MongoDB

91

MongoDB::setProfilingLevel
MongoDB::setProfilingLevel -- Establece el nivel de perfilado (profiling) de la base de datos

Descripcin
public int MongoDB::setProfilingLevel ( int $level ) Modifica el nivel actual de profiling de la base de datos. Esta funcin es equivalente a:
<?php public function setProfilingLevel($level) { return $this->command(array('profile' => $level)); } ?>

Las opciones de niveles son 0 (deshabilitado), 1 (consultas de ms de 100ms), y 2 (todas las consultas). Si se deseara perfilar tan slo las consultas que llevan ms que otro periodo de tiempo, utilice el comando de base de datos con un segundo parmetro: el nmero de milisegundos. Por ejemplo, para perfil todas las consultas que llevan ms de on segundo, ejecute:
<?php $result = $this->command(array('profile' => 1, 'slowms' => 1000)); ?>

Las consultas perfiladas aparecern en la coleccin system.profile de esta base de datos.

Parmetros
level

Nivel de perfilado.

Valores devueltos
Devuelve el valor anterior del nivel de perfilado.

Driver nativo MongoDB

92

MongoDB::setSlaveOkay
MongoDB::setSlaveOkay -- Cambiar el valor de slaveOkay de esta base de datos

Descripcin
public bool MongoDB::setSlaveOkay ( [ bool $ok = true ] ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.

Parmetros
ok

Indica si las lecturas deben enviarse a miembros secundarios de un conjunto de rplicas para todas las posibles consultas que se realicen con esta instancia de MongoDB.

Valores devueltos
Devuelve el valor anterior de slaveOkay de esta instancia.

Driver nativo MongoDB

93

MongoDB::__toString
MongoDB::__toString -- Nombre de esta base de datos

Descripcin
public string MongoDB::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nombre de esta base de datos.

Driver nativo MongoDB

94

Clase MongoCollection

Introduccin
Representa una coleccin de base de datos. Los nombres de colecciones pueden usar cualquier carcter del cdigo ASCII. Algunos ejemplos de nombres vlidos de colecciones son "", "...", "mi coleccion", y "*&#@". Los nombres de colecciones definidos por usuario no pueden contener el smbolo $. Existen colecciones del sistema que utilizan $ en sus nombres (p.ej., local.oplog.$main), pero es un carcter reservado. Si se intentara crear y usar una coleccin que incluya $ en su nombre, MongoDB lo notificar.

Clases sinopsis

MongoCollection

MongoCollection { /* Constantes */ const int MongoCollection::ASCENDING = 1; const int MongoCollection::DESCENDING = -1; /* Campos */ public MongoDB db = NULL; public integer w; public integer wtimeout; /* Mtodos */ public mixed MongoCollection::batchInsert ( array $a [, array $options = array() ] ) public MongoCollection::__construct ( MongoDB $db, string $name ) public int MongoCollection::count ( [ array $query = array() [, int $limit = 0 [, int $ skip = 0 ] ] ] )

Driver nativo MongoDB

95

public array MongoCollection::createDBRef ( array $a ) public array MongoCollection::deleteIndex ( string|array $keys ) public array MongoCollection::deleteIndexes ( void ) public array MongoCollection::drop ( void ) public bool MongoCollection::ensureIndex ( array $keys [, array $options = array() ]) public MongoCursor MongoCollection::find ( [ array $query = array() [, array $ fields = array() ] ] ) public array MongoCollection::findOne ( [ array $query = array() [, array $fields = array() ] ] ) public MongoCollection MongoCollection::__get ( string $name ) public array MongoCollection::getDBRef ( array $ref ) public array MongoCollection::getIndexInfo ( void ) public string MongoCollection::getName ( void ) public bool MongoCollection::getSlaveOkay ( void ) public array MongoCollection::group ( mixed $keys, array $initial, MongoCode $ reduce [, array $options = array() ] ) public mixed MongoCollection::insert ( array $a [, array $options = array() ] ) public mixed MongoCollection::remove ( [ array $criteria = array() [, array $ options = array() ] ] ) public mixed MongoCollection::save ( array $a [, array $options = array() ] ) public bool MongoCollection::setSlaveOkay ( [ bool $ok = true ] ) public string MongoCollection::__toString ( void ) public bool MongoCollection::update ( array $criteria, array $newobj [, array $ options = array() ] ) public array MongoCollection::validate ( [ bool $scan_data = FALSE ] ) }

Constantes predefinidas
MongoCollection::ASCENDING 1 Sentido ascendente en ordenaciones y creaciones de ndices. Driver nativo MongoDB 96

MongoCollection::DESCENDING -1 Sentido descendente para ordenaciones y creaciones de ndices.

Campos
db La base de datos "padre" de esta coleccin. w Nmero de servidores a los que replicar un cambio antes de confirmar xito. Este valor se hereda de la base de datos padre. La clase MongoDB indica de forma ms detallada cmo funciona w. wtimeout Nmero de milisegundos a esperar a que las operaciones se realicen en las $this->w rplicas. Este valor se hereda de la base de datos padre. La clase MongoDB indica de forma ms detallada cmo funciona wtimeout.

Ver tambin
Documentacin principal de MongoDB sobre collections.

Driver nativo MongoDB

97

MongoCollection::batchInsert
MongoCollection::batchInsert -- Inerta mltiples documentos en esta coleccin

Descripcin
public mixed MongoCollection::batchInsert ( array $a [, array $options = array() ] )

Parmetros
a

Array de arrays.
options

Opciones de insercin. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos, y en caso de que la insercin no tenga xito, emitir una excepcin de tipo MongoCursorException. Si safe fuera un entero, replicar la insercin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espra; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la insercin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una insercin segura (safe) y sobrescribir el ajuste safe a FALSE.

Valores devueltos
Si "safe" est habilitado, devuelve un array asociativo con el estado de las inserciones ("ok") y con cualquier error que pudiera haber sucedido ("err"). En cualquier otro caso, devuelve TRUE si la operacin por lotes se envi con xito, o FALSE en caso contrario.

Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" estuviera habilitada y la insercin fallara. Lanza MongoCursorTimeoutException si la opcin "safe" tuviera un valor mayor que uno, y la base de datos no pudiera replicar la operacin en MongoCollection::$wtimeout milisegundos.

Historial de cambios

Driver nativo MongoDB

98

Versin 1.0.5 1.0.9

Descripcin Aadido el parmetro "options". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync".

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::batchInsert() Las inserciones por lotes son una forma rpida de aadir muchos elementos a la base de datos
<?php $users = array(); for ($i = 0; $i<100; $i++) { $users[] = array('username' => 'user'.$i, 'i' => $i); } $mongo = new Mongo(); $collection = $mongo->my_db->users; $collection->drop(); $collection->batchInsert($users); foreach ($users as $user) { echo $user['_id']."\n"; // completado con instanceof MongoId } $users = $collection->find()->sort(array('i' => 1)); foreach ($users as $user) { var_dump($user['username']); } ?>

El resultado del ejemplo sera algo similar a:

4bf43ac68ead0e1971000000 4bf43ac68ead0e1971010000 4bf43ac68ead0e1971020000 ... string(5) "user1" string(5) "user2" string(5) "user3" ...

Driver nativo MongoDB

99

MongoCollection::__construct
MongoCollection::__construct -- Crea una nueva coleccin

Descripcin
public MongoCollection::__construct ( MongoDB $db, string $name )

Parmetros
MongoDB db Base de datos padre.
name

Nombre de esta coleccin.

Valores devueltos
Devuelve un nuevo objeto de tipo coleccin.

Errores/Excepciones
Si el nombre no fuera vlido, emite una excepcin por defecto.

Driver nativo MongoDB

100

MongoCollection::count
MongoCollection::count -- Cuenta el nmero de documentos de esta coleccin

Descripcin
public int MongoCollection::count ( [ array $query = array() [, int $limit = 0 [, int $skip = 0]]])

Parmetros
query

Array asociativo u objeto con los campos que deben coincidir.

limit

Especifica una cota superior del nmero devuelto.

skip

Especifica el nmero de resultados a partir del cual se ignorarn.

Valores devueltos
Devuelve el nmero de documentos que coinciden con la consulta.

Historial de cambios

Versin 1.0.7

Descripcin Aadidos los parmetros limit y skip.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::count()
<?php $collection->insert(array('x'=>1)); $collection->insert(array('x'=>2)); $collection->insert(array('x'=>3)); var_dump($collection->count()); var_dump($collection->count(array('x'=>1)));

Driver nativo MongoDB

101

?>

El resultado del ejemplo sera algo similar a:

int(3) int(1)

Driver nativo MongoDB

102

MongoCollection::createDBRef
MongoCollection::createDBRef -- Crea una referencia a una base de datos

Descripcin
public array MongoCollection::createDBRef ( array $a )

Parmetros
a

Objeto al que crear una referencia.

Valores devueltos
Devuelve un array de referencia a base de datos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::createDBRef
<?php $canciones = $db->canciones; $listasDeReproduccion = $db->listasdereproduccion; // crea una referencia a una cancin $manamana = $songs->findOne(array('titulo' => 'Ma na ma na')); $refACancioin = $songs->createDBRef($manamana); // aade la referencia a mi lista de reproduccin $listasDeReproduccion->update(array('usuario' => 'yo'), array('$push' => array('listadecanciones' => $refToSong))); ?>

Ver tambin

MongoCollection::getDBRef

Driver nativo MongoDB

103

MongoCollection::deleteIndex
MongoCollection::deleteIndex -- Elimina un ndice de esta coleccin

Descripcin
public array MongoCollection::deleteIndex ( string|array $keys ) Este mtodo es identico a:
<?php public function deleteIndexes($keys) { // toIndexString es un mtodo 'protected' que convierte los strings, arrays, y objetos // en nombres de ndices $index = $this->toIndexString($keys); return $this->db->command(array("deleteIndexes" => $this->getName(), "index" => $index); } ?>

Cuando se crea un ndice, se le asigna un nombre nico. Generalmente, ser establecido por el usuario (con la opcin "name" de MongoCollection::ensureIndex() ) o generado por el driver a partir de una combinacin de nombres de clave y de direcciones. Usaremos despus este nombre con MongoCollection::deleteIndex() para eliminar el ndice. Desafortunadamente, el mtodo MongoCollection::ensureIndex() genera nombres ligeramente diferentes a los que crea la shell y, por motivos de retro-compatibilidad, MongoCollection::deleteIndex() no puede eliminar ndices con nombres creados a medida. Por esa reazn, la mejor forma de eliminar ndices creados por la shell o con nombres a medida, es llamar directamente al comando de la base de datos deleteIndexes. De esta forma, si se quisiera eliminar un ndice al que llamamos "superfast query", lo haramos as:
<?php $db->command(array("deleteIndexes" => $collection->getName(), "index" => "superfast query"); ?>

Para averiguar cmo se llama un ndice, puede consultar coleccin system.indexes de una base de datos y analizar el campo name (nombre).

Parmetros
keys

Driver nativo MongoDB

104

Campo o campos en los que eliminar el ndice.

Valores devueltos
Devuelve la respuesta de la base de datos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::deleteIndex() Este ejemplo ilustra cmo pasar tanto un stringo como un array a la funcin.
<?php $m = new Mongo(); $c = $m->example->indices; // crea un ndice $c->ensureIndex(array("i"=>1)); // elimina un ndice $c->deleteIndex("i");

// crea un ndice multi-clave $c->ensureIndex(array("j" => 1, "k" => 1)); // elimina un ndice multi-clave $c->deleteIndex(array("j" => 1, "k" => 1)); ?>

Driver nativo MongoDB

105

MongoCollection::deleteIndexes
MongoCollection::deleteIndexes -- Elimina todos los ndices de esta coleccin

Descripcin
public array MongoCollection::deleteIndexes ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la respuesta de la base de datos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::deleteIndexes() Este ejemplo demuestra cmo eliminar todos los ndices de una coleccin, y muestra tambin la respuesta esperada.
<?php $collection = $mongo->my_db->articles; $response = $collection->deleteIndexes(); print_r($response); ?>

El resultado del ejemplo sera algo similar a:

Array ( [nIndexesWas] => 1 [msg] => all indexes deleted for collection [ok] => 1 )

Driver nativo MongoDB

106

MongoCollection::drop
MongoCollection::drop -- Borra esta coleccin

Descripcin
public array MongoCollection::drop ( void ) Borra esta coleccin y elimina sus ndices.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la respuesta de la base de datos.

Ejemplos
Ejemplo #1 - MongoCollection::drop() example Este ejemplo demuestra cmo borrar una coleccin, y muestra tambin la respuesta esperada.
<?php $collection = $mongo->my_db->articles; $response = $collection->drop(); print_r($response); ?>

El resultado del ejemplo sera algo similar a:

Array ( [nIndexesWas] => 1 [msg] => all indexes deleted for collection [ns] => my_db.articles [ok] => 1 )

Driver nativo MongoDB

107

MongoCollection::ensureIndex
MongoCollection::ensureIndex -- Crea un ndice en el campo o cmapos dados, o si el ndice ya existe, no realiza nada.

Descripcin
public bool MongoCollection::ensureIndex ( array $keys [, array $options = array() ] ) No se puede crear un ndice nico sobre un campo si varios documentos ya existentes no contienen a este campo. En estos documentos el campo sera NULL y, por tanto, no sera nico.

Parmetros
keys

Campo o campos a usar como ndice.

options

Este parmetro es un array asociativo de la forma array("nombredeopcion" => <boolean>, ...). Las opciones soportadas actualmente son: "unique" Crea un ndice nico. "dropDups" Si se estuviera creando un ndice nico, y existieran valores duplicados, borrar todos excepto uno de ellos. "background" Si se estuviera usando MongoDB versin 1.3.2 o superior, se podrn crear ndices de fondo mientras se realiza otras operaciones. Por omisin, la creacin de ndices sucede de forma sncrona. Si se especifica TRUE en esta opcin, la creacin de ndices ser asncrona. "safe" Desde la versin 1.0.4 del driver, se puede indicar mediante un booleano si se comprobar si ha habido o no xito creando el ndice. Si fallara la creacin del ndice, el driver emitira una excepcin de tipo MongoCursorException. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. "name" Desde la versin 1.0.4 del driver (SIN incluir 1.0.4) se puede especificar un nombre de ndice. Puede ser til cuando se indexan muchas claves y Mongo se queja de que los nombres de ndices son demasiado largos. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo

Driver nativo MongoDB

108

de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.

Valores devueltos
Devuelve TRUE.

Historial de cambios

Versin 1.2.0 1.0.11

Descripcin Aadida la opcin timeout. "safe" emitir fallos del maestro, cuando proceda. Se lanza MongoException si el nombre de ndice (generado o asignado) es superior a 128 bytes. Cambiado el parmetro "options" de booleano a array. Antes de 1.0.2, el segundo parmetro era un valor booleano opcional que especificaba un ndice nico.

1.0.11

1.0.2

Errores/Excepciones
Lanza MongoException si el nombre de ndice es superior a 128 bytes. (Versin 1.0.11+) Lanza MongoCursorException si la opcin "safe" est habilitada y falla la creacin del ndice. Lanza MongoCursorTimeoutException si la opcin "safe" est habilitada y la operacin lleva ms de MongoCursor::$timeout milisegundos para ser completada. Esto no paraliza la operacin en el servidor, es slo un lmite de tiempo en el lado del cliente.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::ensureIndex()
<?php $c = new MongoCollection($db, 'foo'); // crea un ndice en 'x' ascendente

Driver nativo MongoDB

109

$c->ensureIndex(array('x' => 1)); // crea un ndice en 'z' ascendente y en 'zz' descendente $c->ensureIndex(array('z' => 1, 'zz' => -1)); // crea un ndice nico en 'x' $c->ensureIndex(array('x' => 1), array("unique" => true)); ?>

Ejemplo #2 - Ejemplo de borrado de duplicados

<?php $collection->insert(array("username" => "joeschmoe")); $collection->insert(array("username" => "joeschmoe")); /* * falla la creacin del ndice; no se puede crear un ndice nico en una clave que no tiene * valores nicos */ $collection->ensureIndex(array("username" => 1), array("unique" => 1)); /* * xito al crear ndice: se ha eliminado uno de los documentos de la coleccin */ $collection->ensureIndex(array("username" => 1), array("unique" => 1, "dropDups" => 1)); /* * ahora tenemos un ndice nico, por lo que las inserciones con el mismo username (como el * anterior) fallarn */ $collection->insert(array("username" => "joeschmoe")); ?>

Ejemplo #3 - Indexacin Geoespacial Mongo soporta ndices geoespaciales, que permiten buscar documentos cercanos a una determinada localizacin o que estn dentro de una determinada forma. Por ejemplo, para crear un ndice geoespacial en el campo "loc":
<?php $collection->ensureIndex(array("loc" => "2d")); ?>

Ver tambin
Driver nativo MongoDB 110

Documentacin de MongoDB sobre -ndices por defecto y sobre -ndices geoespaciales.

Driver nativo MongoDB

111

MongoCollection::find
MongoCollection::find -- Realiza una consulta a la coleccin

Descripcin
public MongoCursor MongoCollection::find ( [ array $query = array() [, array $fields = array() ] ] )

Parmetros
query

Campos en los que buscar.

fields

Campos del resultado que se devolvern.

Valores devueltos
Devuelve un cursor para el resultado de la bsqueda.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::find() Este ejemplo muestra como buscar en un rango.
<?php // buscar documentos donde 5 < x < 20 $rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 )); $cursor = $collection->find($rangeQuery); ?>

Revise MongoCursor para ms informacin sobre cmo trabajar con cursores.

Ejemplo #2 - Ejemplo de MongoCollection::find() usando $where Este ejemplo demuestra cmo buscar en una coleccin usando cdigo javascript para reducir el conjunto de resultados.
<?php

Driver nativo MongoDB

112

$coleccion = $db->mi_bd->articulos; $js = "function() { return this.type == 'paginadeinicio' || this.destacado == true; }"; $articulos = $coleccion->find(array('$where' => $js)); ?>

Ejemplo #3 - Ejemplo de MongoCollection::find() usando $in Este ejemplo demuestra cmo buscar una coleccin usando el operador $in.
<?php $coleccion = $db->mi_bd->articulos; $articulos = $coleccion->find(array( 'tipo' => array('$in' => array('paginadeinicio', 'editorial')) )); ?>

Ejemplo #4 - Obteniendo resultados en forma de array Devuelve un MongoCursor. A menudo, la gente que empiza, se siente ms cmoda usando arrays. Para convertir un cursor en un array, utilice la funcin iterator_to_array().
<?php $cursor = $coleccion->find(); $array = iterator_to_array($cursor); ?>

Al usar iterator_to_array() se fuerza a que el driver cargue todos los resultados en memoria. No lo use cuando el resultado supere el tamao mximo de memoria! Adems, algunas colecciones del sistema no tienen un campo _id. Si se est trabajando con colecciones que pudieran tener documentos sin _id s, establezca FALSE en el segundo argumento de iterator_to_array() (as, no tratar de usar como clave el valor del campo _id inexistente).

Ver tambin
Documentacin de MongoDB sobre find.

Driver nativo MongoDB

113

MongoCollection::findOne
MongoCollection::findOne -- Realiza una consulta a esta coleccin, devolviendo slo un elemento

Descripcin
public array MongoCollection::findOne ( [ array $query = array() [, array $fields = array() ] ] )

Parmetros
query

Campos a los que consultar.

fields

Campos del resultado que devolver.

Valores devueltos
Devuelve el registro que coincide con la bsqueda, o NULL.

Errores/Excepciones
Si no se pudiera acceder a la base de datos, lanzara una excepcin de tipo MongoConnectionException.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::findOne buscando por id. Este ejemplo muestra cmo buscar un documento en una coleccin a partir de su id.
<?php $articulos = $mongo->mi_bd->articulos; $articulo = $articulos->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2'))); ?>

Driver nativo MongoDB

114

Ejemplo #2 - Ejemplo de MongoCollection::findOne a partir de una condicin. Este ejemplo muestra como buscar un documento en una coleccin a partir de una condicin, limitando los campos devueltos.
<?php $usuarios = $mongo->mi_bd->usuarios; $usuario = $usuarios->findOne(array('nombreusuario' => 'jwage'), array('password')); print_r($usuario); ?>

El resultado del ejemplo sera algo similar a:

Array ( [_id] => MongoId Object ( ) [password] => test )

Fjese que, incluso si el documento no contiene un campo nombreusuario, hemos limitado los resultados para que nicamente contengan el campo password.

Driver nativo MongoDB

115

MongoCollection::__get
MongoCollection::__get -- Obtiene una coleccin

Descripcin
public MongoCollection MongoCollection::__get ( string $name ) Forma concisa de obtener una coleccin con un nombre separado por el carcter punto. Si el nombre de coleccin contuviera caracteres extraos, se debera utilizar en su lugar MongoDB::selectCollection().
<?php $mongo = new Mongo(); // las dos siguientes sentencias son equivalentes $collection = $mongo->selectDB("foo")->selectCollection("bar.baz"); $collection = $mongo->foo->bar->baz; ?>

Parmetros
name

Siguiente string en el nombre de la coleccin.

Valores devueltos
Devuelve la coleccin.

Driver nativo MongoDB

116

MongoCollection::getDBRef
MongoCollection::getDBRef -- Captura el documento al que apunta una referencia de base de datos

Descripcin
public array MongoCollection::getDBRef ( array $ref )

Parmetros
ref

Referencia a una base de datos.

Valores devueltos
Devuelve el documente de base de datos al que apunta esta referencia.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::getDBRef
<?php $listasdereproduccion = $db->listasdereproduccion; $miLista = $listasdereproduccion->findOne(array('usuario' => 'yo')); // capturar cada cancin de la lista de reproduccin foreach ($miLista['listacancion'] as $refCancion) { $cancion = $listasdereproduccion->getDBRef($refCancion); echo $cancion['titulo'] . "\n"; } ?>

El resultado del ejemplo sera algo similar a:

Dazed and Confused Ma na ma na Bohemian Rhapsody

En el ejemplo anterior cada $refCancion ser similar a lo siguiente: Array ( [$ref] => canciones [$id] => 49902cde5162504500b45c2c )

Driver nativo MongoDB

117

Ver tambin

MongoCollection::createDBRef

Driver nativo MongoDB

118

MongoCollection::getIndexInfo
MongoCollection::getIndexInfo -- Devuelve un array con los nombres de ndices de esta coleccin

Descripcin
public array MongoCollection::getIndexInfo ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve una lista de nombres de ndices.

Driver nativo MongoDB

119

MongoCollection::getName
MongoCollection::getName -- Devuelve el nombre de esta coleccin

Descripcin
public string MongoCollection::getName ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nombre de esta coleccin.

Ejemplos

Ejemplo #1 - Ejemplo de MongoCollection::getName()

<?php $m = new Mongo(); $c = $m->foo->bar->baz; echo "Trabajando con la coleccin " . $c->getName() . ".\n"; // El espacio de nombres completo viene dado por el mtodo MongoCollection::__toString() echo "Trabajando en el espacio de nombres $c.\n"; ?>

El resultado del ejemplo sera algo similar a:

Trabajando con la coleccin bar.baz. Trabajando en el espacio de nombres foo.bar.baz.

Driver nativo MongoDB

120

MongoCollection::getSlaveOkay
MongoCollection::getSlaveOkay -- Consulta el valor de slaveOkay de esta coleccin

Descripcin
public bool MongoCollection::getSlaveOkay ( void ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el valor de slaveOkay para esta instancia.

Driver nativo MongoDB

121

MongoCollection::group
MongoCollection::group -- Lleva a cabo una operacin similar al comando GROUP BY de SQL

Descripcin
public array MongoCollection::group ( mixed $keys, array $initial, MongoCode $ reduce [, array $options = array() ] )

Parmetros
keys

Campos a agrupar. Si se pasa un array o un objeto que no es de cdigo, ser la clave usada para agrupar resultados. 1.0.4+: Si keys es una instancia de MongoCode, keys ser tratado como una funcin que devuelve la clave con la que agrupar (revise el ejemplo de abajo sobre "Pasando una funcin a keys ").
initial

Valor inicial del objeto contador combinado.

reduce

Una funcin que toma dos argumentos (el documento actual y la agregacin en este punto) y realiza la agregacin.
options

Parmetros opcionales para el comando group. Las opciones vlidas incluyen: "condition" Condicin para incluir un documento a la agregacin. "finalize" Funcin que se invoca por cada clave nica que toma la salida de la funcin reduce.

Valores devueltos
Devuelve un array que contiene el resultado.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::group() Agrupa los documentos por categora y crea una lista de los nombres que hay dentro de la categora.
<?php

Driver nativo MongoDB

122

$collection->insert(array("categoria" $collection->insert(array("categoria" $collection->insert(array("categoria" $collection->insert(array("categoria" $collection->insert(array("categoria" $keys = array("categoria" => 1); $initial = array("items" => array());

=> => => => =>

"fruta", "nombre" => "manzana")); "fruta", "nombre" => "melocoton")); "fruta", "nombre" => "platano")); "verdura", "nombre" => "maiz")); "verdura", "nombre" => "brocoli"));

$reduce = "function (obj, prev) { prev.items.push(obj.nombre); }"; $g = $collection->group($keys, $initial, $reduce); echo json_encode($g['retval']); ?>

El resultado del ejemplo sera algo similar a:

[{"categoria":"fruta","items":["manzana","melocoton","platano"]},{"categoria ":"verdura","items":["maiz","brocoli"]}]

Ejemplo #2 - Ejemplo de MongoCollection::group() Este ejemplo no utiliza ninguna clave, por lo que cada documento ser su propio grupo. Adems, usa una condicin: slo los documentos que la cumplan, sern procesados por la funcin de agrupacin.
<?php $collection->save(array("a" => 2)); $collection->save(array("b" => 5)); $collection->save(array("a" => 1)); // usar todos los campos $claves = array(); // establecer valores iniciales $inicial = array("count" => 0); // funcin JavaScript a realizar $reduce = "function (obj, prev) { prev.count++; }"; // usar slo los documentos donde el campo "a" es mayor que 1 $condicion = array("a" => array( '$gt' => 1)); $g = $collection->group($claves, $inicial, $reduce, $condicion); var_dump($g); ?>

El resultado del ejemplo sera algo similar a:

Driver nativo MongoDB

123

array(4) { ["retval"]=> array(1) { [0]=> array(1) { ["count"]=> float(1) } } ["count"]=> float(1) ["claves"]=> int(1) ["ok"]=> float(1) }

Ejemplo #3 - Pasando una funcin a keys Si se desea agrupar por algo distinto a un nombre de campo, se puede pasar una funcin como primer parmetro de MongoCollection::group() y se ejecutar con cada documento. Se usar el valor devuelto de la funcin como valor de agrupacin. Este ejemplo demuestra cmo agrupar por el campo num mdulo 4 (num % 4).
<?php $c->group(new MongoCode('function(doc) { return {mod : doc.num % 4}; }'), array("count" => 0), new MongoCode('function(current, total) { total.count++; }')); ?>

Driver nativo MongoDB

124

MongoCollection::insert
MongoCollection::insert -- Inserta un array en la coleccin

Descripcin
public mixed MongoCollection::insert ( array $a [, array $options = array() ] ) Todas las cadenas de texto que se enven a la base de datos deben estar en UTF-8. Si un string no estuviera en UTF-8, se lanzara una excepcin MongoException. Para insertar (o para consultar) un texto que no sea UTF-8, utilice MongoBinData.

Parmetros
a

Un array.
options

Opciones de insercin. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos, y en caso de que la insercin no tenga xito, emitir una excepcin de tipo MongoCursorException. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la insercin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la insercin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una insercin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.

Valores devueltos

Driver nativo MongoDB

125

Si safe est habilitado, devuelve un array con el estado de la insercin. En cualquier otro caso, devuelve un booleano indicando si el array no estaba vaco (un array vaco no se insertar).

Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" estuviera habilitada y fallara la insercin. (Versin 1.0.1+) Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y la operacin llevara ms de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.

Historial de cambios

Versin 1.0.5

Descripcin Cambiado el segundo parmetro a un array de opciones. Antes de 1.0.5, el segundo parmetro era un booleano indicando la opcin "safe". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".

1.0.9

1.0.11

1.2.0

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::insert() con _id Al insertar un objeto se le aadir un campo _id, a no ser que se pase por referencia.
<?php $a = array('x' => 1); $collection->insert($a); var_dump($a); $b = array('x' => 1); $ref = &$b; $collection->insert($ref); var_dump($ref);

Driver nativo MongoDB

126

?>

El resultado del ejemplo sera algo similar a:

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

Ejemplo #2 - Ejemplo de MongoCollection::insert() safe Este ejemplo muestra cmo al insertar dos elementos con el mismo _id, se provoca que se lance una excepcin MongoCursorException, ya que safe est habilitado.
<?php $persona = array("nombre" => "Joe", "edad" => 20); $coleccion->insert($persona, true); // ahora $person tiene un campo _id, as que si intentamos guardarlo // de nuevo, obtendremos una excepcin try { $colecction->insert($persona, true); } catch(MongoCursorException $e) { echo "No se puede guardar dos veces la misma persona!\n"; } ?>

Ver tambin
Documentacin de MongoDB sobre insert.

Driver nativo MongoDB

127

MongoCollection::remove
MongoCollection::remove -- Eliminar registros de esta coleccin

Descripcin
public mixed MongoCollection::remove ( [ array $criteria = array() [, array $options = array() ] ] )

Parmetros
criteria

Descripcin de los registros que se eliminarn.

options

Opciones de eliminacin. "justOne" Eliminar solamente uno de los registros que cumplan las condiciones. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos y emitira una excepcion MongoCursorException si la eliminacin no tuviera xito. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la eliminacin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la eliminacin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una eliminacin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.

Valores devueltos
Si "safe" est habilitado, devuelve un array asociativo con el estado de la eliminacin ("ok"), el nmero de elementos eliminados ("n"), y cualquier error que pudiera haber Driver nativo MongoDB 128

ocurrido ("err"). En cualquier otro caso, si la eliminacin se hubiera realizado con xito devuelve TRUE, o FALSE en caso contrario.

Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" est habilitada y la eliminacin falla. Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y la operacin llevara ms de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.

Historial de cambios

Versin 1.0.9

Descripcin Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Cambiado el segundo parmetro a un array de opciones. Antes de 1.0.5, el segundo parmetro era un booleano indicando la opcin "justOne" y no haba opcin "safe". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".

1.0.5

1.0.11

1.2.0

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::remove() con justOne
<?php $radioactivo = $db->radioactivo; // contar cunto plution queda $restante = $radioactivo->count(array('type' => 94)); $vidamedia = $restante/2; // eliminar la mitad while ($vidamedia > 0) { $radioactivo->remove(array('type' => 94), array("justOne" => true)); $vidamedia--; }

Driver nativo MongoDB

129

?>

Ver tambin
Documentacin de MongoDB sobre remove.

Driver nativo MongoDB

130

MongoCollection::save
MongoCollection::save -- Guarda un objeto en esta coleccin

Descripcin
public mixed MongoCollection::save ( array $a [, array $options = array() ] ) Si el objeto fuera de la base de datos, se actualizara. En caso contrario, se insertara.

Parmetros
a

Array a guardar.
options

Opciones de guardado. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos y emitira una excepcion MongoCursorException si la insercin no tuviera xito. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la insercin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la insercin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una insercin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.

Valores devueltos
Si safe estuviera habilitado, devolvera un array que contiene el estado de la escritura. En cualquier otro caso, devuelve un booleano que representa si el array no estaba vaco (un Driver nativo MongoDB 131

array vaco no se insertar).

Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" est habilitada y fallara al guardar. Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y a la operacin llevara ms de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.

Historial de cambios

Versin 1.0.5 1.0.9

Descripcin Aadido el parmetro "options". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".

1.0.11

1.2.0

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::save()
<?php $obj = array('x' => 1); // insertar $obj en la base de datos $collection->save($obj); // aadir otro campo $obj['foo'] = 'bar'; // $obj no puede insertarse de nuevo; provoca un error de _id duplicado $collection->insert($obj); // la funcin save actualiza $obj con el nuevo campo $collection->save($obj); ?>

Driver nativo MongoDB

132

MongoCollection::setSlaveOkay
MongoCollection::setSlaveOkay -- Cambia el valor de slaveOkay de esta coleccin

Descripcin
public bool MongoCollection::setSlaveOkay ( [ bool $ok = true ] ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.

Parmetros
ok

Indica si las lecturas deben enviarse a miembros secundarios del conjunto de rplicas para todas las posibles consultas que utilicen esta instancia de MongoCollection.

Valores devueltos
Devuelve el valor anterior de slaveOkay de esta instancia.

Driver nativo MongoDB

133

MongoCollection::__toString
MongoCollection::__toString -- Representacin en forma de string de esta coleccin

Descripcin
public string MongoCollection::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nombre completo de esta coleccin.

Ejemplos

Ejemplo #1 - Ejemplo de MongoCollection::__toString()

<?php $m = new Mongo(); $c1 = $m->foo->bar->baz; echo "Trabajando con la coleccin $c1."; $c2 = $m->selectCollection('[]', '&'); echo "Trabajando con la coleccin $c2."; ?>

El resultado del ejemplo sera algo similar a:

Trabajando con la coleccin foo.bar.baz. Trabajando con la coleccin [].&.

Driver nativo MongoDB

134

MongoCollection::update
MongoCollection::update -- Actualizar registros basndose en los criterios proporcionados

Descripcin
public bool MongoCollection::update ( array $criteria, array $newobj [, array $options = array() ] )

Parmetros
criteria

Descripcin de los objetos a actualizar.

newobj

El objeto con el que actualizar los registros que cumplan las condiciones.
options

Este parmetro es un array asociativo de la forma array("optionname" => <boolean>, ...). Las opciones soportadas actualmente son: "upsert" Si ningn documento cumplira las condiciones de $criteria, se creara un nuevo documento a partir de $criteria y $newobj (revise ms abajo el ejemplo de upsert). "multiple" Todos los documentos que cumplan las condiciones de $criteria se actualizarn. MongoCollection::update() tiene exactamente el comportamiento contrario que MongoCollection::remove(): de forma predeterminada, actualiza slo un documento, no todos los que cumplan las condiciones. Se recomienda especificar siempre se si deben actualizar mltiples documentos o un nico documento, ya que el comportamiento predeterminado de la base de datos podra cambiar en el futuro. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos y emitira una excepcion MongoCursorException si la insercin no tuviera xito. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la actualizacin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la actualizacin se sincronice

Driver nativo MongoDB

135

en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una actuaizacin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.

Valores devueltos
Devuelve un booleano indicando si la actualizacin se envi o no con xito a la base de datos.

Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" estuviera habilitada y la actualizacin fallara. Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y a la operacin llevara ms de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.

Historial de cambios

Versin 1.0.1

Descripcin Cambiado el parmetro "opciones" de un booleano a un array. Antes de 1.0.1, el segundo parmetro era un booleano opcional cuyo valor indicaba si era o no upsert. Aadida la opcin "safe". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".

1.0.5 1.0.9

1.0.11

1.2.0

Ejemplos
Driver nativo MongoDB 136

Ejemplo #1 - MongoCollection::update() Aadiendo el campo direccin a un documento

<?php $c->insert(array("nombre" => "Pedro", "apellido" => "Ruiz" )); $nuevosdatos = array('$set' => array("direccion" => "Calle Juan, 1")); $c->update(array("nombre" => "Pedro"), $nuevosdatos); var_dump($c->findOne(array("nombre" => "Pedro"))); ?>

El resultado del ejemplo sera algo similar a:

array(4) { ["_id"]=> object(MongoId)#6 (0) { } ["nombre"]=> string(3) "Pedro" ["apellido"]=> string(5) "Ruiz" ["direccion"]=> string(12) "Calle Juan, 1" }

Ejemplo #2 - Ejemplo de MongoCollection::update() con upsert Los upserts pueden simplificar el cdigo, ya que con una sla lnea podemos crear el objeto si ste no existiera, o actualizarlo si existiera.
<?php $c->drop(); $c->update(array("uri" => "/fotos_verano"), array('$inc' => array("accesos" => 1)), array("upsert" => true)); var_dump($c->findOne()); ?>

El resultado del ejemplo sera algo similar a:

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

Si newobj no contuviera operadores $, upsert podra crear a partir de l un nuevo Driver nativo MongoDB 137

documento. Esto coincide con el comportamiento normal de una actualizacin: si no se usaran operadores $, se sobrescribira todo el documento.
<?php $c->update(array("nombre" => "juan"), array("usuario" => "juan12", "fechaAlta" => new MongoDate()), array("upsert" => true)); ?>

El resultado del ejemplo sera algo similar a:

array(3) { ["_id"]=> object(MongoId)#10 (0) { } ["usuario"]=> string(6) "juan312" ["fechaAlta"]=> object(MongoDate)#4 (0) { } }

Ejemplo #3 - Ejemplo de mltiples MongoCollection::update() De forma predeterminada, MongoCollection::update() slo actualizar el primer documento que encuentre que cumpla las condiciones de $criteria. Si fuera necesario, mediante la opcin "multiple" podremos sobrescribir este comportamiento. Este ejemplo aade un campo "regalo" a cada persona cuyo cumpleaos sea el prximo da.
<?php $hoy = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day"))); $gente->update(array("cumpleaos" => $hoy), array('$set' => array('regalo' => $surprise)), array("multiple" => true)); ?>

Ver tambin
La documentacin de PHP sobre actualizaciones y la documentacion en MongoDB.

Driver nativo MongoDB

138

MongoCollection::validate
MongoCollection::validate -- Valida esta coleccin

Descripcin
public array MongoCollection::validate ( [ bool $scan_data = FALSE ] )

Parmetros
scan_data

Slo valida los ndices, no la coleccin base.

Valores devueltos
Devuelve la evaluacin de la base de datos de este objeto.

Driver nativo MongoDB

139

Clase MongoCursor

Introduccin
Un cursor se utiliza parar recorrer el resultado de una consulta a la base de datos. Por ejemplo, para consultar la base de datos y revisar los resultados, se podra:
<?php $cursor = $collection->find(); var_dump(iterator_to_array($cursor)); ?>

Por norma general los cursores no se crean utilizando el constructor MongoCursor, ya que se obtienen al invicar a MongoCollection::find() (como en el ejemplo superior). Supngase que, en el ejemplo superior, $collection fuera una coleccin de 50GB. No quisiramos tener que alojar en memoria todo de una vez, y esto es lo que solucionan los cursores: permiten al cliente acceder a la coleccin gota a gota. Si tuviramos un resultado extenso, podramos recorrerlo cargando unos pocos megabytes a memoria cada vez. Por ejemplo:
<?php $cursor = $collection->find(); foreach ($cursor as $doc) { // hacer algo a cada documento } ?>

Esto recorrer cada documento de la coleccin, cargando y eliminando de memoria cada documento segn se necesite. Debe tenerse en cuenta que esto significa que un cursor no "contiene" el resultado de la base de datos, sino que slo lo gestiona. Por tanto, si se imprimiera un cursor (con, digamos, var_dump() o print_r() ), slo se obtendra el propio objeto cursor, sin los documentos. Para obtener los documentos en s, debe utilizarse alguno de los mtodos vistos arriba.

Estados de un Cursor
Un MongoCursor tiene dos estados: pre y post consulta. Al crear un cursor, ste no se conecta a la base de datos, por lo que est en estado pre-consulta. En este estado, el cliente puede indicar qu quiere consultar, definiendo lmites, saltos, ordenaciones y ms opciones avanzadas.

Driver nativo MongoDB

140

Cuando el cliente solicita el resultado (invocando MongoCursor::next(), directa o indirectamente), el cursor avanza al estado post-consulta. En este punto, la consulta ya se ha ejecutado por la base de datos y ya no se puede modificar.

<?php $cursor = $collection->find()->limit(10); // todava no se ha consultado la base de datos, de modo que se pueden aadir ms opciones $cursor = $cursor->sort(array("a" => 1)); var_dump($cursor->getNext()); // ya se ha consultado la base de datos, y no se pueden aadir ms opciones // por lo que esto lanzara una excepcin: $cursor->skip(4); ?>

Clases sinopsis

MongoCursor

implements Iterator { /* Campos Estticos */ static boolean slaveOkay = FALSE; static integer timeout = 20000; /* Mtodos */ public MongoCursor MongoCursor::addOption ( string $key, mixed $value ) public MongoCursor MongoCursor::batchSize ( int $num ) MongoCursor::__construct ( Mongo $connection, string $ns [, array $query = array() [, array $fields = array() ] ] ) public int MongoCursor::count ( [ bool $foundOnly = FALSE ] ) public array MongoCursor::current ( void ) public bool MongoCursor::dead ( void ) protected void MongoCursor::doQuery ( void )

Driver nativo MongoDB

141

public array MongoCursor::explain ( void ) public MongoCursor MongoCursor::fields ( array $f ) public array MongoCursor::getNext ( void ) public bool MongoCursor::hasNext ( void ) public MongoCursor MongoCursor::hint ( array $key_pattern ) public MongoCursor MongoCursor::immortal ( [ bool $liveForever = true ] ) public array MongoCursor::info ( void ) public string MongoCursor::key ( void ) public MongoCursor MongoCursor::limit ( int $num ) public void MongoCursor::next ( void ) public MongoCursor MongoCursor::partial ( [ bool $okay = true ] ) public void MongoCursor::reset ( void ) public void MongoCursor::rewind ( void ) public MongoCursor MongoCursor::skip ( int $num ) public MongoCursor MongoCursor::slaveOkay ( [ bool $okay = true ] ) public MongoCursor MongoCursor::snapshot ( void ) public MongoCursor MongoCursor::sort ( array $fields ) public MongoCursor MongoCursor::tailable ( [ bool $tail = true ] ) public MongoCursor MongoCursor::timeout ( int $ms ) public bool MongoCursor::valid ( void ) }

Variables Estticas
MongoCursor::slaveOkay Si la consulta debe o no tener asignada la bandera "slaveOkay", la cual permite leer en un esclavo (por omisin, los esclavos son para hacer copias de seguridad). Puede sobrescribirse con MongoCursor::slaveOkay(). MongoCursor::timeout Establecer el tiempo de espera en milisegundos para las respuestas de todas las

Driver nativo MongoDB

142

bases de datos. Para esperar eternamente, use -1. Se puede sobcrescribir con MongoCursor::timeout(). Esto no hace que el servidor MongoDB cancele la operacin; slo hace que el driver deje de esperar, y emite una excepcin MongoCursorTimeoutException.

Ver tambin
Documentacin de MongoDB sobre cursores.

Driver nativo MongoDB

143

MongoCursor::addOption
MongoCursor::addOption -- Adds a top-level key/value pair to a query

Descripcin
public MongoCursor MongoCursor::addOption ( string $key, mixed $value ) This is an advanced function and should not be used unless you know what you're doing. A query can optionally be nested in a "query" field if other options, such as a sort or hint, are given. For instance, adding a sort causes the query to become a subfield of a bigger query object, like:
<?php $query = array("query" => $query, "orderby" => $sort); ?>

This method is for adding a top-level field to a query. It makes the query a subobject (if it isn't already) and adds the key/value pair of your chosing to the top level.

Advertencia It cannot be used to add extra criteria to a query on the fly. For instance, this will not work:
<?php // NOT CORRECT $cursor = $users->find()->addOption("name", "joe")->addOption("age", 20); ?>

This does not query for a user named "joe" with an age of 20.

Parmetros
key

Fieldname to add.
value

Value to add.

Valores devueltos
Returns this cursor.

Driver nativo MongoDB

144

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Ejemplos
Ejemplo #1 - MongoCursor::addOption() example Using MongoCursor::skip() to skip over millions of results can become slow. One way around this is to use $min or $max options for the query. These can be handy, but they require an index on exactly the fields being searched for. This is an example of how to use $min as an alternative to MongoCursor::skip().
<?php // make sure we have an index $c->ensureIndex(array("ts" => 1)); // you may have to modify this to run in a reasonable amount of time on slow // machines (should take about 30 seconds on a good machine) for ($i = 0; $i < 30000000; $i++) { $c->insert(array("ts" => new MongoDate(), "i" => $i)); } $now = strtotime("now"); // find documents inserted in the last 2 seconds $cursor = $c->find()->addOption('$min', array("ts" => $now-2)); ?>

Driver nativo MongoDB

145

MongoCursor::batchSize
MongoCursor::batchSize -- Sets the number of results returned per result set

Descripcin
public MongoCursor MongoCursor::batchSize ( int $num ) This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results). To ensure consistent behavior, the rules of batchSize and limit behavior a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. Some examples:
<?php // one batch, at most 20 items $cursor->limit(-20)->batchSize(10); // one batch, at most 10 items $cursor->limit(20)->batchSize(-10); // first batch: at most 10 items $cursor->limit(10); // first batch: at most 10 items $cursor->limit(10)->batchSize(20); // first batch: at most 10 items $cursor->limit(20)->batchSize(10);

$cursor->limit(30)->batchSize(7) // if we iterate through 28 items, the next call to getNext() will contact the // database and request a batch of 2 documents ?>

Parmetros
num

The number of results to return in the next batch.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Driver nativo MongoDB 146

Throws MongoCursorException if this cursor has started iterating. This will change in 1.0.12, as this should be able to be called at any time.

Driver nativo MongoDB

147

MongoCursor::__construct
MongoCursor::__construct -- Create a new cursor

Descripcin
MongoCursor::__construct ( Mongo $connection, string $ns [, array $query = array() [, array $fields = array() ] ] )

Parmetros
connection

Database connection.
ns

Full name of database and collection.

query

Database query.
fields

Fields to return.

Valores devueltos
Returns the new cursor.

Driver nativo MongoDB

148

MongoCursor::count
MongoCursor::count -- Counts the number of results for this query

Descripcin
public int MongoCursor::count ( [ bool $foundOnly = FALSE ] ) This method does not affect the state of the cursor: if you haven't queried yet, you can still apply limits, skips, etc. If you have started iterating through results, it will not move the current position of the cursor. If you have exhasted the cursor, it will not reset it.

Parmetros
foundOnly

Send cursor limit and skip information to the count function, if applicable.

Valores devueltos
The number of documents returned by this cursor's query.

Ejemplos
Ejemplo #1 - MongoCursor::count() example
<?php $collection->insert(array('x'=>1)); $collection->insert(array('x'=>2)); $collection->insert(array('x'=>3)); $cursor = $collection->find(); var_dump($cursor->count()); var_dump($cursor->count(true)); $cursor->limit(2); var_dump($cursor->count()); var_dump($cursor->count(true)); ?>

El resultado del ejemplo sera algo similar a:

int(3) int(3) int(3) int(2)

Driver nativo MongoDB

149

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.

Driver nativo MongoDB

150

MongoCursor::current
MongoCursor::current -- Returns the current element

Descripcin
public array MongoCursor::current ( void ) This returns NULL until MongoCursor::next() is called.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
The current result as an associative array.

Driver nativo MongoDB

151

MongoCursor::dead
MongoCursor::dead -- Checks if there are documents that have not been sent yet from the database for this cursor

Descripcin
public bool MongoCursor::dead ( void ) The database sends responses in batches of documents, up to 4Mb of documents per response. This method checks if the database has more batches or if the result set has been exhausted. A cursor being "dead" does not mean that MongoCursor::hasNext() will return FALSE, it only means that the database is done sending results to the client. The client should continue iterating through results until MongoCursor::hasNext() is FALSE.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns if there are more results that have not been sent to the client, yet.

Driver nativo MongoDB

152

MongoCursor::doQuery
MongoCursor::doQuery -- Execute the query.

Descripcin
protected void MongoCursor::doQuery ( void ) This function actually queries the database. All queries and commands go through this function. Thus, this function can be overridden to provide custom query handling. This handles serializing your query, sending it to the database, receiving a response, and deserializing it. Thus, if you are planning to override this, your code should probably call out to the original to use the existing functionality (see the example below).

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
NULL.

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.

Ejemplos

Ejemplo #1 - MongoCursor::doQuery() example You could override this function to attempt a query on a slave and, if that fails, try it again on the master.
<?php class MyCursor extends MongoCursor { protected function doQuery() { $this->slaveOkay(); try { MongoCursor::doQuery(); } catch(MongoCursorException $e) { $this->slaveOkay(false); MongoCursor::doQuery();

Driver nativo MongoDB

153

} } } ?>

Driver nativo MongoDB

154

MongoCursor::explain
MongoCursor::explain -- Return an explanation of the query, often useful for optimization and debugging

Descripcin
public array MongoCursor::explain ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns an explanation of the query.

Ejemplos
Ejemplo #1 - MongoCursor::explain() example
<?php $cursor = $collection->find(array("x"=>1), array("y")); $cursor->sort(array("z" => 1))->limit(4)->skip(5); var_dump($cursor->explain()); ?>

El resultado del ejemplo sera algo similar a:

array(8) { ["cursor"]=> string(15) "BtreeCursor x_1" ["startKey"]=> array(1) { ["x"]=> int(1) } ["endKey"]=> array(1) { ["x"]=> int(1) } ["nscanned"]=> float(4) ["n"]=> int(4) ["scanAndOrder"]=> int(1) ["millis"]=>

Driver nativo MongoDB

155

int(3) ["allPlans"]=> array(2) { [0]=> array(3) { ["cursor"]=> string(15) "BtreeCursor x_1" ["startKey"]=> array(1) { ["x"]=> int(1) } ["endKey"]=> array(1) { ["x"]=> int(1) } } [1]=> array(3) { ["cursor"]=> string(11) "BasicCursor" ["startKey"]=> array(0) { } ["endKey"]=> array(0) { } } } }

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.

Ver tambin
MongoDB core docs on explain.

Driver nativo MongoDB

156

MongoCursor::fields
MongoCursor::fields -- Sets the fields for a query

Descripcin
public MongoCursor MongoCursor::fields ( array $f ) Fields are specified by "fieldname" : bool. TRUE indicates that a field should be returned, FALSE indicates that it should not be returned. You can also use 1 and 0 instead of TRUE and FALSE. Thus, to return only the "summary" field, one could say:
<?php $cursor->fields(array("summary" => true)); ?>

To return all fields except the "hidden" field:

<?php $cursor->fields(array("hidden" => false)); ?>

Parmetros
f

Fields to return (or not return).

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating or a scalar argument is given.

Driver nativo MongoDB

157

MongoCursor::getNext
MongoCursor::getNext -- Return the next object to which this cursor points, and advance the cursor

Descripcin
public array MongoCursor::getNext ( void ) This is identical to the function:
<?php public function getNext() { $this->next(); return $this->current(); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns the next object.

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.

Driver nativo MongoDB

158

MongoCursor::hasNext
MongoCursor::hasNext -- Checks if there are any more elements in this cursor

Descripcin
public bool MongoCursor::hasNext ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns if there is another element.

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.

Driver nativo MongoDB

159

MongoCursor::hint
MongoCursor::hint -- Gives the database a hint about the query

Descripcin
public MongoCursor MongoCursor::hint ( array $key_pattern )

Parmetros
key_pattern

Indexes to use for the query.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Driver nativo MongoDB

160

MongoCursor::immortal
MongoCursor::immortal -- Sets whether this cursor will timeout

Descripcin
public MongoCursor MongoCursor::immortal ( [ bool $liveForever = true ] ) After remaining idle for some amount of time, cursor, by default, "die." This is generally the behavior one wants. The database cleans up a cursor once all of its results have been sent to the client, but if the client doesn't request all of the results, the cursor will languish there, taking up resources. Thus, after a few minutes, the cursor "times out" and the database assumes the client has gotten everything it needs and cleans up its the cursor's resources. If, for some reason, you need a cursor to hang around for a long time, you can prevent the database from cleaning it up by using this method. However, if you make a cursor immortal, you need to iterate through all of its results (or at least until Cursor::dead() returns TRUE ) or the cursor will hang around the database forever, taking up resources.

Parmetros
liveForever

If the cursor should be immortal.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Driver nativo MongoDB

161

MongoCursor::info
MongoCursor::info -- Gets the query, fields, limit, and skip for this cursor

Descripcin
public array MongoCursor::info ( void ) This can be called before or after the query.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns the namespace, limit, skip, query, and fields for this cursor.

Historial de cambios

Versin 1.0.10

Descripcin Added started_iterating field, a boolean indicating if cursor is pre- or post-query. Added a number of other fields, including id (the cursor id), at (the driver's counter of which document is current), numReturned (the number returned by the server in the current batch), and server (which server the query was sent to?useful in conjunction with MongoCursor::slaveOkay() ).

1.1.0

Ejemplos
Ejemplo #1 - MongoCursor::info() example
<?php $m = new Mongo(); $cursor = $m->foo->bar->find(array("x" => 4), array("y" => false)); var_dump($cursor->info()); ?>

Driver nativo MongoDB

162

El resultado del ejemplo sera algo similar a:

array(5) { ["ns"]=> string(7) "foo.bar" ["limit"]=> int(0) ["skip"]=> int(0) ["query"]=> array(1) { ["x"]=> int(4) } ["fields"]=> array(1) { ["y"]=> int(0) } }

Driver nativo MongoDB

163

MongoCursor::key
MongoCursor::key -- Returns the current result's _id

Descripcin
public string MongoCursor::key ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
The current result's _id as a string.

Driver nativo MongoDB

164

MongoCursor::limit
MongoCursor::limit -- Limits the number of results returned

Descripcin
public MongoCursor MongoCursor::limit ( int $num )

Parmetros
num

The number of results to return.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Ver tambin
MongoDB core docs on limit.

Driver nativo MongoDB

165

MongoCursor::next
MongoCursor::next -- Advances the cursor to the next result

Descripcin
public void MongoCursor::next ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
NULL.

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.

Driver nativo MongoDB

166

MongoCursor::partial
MongoCursor::partial -- If this query should fetch partial results from mongos if a shard is down

Descripcin
public MongoCursor MongoCursor::partial ( [ bool $okay = true ] ) This option allows mongos to send partial query results if a shard is unreachable. This is only applicable when running a sharded MongoDB cluster and connecting to a mongos. If a shard goes down and a query needs to be sent to that shard, mongos will return the results (if any) from shards it already contacted, then an error message that it could not reach the shard (a MongoCursorException in PHP). If you would like to get whatever results mongos can provide and no exception, you can use this method. Note that this means that you won't have an indication that a shard is down in your query response. This has no effect on the query if all shards are reachable. This flag was implemented in MongoDB version 1.7.5, so will only work with that version and higher.

Parmetros
okay

If receiving partial results is okay.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Driver nativo MongoDB

167

MongoCursor::reset
MongoCursor::reset -- Clears the cursor

Descripcin
public void MongoCursor::reset ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
NULL.

Driver nativo MongoDB

168

MongoCursor::rewind
MongoCursor::rewind -- Returns the cursor to the beginning of the result set

Descripcin
public void MongoCursor::rewind ( void ) This is identical to the function:
<?php public function rewind() { $this->reset(); $this->next(); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
NULL.

Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.

Driver nativo MongoDB

169

MongoCursor::skip
MongoCursor::skip -- Skips a number of results

Descripcin
public MongoCursor MongoCursor::skip ( int $num )

Parmetros
num

The number of results to skip.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Driver nativo MongoDB

170

MongoCursor::slaveOkay
MongoCursor::slaveOkay -- Sets whether this query can be done on a slave

Descripcin
public MongoCursor MongoCursor::slaveOkay ( [ bool $okay = true ] ) Calling this will make the driver route reads to slaves if: You are using a replica set and You created a Mongo instance using the option "replicaSet" => true and There is a healthy slave that can be reached by the driver. You can check which server was used for this query by calling MongoCursor::info() after running the query. It's server field will show which server the query was sent to. Note that you should use this function even if you do not use the automatic routing to slaves. If you connect directly to a secondary in a replica set, you still need to call this function, which basically tells the database that you are aware that you might be getting older data and you're okay with that. If you do not call this, you'll get "not master" errors when you try to query. This method will override the static class variable MongoCursor::slaveOkay. It will also override Mongo::setSlaveOkay(), MongoDB::setSlaveOkay() and MongoCollection::setSlaveOkay().

Parmetros
okay

If it is okay to query the slave.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Ejemplos
Ejemplo #1 - MongoCursor::slaveOkay() example
<?php

Driver nativo MongoDB

171

MongoCursor::$slaveOkay = false; // cannot query slave $cursor = $collection->find(); // can query slave $cursor = $collection->find()->slaveOkay(); MongoCursor::$slaveOkay = true; // can query slave $cursor = $collection->find(); // cannot query slave $cursor = $collection->find()->slaveOkay(false); ?>

Driver nativo MongoDB

172

MongoCursor::snapshot
MongoCursor::snapshot -- Use snapshot mode for the query

Descripcin
public MongoCursor MongoCursor::snapshot ( void ) Use snapshot mode for the query. Snapshot mode assures no duplicates are returned, or objects missed, which were present at both the start and end of the query's execution (if an object is new during the query, or deleted during the query, it may or may not be returned, even with snapshot mode). Note that short query responses (less than 1MB) are always effectively snapshotted. Currently, snapshot mode may not be used with sorting or explicit hints.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Driver nativo MongoDB

173

MongoCursor::sort
MongoCursor::sort -- Sorts the results by given fields

Descripcin
public MongoCursor MongoCursor::sort ( array $fields )

Parmetros
fields

The fields by which to sort.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Ejemplos
Ejemplo #1 - MongoCursor::sort() example
<?php // sort x ascending $cursor->sort(array('x' => 1)); // the associative array is ordered, for instance, these two // examples might yield different results: // sort date ascending and age descending $cursor->sort(array('date' => 1, 'age' => -1)); // sort age descending and date ascending $cursor->sort(array('age' => -1, 'date' => 1)); ?>

Driver nativo MongoDB

174

MongoCursor::tailable
MongoCursor::tailable -- Sets whether this cursor will be left open after fetching the last results

Descripcin
public MongoCursor MongoCursor::tailable ( [ bool $tail = true ] ) Mongo has a feature known as tailable cursors which are similar to the Unix "tail -f" command. Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final object's position. you can resume using the cursor later, from where it was located, if more data were received. Like any "latent cursor", the cursor may become invalid at some point -- for example if that final object it references were deleted. Thus, you should be prepared to requery if the cursor is MongoCursor::dead().

Parmetros
tail

If the cursor should be tailable.

Valores devueltos
Returns this cursor.

Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.

Ejemplos
Ejemplo #1 - MongoCursor::tailable() example
<?php $cursor = $collection->find()->tailable(); $results = array(); while (1) { if (!$cursor->hasNext()) { // we've read all the results, exit if ($cursor->dead()) {

Driver nativo MongoDB

175

break; } // read all results so far, wait for more sleep(10); } else { $results[] = $cursor->getNext(); } } ?>

Driver nativo MongoDB

176

MongoCursor::timeout
MongoCursor::timeout -- Sets a client-side timeout for this query

Descripcin
public MongoCursor MongoCursor::timeout ( int $ms ) A timeout can be set at any time and will affect subsequent queries on the cursor, including fetching more results from the database. For example, to wait forever for an initial response but timeout after 100 ms for subsequent results, one could say:
<?php $cursor = $collection->find(); // $cursor->hasNext() executes the query. No timeout has been set, so the // program will wait as long as necessary for a response. while ($cursor->hasNext()) { $cursor->timeout(100); // now the timeout has been set, so if the cursor needs to get more results // from the database, it will only wait 100 ms for the database's reply try { print_r($cursor->getNext()); } catch(MongoCursorTimeoutException $e) { echo "query took too long!"; } } ?>

A timeout of 0 (or a negative number) will wait forever so it can be used to reset the cursor if a timeout is no longer needed.

Parmetros
ms

The number of milliseconds for the cursor to wait for a response. By default, the cursor will wait forever.

Valores devueltos
This cursor.

Ejemplos

Driver nativo MongoDB

177

Ejemplo #1 - MongoCursor::timeout() example A query where the cursor waits for one second for a response.
<?php $cursor = $collection->find()->timeout(1000); try { foreach ($cursor as $value) { print_r($value); } } catch(MongoCursorTimeoutException $e) { echo "query took too long!"; } ?>

Errores/Excepciones
Causes methods that fetch results to throw MongoCursorTimeoutException s if the query takes longer than the number of milliseconds specified.

Driver nativo MongoDB

178

MongoCursor::valid
MongoCursor::valid -- Checks if the cursor is reading a valid result.

Descripcin
public bool MongoCursor::valid ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
If the current result is not null.

Driver nativo MongoDB

179

Tipos

MongoDB permite a los programadores guardar y consultar datos expresados tanto en los tipos bsicos de PHP, los tipos compuestos (arrays, arrays asociativos, y objetos), y en media docena de clases que proporciona el driver MongoDB de PHP (para expresiones regulares, fechas, y otras aplicaciones especializadas).

Booleanos y NULL
TRUE, FALSE, y NULL pueden usarse tal cual.

Nmeros
En MongoDB los nmeros son distintos de los strings: "123" no es lo mismo que 123. Por tanto, si se desea asegurar de que los nmeros se ordenan y comparan correctamente, debe asegurarse de que realmente se almacenan como nmeros.
<?php $doc = array("a" => 123, "b" => "123"); $collection->insert($doc); $doc->find(array("a" $doc->find(array("a" $doc->find(array("a" $doc->find(array("b" $doc->find(array("b" ?> => => => => => 123)); "123")); 123.0)); 123)); "123")); // // // // // coincide no coincide coincide no coincide coincide

Como vemos, los nmeros en coma flotante se comparan y coinciden con los nmeros enteros tal como cabra esperar.

Nmeros Largos
Por omisin, en sistemas de 32 bits, los nmeros se envan a la base de datos como enteros de 32 bit. En sistemas 64 bits, se envan como enteros de 64 bit. Para guardar la compatibilidad, todos los sistemas deserializan los enteros de 64 bit como nmeros en coma flotante. Los nmeros en coma flotante no son exactos. Si fuera necesario usar valores exactos, habra que hacerlo ajsutando el fichero php.ini. En sistemas de 32 bits, si mongo.long_as_object est habilitado, los enteros de 64 bit se devolvern como objetos MongoInt64. El entero se almacenar en el campo value con una precisin perfecta (como un string). MongoInt64 puede usarse tambin para guardar enteros de 64 bit en mquinas de 32 bits.

Driver nativo MongoDB

180

En sistemas de 64 bits, puede o bien habilitarse mongo.long_as_object o mongo.native_long. mongo.native_long devolver enteros de 64 bit y enteros "normales" de PHP. MongoInt32 puede usarse para almacenar enteros de 32 bit en mquinas de 64 bits. Debe establecerse un valor en mongo.long_as_object y en mongo.native_long de acuerdo al comportamiento que se espere, incluso en el caso de que coincida con los valores por omisin (para prevenir futuros cambios de estos valores). Vea tambin: Opciones de php.ini, MongoInt32, MongoInt64.

Strings
Los strings deben ser UTF-8. Si no, o bien se convierten a UTF-8 antes de enviarse a la base de datos, o bien se almacenan como datos binarios. Pueden usarse expresiones regulares para consultar strings, y se expresan usando la clase MongoRegex.

Datos Binarios
Tanto los textos que no son UTF-8, como las imgenes, o cualuier otro dato binario, debe enviarse a la base de datos usando el tipo MongoBinData.

Fechas
Pueden crearse fechas usando la clase MongoDate. Se almacenan como milisegundos a partir de la fecha de referencia. MongoTimestamp no es para almacenar fechas ni timestamps, sino que se usa internamente por MongoDB. A no ser que se est creando una herramienta que interacte con los entresijos de rplicas o sharding, se deber usar MongoDate, y no MongoTimestamp.

Ids nicos
El driver crear automticamente un campo _id antes de insertar un documento (a no ser que el usuario haya especificado uno). Este campo es una instancia de MongoId (en otros lenguajes habitualmente se le llama "ObjectId"). Estos ids se componen de 12 bytes: 4 bytes de timestamp Dos registros no pueden tener el mismo id si se han insertado en momentos diferentes. 3 bytes de id de mquina Dos registros no pueden tener el mismo id si se han insertado en mquinas diferentes. Driver nativo MongoDB 181

 2 bytes de id de hebra Dos registros no pueden tener el mismo id si se han insertado por diferentes hebras en la misma mquina. 3 bytes de valor incremental Cada vez que se crea un id, un contador global se incrementa, y se usa para el incremento del siguiente id. Por tanto, dos registros no pueden tener el mismo id, a no ser que un nico proceso en una misma mquina trate de insertar 256^3 (ms de 16 millones) de documentos en un segundo, desbordando el campo de incremento.

JavaScript
MongoDB incorpora un motor JavaScript, de modo que se pueden incluir cdigo JavaScript en las consultas (usando la clasula $where), enviarlo directamente a la base de datos para ejecutarlo, y usarlo para llevar a cabo agregaciones. Por seguridad, en MongoCode utilice el campo scope cuando vaya a usar variables PHP en JavaScript. Cuando el cdigo no requiera de valores externos, se puede o bien usar MongoCode o smplemente un string. Revise la seccin de seguridad para ms informacin sobre cmo enviar cdigo JavaScript a la base de datos.

Arrays y Objetos
Tambin pueden guardarse arrays y objetos en la base de datos. Los arrays con clave numrica incremental se almacenarn como arrays. En cualquier otro caso, se almacenarn como objetos.
<?php // $puntuaciones se almacenar como array $puntuaciones = array(98, 100, 73, 85); $collection->insert(array("puntuaciones" => $puntuaciones)); // $puntuaciones se almacenar como un objeto $puntuaciones = array("pregunta1" => 98, "examen" => 100, "pregunta2" => 73, "final" => 85); $collection->insert(array("puntuaciones" => $puntuaciones)); ?>

Si consultamos estos objetos en la consola de la base de dato, obtendremos algo similar a esto:
> db.students.find() { "_id" : ObjectId("4b06beada9ad6390dab17c43"), "puntuaciones" : [ 98, 100, 73, 85 ] } { "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "puntuaciones" : { "pregunta1" : 98, "examen" : 100, "pregunta2" : 73, "final" : 85 } }

La base de datos puede almacenar tambin objetos PHP arbitrarios (pese a que se devolvern como arrays asociativos). Los campos se usan para pares clave/valor. Por ejemplo, la entrada de un blog podra ser as:
<?php

Driver nativo MongoDB

182

// clase de la entrada de un blog class Entrada { var var var var $autor; $contenido; $comentarios = array(); $fecha;

public function __construct($autor, $contenido) { $this->autor = $autor; $this->contenido = $contenido; $this->fecha = new MongoDate(); } public function establecerTitulo($titulo) { $this->titulo = $titulo; } } // crear una entrada de blog sencilla e insertarla en base de datos $entrada1 = new Entrada("Adam", "Esto es una entrada de un blog"); $blog->insert($entrada1);

// no hay niguna restriccin del tipo usado en el campo "autor", de manera que podemos // usarlo como un objeto anidado $autor = array("nombre" => "Fred", "karma" => 42); $entrada2 = new Entrada($autor, "sta es otra entrada de blog."); // creamos un campo ms para el ttulo $entrada2->establecerTitulo("Segunda Entrada"); $blog->insert($entrada2); ?>

En la consola de la base de datos, lo veramos parecido a esto:

> db.blog.find() { "_id" : ObjectId("4b06c263edb87a281e09dad8"), "autor" : "Adam", "contenido" : "Esto es una entrada de un blog", "comentarios" : [ ], "fecha" : "Fri Nov 20 2009 11:22:59 GMT-0500 (EST)" } { "_id" : ObjectId("4b06c282edb87a281e09dad9"), "autor" : { "nombre" : "Fred", "karma" : 42 }, "contenido" : "sta es otra entrada de blog", "comentarios" : [ ], "fecha" : "Fri Nov 20 2009 11:23:30 GMT-0500 (EST)", "titulo" : "Segunda Entrada" }

El driver no detecta referencias cclicas en arrays ni en objetos. Por ejemplo, esto emitira un error fatal:
<?php $collection->insert($GLOBALS); ?> Fatal error: Nesting level too deep - recursive dependency?

Driver nativo MongoDB

183

Si se necesitara insertar documentos que pudieran tener dependencias cclicas, deber comprobarse a mano antes de pasarlo al driver.

Driver nativo MongoDB

184

Clase MongoId

Introduccin
Identificador nico creado para objetos de bases de datos. Se se inserta un objeto sin un campo _id en una base de datos , ste se aadir con una instancia de MongoId. Si los datos tuvieran un campo nico natural (como p.ej., un nombre de usuario o una fecha) no habra problema en usarlo como _id, y en este caso no se reemplazara por un MongoId. Las instancias de MongoId cumplen la funcin de los campos autoincrementales de las base de datos relacionales: ofrecen una clave nica cuando los datos no tienen una clave natural. Los autoincrementales no funcionan correctamente en bases de datos compartidas, ya que es imposible averiguar rpidamente cul ser el siguiente nmero. Esta clase establece las limitaciones necesarias para generar rpidamente un valor nico entre servidores compartidos. Cada MongoId contiene 12 bytes (componiendo un string de 24 caracteres hexadecimales). Los cuatro primeros bytes son un timestamp, los tres siguientes son un hash del nombre de mquina del cliente, los dos siguiente son los bytes menos significativos del id del proceso en ejecucin del script, y los ltimos tres corresponden a un valor incremental. MongoId es serializable y deserializable. Su forma serializada es similar a su forma en string:
C:7:"MongoId":24:{4af9f23d8ead0e1d32000000}

Clases sinopsis

MongoId

MongoId { public string $id = NULL; /* Mtodos */ MongoId::__construct ( [ string $id = NULL ] ) public static string MongoId::getHostname ( void ) public int MongoId::getInc ( void )

Driver nativo MongoDB

185

public int MongoId::getPID ( void ) public int MongoId::getTimestamp ( void ) public static MongoId MongoId::__set_state ( array $props ) public string MongoId::__toString ( void ) }

Campos
$id Este campo contiene la respresentacin string de este objeto.

Ver tambin
Documentacin de MongoDB sobre ids.

Driver nativo MongoDB

186

MongoId::__construct
MongoId::__construct -- Crea un nuevo id

Descripcin
MongoId::__construct ( [ string $id = NULL ] )

Parmetros
id

Texto a usar como identificador. Debe estar formado por 24 caracteres hexadecimales. Si se pasara un valor invlido a este constructor, lo ignorara y creara un nuevo valor para id.

Valores devueltos
Devuelve un nuevo id.

Ejemplos
Ejemplo #1 - MongoId::__construct() example Este ejemplo muestra cmo crear un nuevo id. Rara vez neceasrio usar esto, ya que el driver aade automticamente un id a los arrays antes de que los almacene en base de datos.
<?php $id1 = new MongoId(); echo "$id1\n"; $id2 = new MongoId(); echo "$id2\n"; ?>

El resultado del ejemplo sera algo similar a:

49a7011a05c677b9a916612a 49a702d5450046d3d515d10d

Ejemplo #2 - Ejemplo con parmetros Este ejemplo muestra cmo usar el parmetro para inicializar un MongoId con el valor Driver nativo MongoDB 187

proporcionado.
<?php $id1 = new MongoId(); // crea un nuevo id a partir de $id1 $id2 = new MongoId("$id1"); // muestra que $id1 e $id2 tienen el mismo valor hexadecimal var_dump($id1 == $id2); ?>

El resultado del ejemplo sera algo similar a:

bool(true)

Ver tambin

MongoId::__toString

Driver nativo MongoDB

188

MongoId::getHostname
MongoId::getHostname -- Obtiene el nombre de host que se usa para el id de esta mquina

Descripcin
public static string MongoId::getHostname ( void ) Devuelve el nombre de host que usa MongoId para generar identificadores nicos. Es el mismo valor que devuelve gethostname(). Es idntico a esta funcin:
<?php public static function getHostname() { return gethostname(); } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nombre de host.

Driver nativo MongoDB

189

MongoId::getInc
MongoId::getInc -- Obtiene el valor incremental usado para crear este id

Descripcin
public int MongoId::getInc ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el valor incremental usado para crear este MongoId.

Driver nativo MongoDB

190

MongoId::getPID
MongoId::getPID -- Devuelve el id del proceso usado para crear este id

Descripcin
public int MongoId::getPID ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el PID usado para crear este MongoId.

Driver nativo MongoDB

191

MongoId::getTimestamp
MongoId::getTimestamp -- Devuelve el nmero de segundos desde la fecha de referencia con el que se cre este id

Descripcin
public int MongoId::getTimestamp ( void ) Devuelve lo mismo que cuando se ejecuta time() al crear el id.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nmero de segundos desde la fecha de referencias con el que se cre este id. Tan slo hay cuatro bytes para almacenar el timestamp, por lo que MongoDate es una opcin mejor si se desea almacenar fechas exacta de alto alcance.

Driver nativo MongoDB

192

MongoId::__set_state
MongoId::__set_state -- Crea un MongoId vaco

Descripcin
public static MongoId MongoId::__set_state ( array $props ) Esta funcin slo se usa internamente por PHP, por lo que no debera necesitar ser nunca invocada por el usuario. Es idntica a esta funcin:
<?php public static function __set_state($props) { return new MongoId("000000000000000000000000"); } ?>

Parmetros
props

Supuestamente, un array de propiedades que se usa para crear el nuevo id. Sin embargo, ya que las instancias de MongoId no tienen propiedades, este parmetro no se usa.

Valores devueltos
Un nuevo id con el valor "000000000000000000000000".

Driver nativo MongoDB

193

MongoId::__toString
MongoId::__toString -- Devuelve la representacin hexadecimal de este id

Descripcin
public string MongoId::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Este id.

Ejemplos
Ejemplo #1 - Ejemplo de MongoId::__toString()
<?php $m = new Mongo(); $collection = $m->selectDB("foo")->selectCollection("bar"); $collection->insert(array( "x" => "y" )); $collection->insert(array( "x" => "y" )); $cursor = $collection->find(); $r1 = $cursor->next(); $r2 = $cursor->next(); echo $r1["_id"] . "\n"; echo $r2["_id"] . "\n"; ?>

El resultado del ejemplo sera algo similar a:

49a7011a05c677b9a916612a 49a702d5450046d3d515d10d

Driver nativo MongoDB

194

Clase MongoCode

Introduccin
Representa cdigo JavaScript para la base de datos. Los objetos MongoCode se componen de dos partes: el texto del cdigo y un mbito opcional. El texto del cdigo debe ser JavaScript vlido. El mbito es un array asociativo de pares nombre/valor.

Clases sinopsis

MongoCode

MongoCode { /* Mtodos */ MongoCode::__construct ( string $code [, array $scope = array() ] ) public string MongoCode::__toString ( void ) }

Driver nativo MongoDB

195

MongoCode::__construct
MongoCode::__construct -- Crea un nuevo objeto de cdigo

Descripcin
MongoCode::__construct ( string $code [, array $scope = array() ] )

Parmetros
code

Texto del cdigo.

scope

mbito que se usar para este cdigo.

Valores devueltos
Devuelve un nuevo objeto de cdigo.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCode::__construct()
<?php $code = new MongoCode('function() { '. 'for(i=0;i<10;i++) {'. 'db.foo.update({z : i}, {z : x});'. '}'. 'return x-1;'. '}', array("x" => 4)); var_dump($code); ?>

El resultado del ejemplo sera algo similar a:

object(MongoCode)#1 (2) { ["scope"]=> array(1) { ["x"]=> int(4) } ["code"]=> string(80) "function() { for(i=0;i<10;i++) { db.foo.update({z : i}, {z : x}); } return x-1; }" }

Driver nativo MongoDB

196

Ejemplo #2 - Usando MongoCode() con $where Este ejemplo consulta la coleccin de elementos cuyos campos 'x' valgan menos que $y. Tenga en cuenta que se pasan objetos PHP al mbito de JavaScript y que la funcin JavaScript devuelve un booleano.
<?php $cursor = $collection->find(array('$where' => new MongoCode('function() { return this.x < y; }', array('y'=>$y)))); ?>

Driver nativo MongoDB

197

MongoCode::__toString
MongoCode::__toString -- Devuelve este cdigo en forma de texto

Descripcin
public string MongoCode::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Este cdigo. No se devuelve el mbito.

Ejemplos
Ejemplo #1 - Ejemplo de MongoCode::__toString()
<?php $code = new MongoCode('return x;', array("x"=>"hi")); echo "$code\n"; $code = new MongoCode('function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }'); echo "$code\n"; ?>

El resultado del ejemplo sera algo similar a:

return x; function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }

Driver nativo MongoDB

198

Clase MongoDate

Introduccin
Representa objetos de tipo fecha para la base de datos. Esta clase debe usarse para almacenar fechas en la base de datos y para consultarlas. Por ejemplo:
<?php // guardar una fecha en base de datos $collection->save(array("ts" => new MongoDate())); $start = new MongoDate(strtotime("2010-01-15 00:00:00")); $end = new MongoDate(strtotime("2010-01-30 00:00:00")); // encontrar fechas entre 1/15/2010 y 1/30/2010 $collection->find(array("ts" => array('$gt' => $start, '$lte' => $end))); ?>

MongoDB almacena fechas en milisegundos tras la fecha de referencia. Esto significa que las fechas no contienen informacin de zonas horarias. Si fuera necesario, la zona horaria deber ser almacenada en otro campo. Adems, esto significa que cualquier nivel de precisin ms all de milisegundos se perder al leer o escribir en la base de datos.

Clases sinopsis

MongoDate

MongoDate { /* Campos */ public int sec; public int usec; /* Mtodos */ MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] ) public string MongoDate::__toString ( void ) }

Driver nativo MongoDB

199

MongoDate::__construct
MongoDate::__construct -- Crea un nuevo objeto fecha

Descripcin
MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] ) Crea una nueva fecha. Si no se rellena ningn parmetro, se utilizar la hora actual.

Parmetros
sec

Nmero de segundos desde el 1 de enero de 1970.

usec

Microsegundos.

Valores devueltos
Devuelve esta nueva fecha.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDate::__construct() Este ejemplo muestra cmo crear una nueva fecha con la hora actual y una nueva fecha con la hora proporcionada.
<?php $d = echo $d = echo $d = echo ?> new MongoDate(); "$d\n"; new MongoDate(1234567890); "$d\n"; new MongoDate(strtotime("2009-05-01 00:00:01")); "$d\n";

El resultado del ejemplo sera algo similar a:

0.23660600 1235685067 0.00000000 1234567890 0.00000000 1241150401

Driver nativo MongoDB

200

Ver tambin

MongoDate::__toString

Driver nativo MongoDB

201

MongoDate::__toString
MongoDate::__toString -- Devuelve una representacin en forma de texto de esta fecha

Descripcin
public string MongoDate::__toString ( void ) Devuelve una representacin en forma de texto de esta fecha, similar a la representacin que devuelve microtime().

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Esta fecha.

Driver nativo MongoDB

202

Clase MongoRegex

Introduccin
Esta clase se puede usar para crear expresiones regulares. Normalmente, estas expresiones se usarn para consultar la base de datos y localizar textos que coincidan. Con menos frecuencia, se almacenarn en la base de datos para su posterior consulta. Mongo reconoce seis banderas de expresiones regulares:

i Insensible a maysculas m Multilnea x Puede contener comentarios l local s "." coincidir con todo, incluyendo cambios de lnea u unicode

Clases sinopsis

MongoRegex

MongoRegex { /* Campos */ public string regex; public string flags; /* Mtodos */ MongoRegex::__construct ( string $regex ) public string MongoRegex::__toString ( void ) }

Driver nativo MongoDB

203

MongoRegex::__construct
MongoRegex::__construct -- Crea una nueva expresin regular

Descripcin
MongoRegex::__construct ( string $regex ) Crea una nueva expresin regular.

Parmetros
regex

Texto de la expresin regular, con la forma /expresin/banderas.

Valores devueltos
Devuelve una nueva expresin regular.

Ejemplos

Ejemplo #1 - Ejemplo de MongoRegex::__construct() Este ejemplo usa una expresin regular para seleccionar todos los documentos con el campo usuario que cumpla las condiciones.
<?php $buscar_jose = new MongoRegex("/j[o0]se/i"); $cursor = $collection->find(array("usuario" => $buscar_jose)); ?>

Ver tambin

MongoRegex::__toString

Driver nativo MongoDB

204

MongoRegex::__toString
MongoRegex::__toString -- Representacin en forma de texto de esta expresin regular

Descripcin
public string MongoRegex::__toString ( void ) Devuelve la representacin en forma de texto de esta expresin regular.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Esta expresin regular en la forma "/expresin/banderas".

Ejemplos

Ejemplo #1 - Ejemplo de MongoRegex::__toString()

<?php $r = echo echo echo ?> new MongoRegex( "/[a-fA-F0-9]{16}/g" ); $r->regex . "\n"; $r->flags . "\n"; "$r\n";

El resultado del ejemplo sera algo similar a:

[a-fA-F0-9]{16} g /[a-fA-F0-9]{16}/g

Driver nativo MongoDB

205

Clase MongoBinData

Introduccin
Objeto para almacenar y consultar datos binarios de la base de datos. El tamao mximo de un objeto que puede insertarse en la base de datos es 4Mb. Para datos superiores (pelculas, msica, autobiografa de Henry Kissinger), utilice MongoGridFS. Para datos inferiores a 4Mb, lo ms probable es que lo ms sencillo sea empotrarlo al documento utilizando MongoBinData. Por ejemplo, para empotrar una imagen a un documento, se podra escribir:
<?php $profile = array("username" => "foobity", "pic" => new MongoBinData(file_get_contents("gravatar.jpg")) ); $users->save($profile); ?>

Esta clase contiene el campo type, que actualmente no proporciona ninguna funcionalidad al driver de la base de datos. Hay 5 tipos predefinidos (las contantes de clase definidas abajo), y los usuarios puede definir los suyos propios (se corre el riesgo de que colisione con la especificacin BSON). Por omisin, el driver de PHP siempre utiliza el tipo 2: un array de bytes.

Clases sinopsis

MongoBinData

MongoBinData { /* Constantes */ const int MongoBinData::FUNC = 1; const int MongoBinData::BYTE_ARRAY = 2; const int MongoBinData::UUID = 3; const int MongoBinData::MD5 = 5;

Driver nativo MongoDB

206

const int MongoBinData::CUSTOM = 128; /* Fields */ public string bin; public int type = 2; /* Mtodos */ public MongoBinData::__construct ( string $data [, int $type = 2 ] ) public string MongoBinData::__toString ( void ) }

Constantes predefinidas Tipos de Datos Binarios

MongoBinData::FUNC 0x01 Funcin. MongoBinData::BYTE_ARRAY 0x02 Array de bytes. MongoBinData::UUID 0x03 Identificador nico Universal. MongoBinData::MD5 0x05 MD5. MongoBinData::CUSTOM 0xf0 Tipo definido por el usuario.

Driver nativo MongoDB

207

MongoBinData::__construct
MongoBinData::__construct -- Crea un nuevo objeto de datos binarios

Descripcin
public MongoBinData::__construct ( string $data [, int $type = 2 ] ) Crea un nuevo objeto de datos binarios Hay cinco tipos reconocidos de datos binarios segn la especificacin BSON: funcin (0x01), matriz de bytes (0x02), UUID (0x03), MD5 (0x05), y definido por el usuario (0x80). El tipo por omisin es matriz de bytes (0x02). No hay ninguna diferencia en particilar sobre cmo interpreta el driver cada tipo, There is no particular difference in how the driver or server interpret different types, por tanto es por ahora irrelevante. Se puede usar cualquier nmero (entre 0 y 255) como tipo, siempre y cuando el usuario asuma el riesgo de que la base de datos pueda eventualmente llevar a cabo alguna funcin con datos binarios de este tipo.

Parmetros
data

Datos binarios.
type

Tipo de datos.

Valores devueltos
Devuelve un nuevo objeto de datos binarios.

Driver nativo MongoDB

208

MongoBinData::__toString
MongoBinData::__toString -- Representacin en forma de string de este objeto de datos binarios

Descripcin
public string MongoBinData::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el string "<Mongo Binary Data>". Para acceder al contenido de un MongoBinData, utilice el campo bin.

Driver nativo MongoDB

209

Clase MongoInt32

Introduccin
Esta clase se puede usar para guardar enteros de 32 bits en bases de datos de sistemas a 64 bits.

Clases sinopsis

MongoInt32

MongoInt32 { /* Campos */ public string value; /* Mtodos */ public MongoInt32::__construct ( string $value ) public string MongoInt32::__toString ( void ) }

Campos
value Este es el valor en forma de texto del nmero de 64 bits. Por ejemplo, el valor de 123 sera "123".

Driver nativo MongoDB

210

MongoInt32::__construct
MongoInt32::__construct -- Crea un nuevo entero de 32 bits

Descripcin
public MongoInt32::__construct ( string $value ) Crea un nuevo nmero de 32 bits con el valor proporcionado.

Parmetros
value

Un nmero.

Valores devueltos
Devuelve un nuevo entero.

Driver nativo MongoDB

211

MongoInt32::__toString
MongoInt32::__toString -- Devuelve al representacin en forma de texto de este entero de 32 bits

Descripcin
public string MongoInt32::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la representacin en forma de texto de este entero.

Driver nativo MongoDB

212

Clase MongoInt64

Introduccin
Esta clase se puede usar para guardar enteros de 64 bits en bases de datos en sistemas de 32 bits.

Clases sinopsis

MongoInt64

MongoInt64 { /* Campos */ public string value; /* Mtodos */ public MongoInt64::__construct ( string $value ) public string MongoInt64::__toString ( void ) }

Campos
value Este es el valor en forma de texto del nmero de 64 bits. Por ejemplo, el valor de 123 sera "123".

Driver nativo MongoDB

213

MongoInt64::__construct
MongoInt64::__construct -- Crea un nuevo entero de 64 bits

Descripcin
public MongoInt64::__construct ( string $value ) Crea un nuevo nmero de 64 bits con el valor proporcionado.

Parmetros
value

Un nmero.

Valores devueltos
Devuelve un nuevo entero.

Driver nativo MongoDB

214

MongoInt64::__toString
MongoInt64::__toString -- Devuelve la representacin en forma de texto de este entero de 64 bits

Descripcin
public string MongoInt64::__toString ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve la representacin en forma de texto de este entero.

Driver nativo MongoDB

215

Clase MongoDBRef

Introduccin
Esta clase puede usarse para crear enlaces ligeros entre objetos de diferencias colecciones. Motivacin: Supongamos que necesitamos referirnos a un documento en otra coleccin. La forma ms fcil es crear un nuevo campo en el documento actual. Por ejemplo, si tenemos una coleccin "personas" y una coleccin "direcciones", quizs queramos crear un enlace entre cada documento de persona y un documento de direccin:
<?php $personas = $db->personas; $direcciones = $db->direcciones; $miDireccion = array("linea 1" => "Calle Mayor, 123", "linea 2" => null, "ciudad" => "Springfield", "estado" => "Vermont", "pais" => "USA"); // guardamos la direccion $direcciones->insert($miDireccion); // guardar una persona con una referencia a la direccion $yo = array("nombre" => "Fred", "direccion" => $miDireccion['_id']); $personas->insert($yo); ?>

Posteriormente podremos encontrar la direccin de la persona consultando la coleccin "direcciones" con el MongoId que almacenamos en la coleccin "personas". Supongamos ahora que tenemos un caso ms general, donde no sabemos qu coleccin (o incluso qu base de datos) contiene el documento referenciado. MongoDBRef es una buena eleccin para estos casos, ya que es un formato comn que todos los drivers y bases de datos podrn interpretar. Si cada persona tuviera una lista de cosas que les gusta, y stas pudieran venir a partir de varias colecciones, como "hobbies", "deportes", "libros", etc., podramos usar MongoDBRef para seguir la pista de con qu coleccin se asocia cada gusto:
<?php $personas = $db->selectCollection("personas"); // modelismo ferroviario est en la coleccin "hobbies" $ferroRef = MongoDBRef::create("hobbies", $modelismoFerroviario['_id']); // ftbol est en la coleccin "deportes" $futbolRef = MongoDBRef::create("deportes", $futbol['_id']);

Driver nativo MongoDB

216

// ahora, cuando consultemos el documento, sabremos a qu coleccin // pertenecen cada tem de "gustos" $personas->insert(array("nombre" => "Fred", "gustos" => array($ferroRef, $futbolRef))); ?>

Las referencias a bases de datos se pueden concebir como hipervnculos: proporcionan una direccin nica a otro documento, pero no cargan ni redirigen automticamente al enlace/referencia. Una referencia a una base de datos es un array asociativo, no una instancia de MongoDBRef, de modo que esta clase es ligeramente diferente al resto de clases de tipos de datos. Esta clase contiene nicamente mtodos estticos para poder manipular las referencias a bases de datos.

Clases sinopsis

MongoDBRef

MongoDBRef { /* Mtodos */ public static array MongoDBRef::create ( string $collection, mixed $id [, string $ database ] ) public static array MongoDBRef::get ( MongoDB $db, array $ref ) public static bool MongoDBRef::isRef ( mixed $ref ) }

Ver tambin
Documentacin de MongoDB sobre referencias a bases de datos.

Driver nativo MongoDB

217

MongoDBRef::create
MongoDBRef::create -- Crea una nueva referencia de base de datos

Descripcin
public static array MongoDBRef::create ( string $collection, mixed $id [, string $ database ] ) Si no se especifica ninguna base de datos, se utiliza la actual.

Parmetros
collection

Nombre de la coleccin (sin el nombre de la base de datos).

id

Campo _id del objeto al que enlazar.

database

Nombre de la base de datos.

Valores devueltos
Devuelve la referencia.

Ejemplos
Ejemplo #1 - Ejemplo de MongoDBRef::create() Crea una referencia de base de datos a un documento en la coleccin addresses. La funcin MongoCollection::getName() devuelve el nombre de la coleccin (sin incluir el nombre de la base de datos).
<?php $addresses = $db->addresses; $people = $db->people; // guardar $address para que as tenga un _id $addresses->insert($address); // creamos una referencia $ref = MongoDBRef::create($addresses->getName(), $address['_id']); // asignamos el campo a $person $person['address'] = $ref; $people->save($person); ?>

Driver nativo MongoDB

218

Ver tambin

MongoDB::createDBRef MongoCollection::createDBRef

Driver nativo MongoDB

219

MongoDBRef::get
MongoDBRef::get -- Captura el objeto al que apunta la referencia

Descripcin
public static array MongoDBRef::get ( MongoDB $db, array $ref )

Parmetros
db

Base de datos a usar.

ref

Referencia a capturar.

Valores devueltos
Devuelve el documento al que referencia o NULL si el documento no existe (la referencia est rota).

Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::createDBRef()
<?php // extraemos $person de la base de datos $persona = $gente->findOne(); // obtenemos la direccin $direccion = MongoDBRef::get($gente->db, $persona['direccion']); ?>

Ver tambin

MongoDB::getDBRef MongoCollection::getDBRef

Driver nativo MongoDB

220

MongoDBRef::isRef
MongoDBRef::isRef -- Comprueba si un array es una referencia en la base de datos

Descripcin
public static bool MongoDBRef::isRef ( mixed $ref ) Esta funcin no sigue las referencias, por lo que no sirve para determinar si una referencia est o no rota. Tan solo comprueba que ref est en el formato vlido de referencias de bases de datos (objeto o array con los campos $ref y $id).

Parmetros
ref

Array u objeto a comprobar.

Valores devueltos
Devulve un indicador de si ref es o no una referencia.

Driver nativo MongoDB

221

Clase MongoMinKey

Introduccin
MongoMinKey es un tipo especial de la base de datos que se evala siempre como menor que cualquier otro tipo. As, si se ordena ascendemente una consulta por un determinado campo, cualquier documento que tenga MongoMinKey como valor, ser devuelto en primera posicin. MongoMinKey no tiene ni campos, ni mtodos, ni constantes asociados. Es simplemente el valor "ms bajo" que se puede insertar en la base de datos.

Clases sinopsis

MongoMinKey

MongoMinKey { }

Usando MongoMinKey como valor

<?php $collection->insert(array("tarea" => "almorzar", "hacer el" => new MongoMinKey)); $collection->insert(array("tarea" => "reunin de personal", "hacer el" => new MongoDate(strtotime("+4 days")))); $cursor = $collection->find()->sort(array("hacer el" => 1)); ?>

El cursor contendr el documento de almorzar, y despus el documento de reunin de personal. El documento de almorzar siempre ser el primero, independientemente de lo que aadamos a la coleccin (a no ser que se aadan otros documentos con MongoMinKey en el campo "hacer el").

Driver nativo MongoDB

222

Clase MongoMaxKey

Introduccin
MongoMaxKey es un tipo especial de la base de datos que se evala siempre como mayor que cualquier otro tipo. As, si se ordena ascendemente una consulta por un determinado campo, cualquier documento que tenga MongoMaxKey como valor, ser devuelto al final. MongoMaxKey no tiene ni campos, ni mtodos, ni constantes asociados. Es simplemente el valor "ms alto" que se puede insertar en la base de datos.

Clases sinopsis

MongoMaxKey

MongoMaxKey { }

Usando MongoMaxKey como valor

<?php $collection->insert(array("tarea" => "fregar platos", "hacer el" => new MongoMaxKey)); $collection->insert(array("tarea" => "reunin de personal", "hacer el" => new MongoDate(strtotime("+4 days")))); $cursor = $collection->find()->sort(array("hacer el" => 1)); ?>

El cursor contendr el documento de la reunin de personal, y despus el documento de fregar platos. El documento de fregar platos siempre ser el ltimo, independientemente de lo que aadamos a la coleccin (a no ser que se aadan otros documentos con MongoMaxKey en el campo "hacer el").

Driver nativo MongoDB

223

Clase MongoTimestamp

Introduccin
MongoTimestamp se usa para sharding (particionamiento horizontal de BD). Si no se van a usar herramientas de sharding, se recomienda usar MongoDate. MongoTimestamp es un timestamp de 4 bytes (segundos a partir de la fecha de referencia) y 4 bytes de incremento. Esta clase no es para medir tiempo, creando un timestamp en un documento o aadiendo/actualizando el timestamp de un documento. A no ser que se est usando algo que interacte con sharding, detngase, y vaya directamente a MongoDate, no est aqu de paso. sta no es la clase que est buscando. Si est escribiendo herramientas de sharding, contine.

Clases sinopsis

MongoTimestamp

MongoTimestamp { /* Campos */ public int sec = 0; public int inc = 0; /* Mtodos */ MongoTimestamp::__construct ( [ int $sec = time() [, int $inc ] ] ) public string MongoTimestamp::__toString ( void ) }

Driver nativo MongoDB

224

MongoTimestamp::__construct
MongoTimestamp::__construct -- Crea un nuevo timestamp

Descripcin
MongoTimestamp::__construct ( [ int $sec = time() [, int $inc ] ] ) Crea un nuevo timestamp. Si no se rellenan los parmetros, se usa la hora actual con incremento automtico. El incremento se establece a 0 cuando se carga el mdulo, y se incrementa cada vez que se invoca a este constructor (cuando no se rellene el parmetro $inc).

Parmetros
sec

Nmero de segundos desde el 1 de enero de 1970.

inc

Incremento.

Valores devueltos
Devuelve el nuevo timestamp.

Ver tambin

MongoTimestamp::__toString

Driver nativo MongoDB

225

MongoTimestamp::__toString
MongoTimestamp::__toString -- Devuelve la representacin en forma de texto de este timestamp

Descripcin
public string MongoTimestamp::__toString ( void ) Devuelve el campo "sec" del timestamp.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Los segundos desde la fecha de referencia que rerpesenta este timestamp.

Driver nativo MongoDB

226

Clases de GridFS

Driver nativo MongoDB

227

Clase MongoGridFS

Introduccin
Utilidad para almacenar y extraer ficheros de la base de datos. GridFS es una especificacin de almacenamiento que implementan todos los drivers soportados. En resumen, define dos colecciones: files, para los metadatos del fichero, y chunks, para el contenido del fichero. Si el fichero fuera de gran tamao, automticamente se dividira en porciones menores, y cada bloque se guardar como un documento en la coleccin de bloques. Cada documento de la coleccin de ficheros contiene el nombre de fichero, fecha de subida, y un cdigo hash md5. Tambin contiene un campo nico _id, que se puede utilizar para consultar el contenido del fichero en la coleccin de bloques. Cada documento de la coleccin de bloques contiene un bloque de datos binarios, un campo files_id que se corresponde con el _id de su fichero, y la posicin de este bloque respecto a los dems. Por ejemplo, el documento de ficheros podra ser algo tal que as:
<?php array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12); ?>

mientras que los documentos de bloques:

<?php array("files_id" array("files_id" array("files_id" array("files_id" ?> => => => => 123456789, 123456789, 123456789, 123456789, "n" "n" "n" "n" => => => => 0, 1, 2, 3, "data" "data" "data" "data" => => => => new new new new MongoBinData("abc")); MongoBinData("def")); MongoBinData("ghi")); MongoBinData("jkl"));

Por supuesto, el tamao por omisin de los bloques es en realidad de miles de bytes.

Compatibilidad Entre Lenguajes

Se puede usar cualquier fichero creado con MongoGridFS con cualquier otro driver y viceversa. Sin embargo, algunos drivers esperan que todos los metadatos asociados con un fichero se encuentren en el campo "metadata". Si se preve que se utilizar con otros lenguajes, es una buena idea empaquetar en un campo "metadata" toda la informacin que se desee que vean. Por ejemplo, en lugar de:
<?php $grid->storeFile("algunfichero.txt", array("date" => new MongoDate())); ?>

utilice algo as:

Driver nativo MongoDB

228

<?php $grid->storeFile("algunfichero.txt", array("metadata" => array("date" => new MongoDate()))); ?>

La Familia MongoGridFS
MongoGridFS representa los ficheros y las colecciones de bloques. MongoGridFS hereda MongoCollection. Las instancias de MongoGridFS tienen acceso a todos los mtodos de MongoCollection, que actan sobre las colecciones de ficheros:
<?php $grid = $db->getGridFS(); $grid->update(array("filename" => "foo"), $newObj); // actualizacin en la coleccin de ficheros ?>

Otro ejemplo de manipulacin de metadatos:

<?php // guardar un fichero $id = $grid->storeFile("juego.tgz"); $juego = $grid->findOne(); // aadir un contador de descargas $juego->file['descargas'] = 0; $grid->save($juego->file); // incrementar el contador $grid->update(array("_id" => $id), array('$inc' => array("descargas" => 1))); ?>

Se puede tambin acceder a los bloques de una coleccin a partir de una instancia de MongoGridFS:
<?php $chunks = $grid->chunks; // $chunks es un MongoCollection normal $chunks->insert(array("x" => 4)); ?>

Hay algunos mtodos de MongoGridFS que comparten nombres con mtodos de MongoCollection, pero que se comportan de un modo ligeramente diferente. Por ejemplo, Driver nativo MongoDB 229

MongoGridFS::remove() eliminar cualquier objeto, junto con su contenido en la coleccin de bloques, cuando se cumplan los criterios de la coleccin de ficheros. Para almacenar cualquier otra cosa en GridFS, hay varias opciones. Si se tuviera un nombre de fichero, se podra hacer:
<?php $grid->storeFile($filename, array("cualquier" => "metadato", "que" => "desee")); ?>

Si se tuviera un string de bytes que no fuera un fichero, se podr tambien almacenar usando MongoGridFS::storeBytes():
<?php $grid->storeBytes($bytes, array("cualquier" => "metadato", "que" => "desee")); ?>

Al consultar a una coleccin MongoGridFS, se devolver un MongoGridFSCursor, que se comporta como un MongoCursor convencional, excepto que devuelve un MongoGridFSFiles en lugar de una matriz asociativa. MongoGridFSFiles puede volver a escribirse en disco usando MongoGridFSFile::write(), o en memoria usando MongoGridFSFile::getBytes(). Actualmente no existe ningn mtodo que cree automticamente un flujo de bloques, pero resulta muy sencillo hacer escrituras realizando consultas a la coleccin $grid->chunks. El objeto MongoGridFSFile contiene un campo file (fichero) que contiene cualquier metadato del fichero.

Clases sinopsis

MongoGridFS

extends MongoCollection { /* Campos */ public MongoCollection chunks = NULL; protected string filesName = NULL;

Driver nativo MongoDB

230

protected string chunksName = NULL; /* Mtodos */ MongoGridFS::__construct ( MongoDB $db [, string $prefix = "fs" [, mixed $ chunks = "fs" ] ] ) public bool MongoGridFS::delete ( mixed $id ) public array MongoGridFS::drop ( void ) public MongoGridFSCursor MongoGridFS::find ( [ array $query = array() [, array $ fields = array() ] ] ) public MongoGridFSFile MongoGridFS::findOne ( [ mixed $query = array() [, mixed $fields = array() ] ] ) public MongoGridFSFile MongoGridFS::get ( mixed $id ) public mixed MongoGridFS::put ( string $filename [, array $extra = array() ] ) public bool MongoGridFS::remove ( [ array $criteria = array() [, array $options = array() ] ] ) public mixed MongoGridFS::storeBytes ( string $bytes [, array $extra = array() [, array $options = array() ] ] ) public mixed MongoGridFS::storeFile ( string $filename [, array $extra = array() [, array $options = array() ] ] ) public mixed MongoGridFS::storeUpload ( string $name [, array $metadata ] ) }

Ver tambin
Documentacin principal de MongoDB de GridFS. Hay tambin una buena introduccin a cmo guardar datos subidos por usuarios y a cmo aadir metadatos en LightCubeSolutions.com.

Driver nativo MongoDB

231

MongoGridFS::__construct
MongoGridFS::__construct -- Crea una nueva coleccin de ficheros

Descripcin
MongoGridFS::__construct ( MongoDB $db [, string $prefix = "fs" [, mixed $chunks = "fs" ] ] ) Los ficheros se almacenan en dos colecciones. La primera contiene informacin descriptiva de los ficheros. La segunda contiene los bloques del contenido real del fichero. Por omisin, los nombres que se usan para las colecciones son fs.files y fs.chunks. Mediante un argumento puede especificar un prefijo distinto a "fs":$fs = new MongoGridFS($db, "misficheros"); esto utilizara las colecciones misficheros.files y misficheros.chunks.

Parmetros
db

Base de datos.
files

Prefijo opcional para el nombre de la coleccin.

Driver nativo MongoDB

232

MongoGridFS::delete
MongoGridFS::delete -- Elimina un fichero de la base de datos

Descripcin
public bool MongoGridFS::delete ( mixed $id )

Parmetros
id

_id del fichero a eliminar.

Valores devueltos
Devuelve un indicador de si la orden de eliminacin se envi o no con xito a la base de datos.

Driver nativo MongoDB

233

MongoGridFS::drop
MongoGridFS::drop -- Da de baja una coleccin de ficheros y de bloques

Descripcin
public array MongoGridFS::drop ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Respuesta de la base de datos.

Driver nativo MongoDB

234

MongoGridFS::find
MongoGridFS::find -- Selecciona ficheros

Descripcin
public MongoGridFSCursor MongoGridFS::find ( [ array $query = array() [, array $ fields = array() ] ] )

Parmetros
query

La consulta
fields

Campos que devolver.

Valores devueltos
Un objeto de la clase MongoGridFSCursor.

Driver nativo MongoDB

235

MongoGridFS::findOne
MongoGridFS::findOne -- Devuelve el fichero que cumpla las condiciones

Descripcin
public MongoGridFSFile MongoGridFS::findOne ( [ mixed $query = array() [, mixed $ fields = array() ] ] )

Parmetros
query

El nombre del fichero o las condiciones de bsqueda.

Valores devueltos
Devuelve un MongoGridFSFile o NULL.

Ejemplos
Ejemplo #1 - Ejemplo de MongoGridFS::findOne Ejemplo que muestra cmo localizar un fichero de MongoGridFS.
<?php $descargas = $mongo->my_db->getGridFS('descargas'); $descargas->storeFile('nombredefichero.tgz'); $descarga = $downloads->findOne('nombredefichero.tgz'); // instancia de MongoGridFSFile print_r($descarga); ?>

Vea MongoGridFSFile para ms informacin sobre cmo trabajar con ficheros. El resultado del ejemplo sera algo similar a:
MongoGridFSFile Object ( [file] => Array ( [_id] => MongoId Object ( ) [filename] => nombredefichero.tgz

Driver nativo MongoDB

236

[uploadDate] => MongoDate Object ( [sec] => 1274288014 [usec] => 467000 ) [chunkSize] => 262144 [md5] => d41d8cd98f00b204e9800998ecf8427e ) [gridfs:protected] => MongoGridFS Object ( [chunks] => MongoCollection Object ( ) [filesName:protected] => descargas.files [chunksName:protected] => descargas.chunks ) )

Driver nativo MongoDB

237

MongoGridFS::get
MongoGridFS::get -- Obtiene un fichero de la base de datos

Descripcin
public MongoGridFSFile MongoGridFS::get ( mixed $id )

Parmetros
id

_id del fichero a localizar.

Valores devueltos
Devuelve el fichero si se le encuentra, o NULL.

Driver nativo MongoDB

238

MongoGridFS::put
MongoGridFS::put -- Almacena un fichero en la base de datos

Descripcin
public mixed MongoGridFS::put ( string $filename [, array $extra = array() ] )

Parmetros
filename

Nombre del fichero.

extra

Otra metainformacin a aadir junto con el fichero almacenado.

Valores devueltos
Devuelve el _id del objeto guardado.

Driver nativo MongoDB

239

MongoGridFS::remove
MongoGridFS::remove -- Elimina ficheros de las colecciones

Descripcin
public bool MongoGridFS::remove ( [ array $criteria = array() [, array $options = array() ] ] )

Parmetros
query

Nombre de fichero o condiciones de bsqueda.

options

Opciones para la eliminacin. Las opciones vlidas son: "safe" Comprobar que la eliminacin ha tenido xito.

Valores devueltos
Devuelve un indicador sobre si la eliminacin se envi o no con xito a la base de datos.

Driver nativo MongoDB

240

MongoGridFS::storeBytes
MongoGridFS::storeBytes -- Fragmenta y almacena bytes en la base de datos

Descripcin
public mixed MongoGridFS::storeBytes ( string $bytes [, array $extra = array() [, array $options = array() ] ] )

Parmetros
bytes

Un string con los bytes a almacenar.

extra

Otra metainformacin a aadir junto con el fichero guardado.

options

Opciones para el guardado. "safe" Comprueba que el guardado tuvo xito.

Valores devueltos
El _id del objeto guardado.

Errores/Excepciones
Lanza MongoCursorException si se estableci la opcin "safe" y la insercin falla.

Driver nativo MongoDB

241

MongoGridFS::storeFile
MongoGridFS::storeFile -- Almacena un fichero en la base de datos

Descripcin
public mixed MongoGridFS::storeFile ( string $filename [, array $extra = array() [, array $options = array() ] ] )

Parmetros
filename

Nombre del fichero.

extra

Otra metainformacin a aadir junto con el fichero guardado.

options

Opciones para el guardado. "safe" Comprueba que el guardado tuvo xito.

Valores devueltos
Devuelve el _id del objeto guardado.

Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" est establecida y la insercin falla.

Driver nativo MongoDB

242

MongoGridFS::storeUpload
MongoGridFS::storeUpload -- Guarda en la base de datos un fichero subido

Descripcin
public mixed MongoGridFS::storeUpload ( string $name [, array $metadata ] ) Almacena los archivos directamente desde un POST a la base de datos. Por ejemplo, suponga que tiene el siguiente formulario HTML:
<form method="POST" enctype="multipart/form-data"> Por favor, sube una imagen de perfil: <input type="file" name="pic"/> <input type="submit"/> </form>

Si quisiera almacenar este perfil en MongoDB, se puede hacer:

<?php $grid->storeUpload("pic", array("username" => "joe")); ?>

Tenga en cuenta que el campo "name" en HTML coincide con el parmetro name.

Parmetros
name

El campo name del archivo cargado.

metadata

Una array de campos adicionales para el archivo cargado.

Valores devueltos
Devuelve el _id del archivo cargado.

Historial de cambios

Versin 1.2.5

Descripcin Cambiado el segundo parmetro a un array de metadatos. Antes de la versin 1.2.5, el segundo parmetro fue un string opcional reemplazando el nombre de archivo. 243

Driver nativo MongoDB

Clase MongoGridFSFile

Introduccin
Objeto fichero de una base de datos.

Clases sinopsis

MongoGridFSFile

MongoGridFSFile { /* Campos */ public array file = NULL; protected MongoGridFS gridfs = NULL; /* Mtodos */ MongoGridfsFile::__construct ( MongoGridFS $gridfs, array $file ) public string MongoGridFSFile::getBytes ( void ) public string MongoGridFSFile::getFilename ( void ) public int MongoGridFSFile::getSize ( void ) public int MongoGridFSFile::write ( [ string $filename = NULL ] ) }

Driver nativo MongoDB

244

MongoGridfsFile::__construct
MongoGridfsFile::__construct -- Crea un nuevo fichero GridFS

Descripcin
MongoGridfsFile::__construct ( MongoGridFS $gridfs, array $file )

Parmetros
gridfs

La instancia padre de MongoGridFS.

file

Un fichero de la base de datos.

Valores devueltos
Devuelve un nuevo MongoGridFSFile.

Driver nativo MongoDB

245

MongoGridFSFile::getBytes
MongoGridFSFile::getBytes -- Devuelve el contenido de este fichero en forma de string de bytes

Descripcin
public string MongoGridFSFile::getBytes ( void ) Aviso: se cargar el fichero en memoria. Si el fichero es de mayor tamao que la memoria, provocar un problema.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve un string con los bytes del fichero.

Ejemplos
Ejemplo #1 - Ejemplo de MongoGridFSFile::getBytes
<?php $images = $db->my_db->getGridFS('images'); $image = $images->findOne('jwage.png'); header('Content-type: image/png;'); echo $image->getBytes(); ?>

Driver nativo MongoDB

246

MongoGridFSFile::getFilename
MongoGridFSFile::getFilename -- Devuelve el nombre de este fichero

Descripcin
public string MongoGridFSFile::getFilename ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nombre de fichero.

Driver nativo MongoDB

247

MongoGridFSFile::getSize
MongoGridFSFile::getSize -- Devuelve el tamao de este fichero

Descripcin
public int MongoGridFSFile::getSize ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el tamao de este fichero

Driver nativo MongoDB

248

MongoGridFSFile::write
MongoGridFSFile::write -- Escribe este fichero en disco

Descripcin
public int MongoGridFSFile::write ( [ string $filename = NULL ] )

Parmetros
filename

La ubicacin en la que se escribir el fichero. Si no se da ninguno, se usar el nombre del fichero almacenado.

Valores devueltos
Devuelve el nmero de bytes escritos.

Ejemplos
Ejemplo #1 - Ejemplo de MongoGridFSFile::write
<?php $images = $db->my_db->getGridFS('images'); $image = $images->findOne('jwage.png'); $image->write('/path/to/write/jwage.png'); ?>

Driver nativo MongoDB

249

Clase MongoGridFSCursor

Introduccin
Cursor para los resultados de ficheros de bases de datos.

Clases sinopsis

MongoGridFSCursor

extends MongoCursor { /* Campos */ protected MongoGridFS gridfs = NULL; /* Mtodos */ MongoGridFSCursor::__construct ( MongoGridFS $gridfs, resource $connection, string $ns, array $query, array $fields ) public MongoGridFSFile MongoGridFSCursor::current ( void ) public MongoGridFSFile MongoGridFSCursor::getNext ( void ) public string MongoGridFSCursor::key ( void ) }

Driver nativo MongoDB

250

MongoGridFSCursor::__construct
MongoGridFSCursor::__construct -- Crea un nuevo cursor

Descripcin
MongoGridFSCursor::__construct ( MongoGridFS $gridfs, resource $connection, string $ns, array $query, array $fields )

Parmetros
gridfs

Coleccin GridFS relacionada.

connection

Conexin a la base de datos.

ns

Nombre completo de la base de datos y de la coleccin.

query

Consulta a la base de datos.

fields

Campos que se desea obtener.

Valores devueltos
Devuelve el nuevo cursor.

Driver nativo MongoDB

251

MongoGridFSCursor::current
MongoGridFSCursor::current -- Devuelve el fichero actual

Descripcin
public MongoGridFSFile MongoGridFSCursor::current ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Fichero actual.

Driver nativo MongoDB

252

MongoGridFSCursor::getNext
MongoGridFSCursor::getNext -- Devuelve el siguiente fichero al que apunta este cursor, y avanza el cursor

Descripcin
public MongoGridFSFile MongoGridFSCursor::getNext ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el siguiente fichero.

Driver nativo MongoDB

253

MongoGridFSCursor::key
MongoGridFSCursor::key -- Devuelve el nombre de fichero del resultado actual

Descripcin
public string MongoGridFSCursor::key ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Nombre de fichero del resultado actual.

Driver nativo MongoDB

254

Miscelnea

Driver nativo MongoDB

255

Clase MongoLog

Introduccin
Se puede utilizar para obtener informacin detallada sobre qu est realizando el driver. Con PHP-CLI, los informes se pueden redirigir a stderr. En un servidor de aplicaciones, los mensajes generalmente se imprimiran en un registro de errores. Por omisin, estos registros estn deshabilitados. Esta clase permite habilitar niveles especficos de informes para determinadas reas del driver. Algunos ejemplos:
<?php // muestra todos los mensajes posibles MongoLog::setLevel(MongoLog::ALL); // todos los niveles de registros MongoLog::setModule(MongoLog::ALL); // todas las partes del driver // muestra eventos significativos sobre fallos en conjuntos de rplicas MongoLog::setLevel(MongoLog::INFO); MongoLog::setModule(MongoLog::RS); // muestra registros de nivel de informacin y de seguimiento sobre conjuntos de rplicas y sobre agrupamientos de conexiones MongoLog::setLevel(MongoLog::INFO|MongoLog::TRACE); MongoLog::setModule(MongoLog::RS|MongoLog::POOL); ?>

Clases sinopsis

MongoLog

MongoLog { /* Constantes */ const int MongoLog::NONE; const int MongoLog::ALL; constantes de niveles { const int MongoLog::WARNING; const int MongoLog::INFO;

Driver nativo MongoDB

256

const int MongoLog::FINE; constantes de mdulos { const int MongoLog::RS; const int MongoLog::POOL; const int MongoLog::IO; /* Campos */ public int level; public int module; /* Mtodos */ MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] ) public string MongoDate::__toString ( void ) }

Constantes predefinidas Constantes de MongoLog

Estas constantes pueden usarse tanto por MongoLog::setLevel() como por MongoLog::setModule(). MongoLog::NONE Constante para deshabilitar los registros. MongoLog::ALL Constante para notificar todos los registros.

Constantes de Nivel de MongoLog

Estas constantes pueden usarse por MongoLog::setLevel(). MongoLog::WARNING Muestra mensajes sobre situaciones excepcionales no crticas. MongoLog::INFO Muestra eventos que pudieran ser de interes para administradores, pero no especialmente notorios. MongoLog::FINE Driver nativo MongoDB 257

Muestra la mayor parte de eventos que realiza el driver. Dependiendo del mdulo que se est analizando, este nivel podra ser demasiado ruidoso. Se usa principalmente para depuracin.

Constantes de mdulos de MongoLog

Estas constantes pueden usarse por MongoLog::setModule(). MongoLog::RS Registra las actividades de los conjuntos de rplicas. Cadas, comprobaciones, eleccin de secundarios a los que leer, etc.. MongoLog::POOL Registra las actividades de los agrupamientos de conexiones. Creacin de nuevas conexiones, reutilizacin de conexiones, y cierre de conexiones. MongoLog::IO Registra el trfico de y desde la base de datos. Este modo generar un gran nmero de mensajes de registro, salvo en el caso de que la aplicacin sea trivial.

Driver nativo MongoDB

258

MongoLog::getLevel
MongoLog::getLevel -- Obtiene el nivel de registro

Descripcin
public static int MongoLog::getLevel ( void ) Esto puede ser usado para ver el nivel de registro. Utilice las constantes descritas en la seccin MongoLog con los operadores bit a bit para comprobar el nivel.
<?php if (MongoLog::getLevel() & MongoLog::FINE) { echo "un montn de logs\n"; } if (MongoLog::getLevel() ^ MongoLog::NONE) { echo "logging, al menos un poco\n"; } if (MongoLog::getLevel() == MongoLog::ALL) { echo "logging al ms alto nivel\n"; } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve el nivel actual.

Driver nativo MongoDB

259

MongoLog::getModule
MongoLog::getModule -- Devuelve los mdulos que estn actualmente se estn registrando

Descripcin
public static int MongoLog::getModule ( void ) Esta funcin se puede usar para conocer qu partes del driver se estn registrando. Utilice las constantes descritas en la seccin de MongoLog con operadores a nivel de bits para comprobar si algn mdulo especfico est siendo registrado.
<?php if (MongoLog::getModule() & MongoLog::RS) { echo "registrando conjuntos de rplicas\n"; } if (MongoLog::getModule() ^ MongoLog::NONE) { echo "registrando algo\n"; } if ((MongoLog::getModule() & MongoLog::IO) == 0) { echo "no se estn registrando entradas/salidas\n"; } ?>

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Devuelve los mdulos que actualmente se estn registrando.

Driver nativo MongoDB

260

MongoLog::setLevel
MongoLog::setLevel -- Establece el nivel de informe de mensajes

Descripcin
public static void MongoLog::setLevel ( int $level ) Esta funcin se puede usar para establecer el nivel de detalles que se mostrarn, as como el tipo de informacin que se registrar. Utilice las constantes descritas en la seccin MongoLog con operadores a nivel de bits para especificar estos niveles.
<?php // primero, habilitamos todos los mensajes para un mdulo MongoLog::setModule(MongoLog::POOL);

// registramos los mensajes de todos los niveles MongoLog::setLevel(MongoLog::ALL); // registramos mensaje de tipo 'aviso' e informativos MongoLog::setLevel(MongoLog::WARNING|MongoLog::INFO); // registramos todo, excepto actividades de grano fino MongoLog::setLevel(MongoLog::ALL & (~MongoLog::FINE)); ?>

Tenga presente que tambin puede llamar a MongoLog::setModule() para escoger qu partes del driver registrar.

Parmetros
level

Nivel que se desea registrar.

Driver nativo MongoDB

261

MongoLog::setModule
MongoLog::setModule -- Establece de qu funcionalidades se deben notificar eventos

Descripcin
public static void MongoLog::setModule ( int $module ) Esta funcin puede usarse para establecer de qu partes del driver se deben registrar eventos. Para especificar los mdulos, utilice las constantes descritas en la seccin MongoLog con operadores a nivel de bits.
<?php // primero, habilitamos todos los niveles de registro MongoLog::setLevel(MongoLog::ALL);

// registramos las actividades de conjuntos de rplicas MongoLog::setModule(MongoLog::RS); // registramos las actividades de conjuntos de rplicas y de agrupamientos de conexiones MongoLog::setModule(MongoLog::RS|MongoLog::ALL); // registramos todo excepto actividades de E/S MongoLog::setModule(MongoLog::ALL & (~MongoLog::IO)); ?>

Tenga presente que tambin se puede invocar a MongoLog::setLevel() para habilitar el registro de mensajes.

Parmetros
module

El/los mdulo/s que desea registrar.

Driver nativo MongoDB

262

Clase MongoPool

Introduccin
En la versin 1.2.0 del driver se incorporaron los agrupamiento (pools) de conexiones. Esta clase ofrece herramientras de control e informacin sobre agrupamientos.

Nota Originalmente, las funciones de esta clase eran miembros estticos de Mongo. Se recomienda encarecidamente utilizar esta clase en un futuro, ya que las funciones estticas de Mongo estn consideradas obsoletas.

Clases sinopsis

MongoPool

MongoPool { /* Mtodos */ public static int MongoPool::getSize ( void ) public array MongoPool::info ( void ) public static bool MongoPool::setSize ( int $size ) }

Driver nativo MongoDB

263

MongoPool::getSize
MongoPool::getSize -- Devuelve el tamao actual de un agrupamiento de conexiones

Descripcin
public static int MongoPool::getSize ( void )

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Retorna el tamao actual del agrupamiento.

Ejemplos
Ejemplo #1 - Cambiar el tamao de un agrupamiento Devuelve el tamao por omisin del agrupamiento, esatblece un nuevo tamao, y muestra el nuevo tamao junto con informacin de depuracin. Tenga presente que esta accin slo afecta a las nuevas conexiones; no modifica las anteriores.
<?php $connection = new Mongo("host1"); // tamao de agrupamiento: -1 echo "tamao de agrupamiento: ".MongoPool::getSize()."\n"; echo "establecemos un tamao de agrupamiento de 200\n"; MongoPool::setSize(200); // tamao de agrupamiento: 200 echo "tamao de agrupamiento: ".MongoPool::getSize()."\n"; $conn2 = new Mongo("host2"); // conexiones disponibles en host1: -2 // conexiones disponibles en host2: 199 var_dump(Mongo::poolDebug()); ?>

Ver tambin
Driver nativo MongoDB 264

 MongoPool::setSize() MongoPool::info() Documentacin sobre conexiones.

Driver nativo MongoDB

265

MongoPool::info
MongoPool::info -- Devuelve informacin sobre todos los agrupamientos de conexiones

Descripcin
public array MongoPool::info ( void ) Devuelve un array con informacin sobre los agrupamientos de conexiones.

Parmetros
Esta funcin no tiene parmetros.

Valores devueltos
Cada agrupamiento de conexin tiene un identificador, que comienza con el nombre de host. Se muestra la siguiente informacin para cada agrupamiento:
in use

Nmero de conexiones actualmente en uso por instancias de Mongo.

in pool

Nmero de conexiones que hay actualmente en el agrupamiento (sin usar).

remaining

Nmero de conexiones que se pueden crear en este agrupamiento. Por ejemplo, supongamos que un agrupamiento tena 5 conexiones pendientes y 3 conexiones en agrupamiento. Podramos crear 8 nuevas instancias de Mongo antes de agotar este agrupamiento (asumiendo que ninguna instancia de Mongo qued fuera de mbito, devolviendo sus conexiones al agrupamiento). Un nmero negativo indica que este agrupamiento puede lanzar conexiones ilimitadas. Antes de crear un agrupamiento, se puede cambiar su nmero mximo de conexiones invocando a Mongo::setPoolSize(). Una vez que se ha llamado a esta funcin, no se podr modificar su tamao.
total

Nmero total de conexiones permitidas en este agrupamiento. Ser mayor o igual a la suma de "in use" + "in pool" (o -1).
timeout

Tiempo mximo de espera para las conexiones de este agrupamiento. Indica por cunto tiempo las conexiones intentarn conectar con un servidor antes de darse por vencidas.
waiting

Si se ha restringido el tamao del agrupamiento, los procesos que soliciten conexiones de este agrupamiento podrn quedarse bloqueados hasta que otros procesos devuelvan sus conexiones. Este campo indica por cuntos Driver nativo MongoDB 266

milisegundos quedarn bloqueados esperando a que se libere una conexin. Si este nmero creciera demasiado, quizs sea conveniente usar MongoPool::setSize() para aadir ms conexiones al agrupamiento.

Driver nativo MongoDB

267

MongoPool::setSize
MongoPool::setSize -- Establece el tamao de los nuevos agrupamientos de conexiones

Descripcin
public static bool MongoPool::setSize ( int $size ) Establece el nmero mximo de conexiones que podrn crear los nuevos agrupamientos.

Parmetros
size

Nmero mximo de conexiones que podrn crear los nuevos agrupamientos. Un nmero negativo indica que el agrupamiento podr lanzar un nmero infinito de conexiones.

Valores devueltos
Devuelve el valor anterior de tamao de agrupamiento.

Ejemplos

Ejemplo #1 - Ejemplo de Mongo::setPoolSize() Si se establece un tamao de agrupamiento de n y creamos n conexiones, al intentar crear la conexin n+1 se lanzar una excepcin de tipo MongoConnectionException.
<?php // slo permitimos una conexin al servidor MongoPool::setSize(1); // creamos una conexin a localhost:27017 $m1 = new Mongo(); // intentamos crear una segunda conexin a localhost:27017 // puesto que slo se permite una, se emitir una excepcin $m2 = new Mongo(); ?>

El resultado del ejemplo sera algo similar a:

Driver nativo MongoDB

268

Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10 Stack trace: #0 /path/to/php/script.php(10): Mongo->__construct() #1 {main} thrown in /path/to/php/script.php on line 10

Ver tambin

MongoPool::getSize() MongoPool::info() Documentacin sobre conexiones.

Driver nativo MongoDB

269

Funciones

Driver nativo MongoDB

270

Funciones de Mongo

Driver nativo MongoDB

271

bson_decode
bson_decode -- Decodifica un objecto BSON a un array PHP

Descripcin
array bson_decode ( string $bson ) Esta funcin es muy beta todava y es intil para el 99% de usuarios. Solo es til en casos especiales, como cuando se necesita escribir tu propio driver encima del driver de PHP.

Parmetros
bson

El BSON a ser decodificado.

Valores devueltos
Devuelve un objecto BSON decodificado.

Driver nativo MongoDB

272

bson_encode
bson_encode -- Serializa una variable PHP a un string BSON

Descripcin
string bson_encode ( mixed $anything ) Esta funcin es muy beta todava y es intil para el 99% de usuarios. Solo es til en casos especiales, como cuando se necesita escribir tu propio driver encima del driver de PHP.

Parmetros
anything

La variable ha serializar.

Valores devueltos
Devuelve un string serializado.

Driver nativo MongoDB

273

Excepciones

Peculiaridades en VMWare
Si se est ejecutando VMWare en Windows, y se usa CIFS, al pausar la mquina virtual se desincronizar CIFS causando errores inesperados al volver a ponerlo en funcionamiento ("El objeto Mongo no se ha inicializado correctamente por su constructor"). Si se monta de forma permanente los compartidos de Windows, se corregir este problema y ya se podr pausar y reiniciar. Para montar permanentemente los compartidos de Windows, ejecute:
$ sudo update-rc.d -f umountnfs.sh remove $ sudo update-rc.d umountnfs.sh stop 15 0 6 .

Consulte la documentacin de Ubuntu para ver las instrucciones ms actualizadas.

Driver nativo MongoDB

274

Clase MongoException

Introduccin
Excepcin Mongo predeterminada. Abarca un gran nmero de condiciones de error que, eventualmente, podrn moverse a excepciones ms especficas, pero que en cualquier caso siempre extendern MongoException.

The MongoSomething object has not been correctly initialized by its constructor Cdigo: 0 Probablemente tu objeto Mongo no est conectado al servidor de bases de datos. zero-length keys are not allowed, did you use $ with double quotes? Cdigo: 1 Se ha intentado guardar el valor "" como clave. En general, no se debe hacer esto. "" podra provocar errores al acceder a subobjetos, adems de que es usado internamente por MongoDB. Sin embargo, si realmente quiere, puede asignar en su fichero php.ini el valor true a mongo.allow_empty_keys para sobrescribir esta comprobacin. Si se sobrescribe, se recomienda encarecidamente establecer la comprobacin estricta de errores para evitar errores de interpolacin de textos. '.' not allowed in key: <key> Cdigo: 2 Se ha intentado escribir una clave que contiene un ".", lo cual est prohibido. insert too large: <size>, max: <max> Cdigo: 3 Se ha intentado enviar demasiada informacin de una vez a la base de datos: la base de datos slo acepta inserciones de hasta un determinado tamao (actualmente 16 MB). no elements in doc Cdigo: 4 Se ha intentado guardar un documento que no contiene ningn campo. size of BSON doc is <size> bytes, max <max>MB Cdigo: 5 Se ha intentado guardar un documento con un tamao superior al que MongoDB puede guardar. no documents given Cdigo: 6 Se ha intentado insertar por lotes un array vaco de documentos. MongoCollection::group takes an array, object, or MongoCode key Cdigo: 7 Se han enviado a MongoCollection::group() parmetros del tipo equivocado field names must be strings Cdigo: 8 Deben formatearse los selectores de la siguiente forma: array("field1" => 1, "field2" => 1, ..., "fieldN" => 1). invalid regex Cdigo: 8 La expresin regular pasada a MongoRegex no cumple la forma correcta. MongoDBRef::get: $ref field must be a string Cdigo: 10 MongoDBRef::get: $db field must be a string Cdigo: 11 Driver nativo MongoDB 275

 non-utf8 string: <str> Cdigo: 12 Sucede cuando se intenta enviar un texto que no es utf8 a la base de datos. Todos los textos que se enven a la base de datos deben estar en UTF8. Revise las opciones de php.ini para conocer la opcin de transicin que evita esta excepcin. mutex error: <err> Cdigo: 13 En entornos multihebra, el driver utiliza mutex para sincronizar las peticiones y las respuestas. Este es un error crtico que no se puede trazar. Es poco usual y debe notificarse a los mantenedores junto con cualquier informacin del sistema y los pasos que se han seguido para reproducir el error. index name too long: <len>, max <max> characters Cdigo: 14 No se crearn ndices con nombres superiores a 128 caracteres. Si se obtuviera este error, se debera usar la opcin "name" de MongoCollection::ensureIndex() para crear un nombre ms corto para el ndice.

Clases sinopsis

MongoException

extends Exception { }

Driver nativo MongoDB

276

The MongoCursorException class

Introduccin
Caused by accessing a cursor incorrectly or a error receiving a reply. Note that this can be thrown by any database request that receives a reply, not just queries. Writes, commands, and any other operation that sends information to the database and waits for a response can throw a MongoCursorException. The only exception is new Mongo() (creating a new connection), which will only throw MongoConnectionException s. This returns a specific error message to help diagnose the problem and a numeric error code associated with the cause of the exception. For example, suppose you tried to insert two documents with the same _id:
<?php try { $collection->insert(array("_id" => 1), array("safe" => true)); $collection->insert(array("_id" => 1), array("safe" => true)); } catch (MongoCursorException $e) { echo "error message: ".$e->getMessage()."\n"; echo "error code: ".$e->getCode()."\n"; } ?>

This would produce output like:

error message: E11000 duplicate key error index: foo.bar.$_id_ { : 1 } error code: 11000 dup key:

Note that the MongoDB error code (11000) is used for the PHP error code. The PHP driver uses the "native" error code wherever possible. The following is a list of common errors, codes, and causes. Exact errors are in italics, errors where the message can vary are described in obliques.

cannot modify cursor after beginning iteration Code: 0 You are calling a method that sets up the query after executing the query. Reset the cursor and try again. An example:
<?php try { $cursor = $collection->find(); var_dump($cursor->getNext()); // getNext() queried the database, it's too late to set a limit $cursor->limit(1); } catch (MongoCursorException $e) {

Driver nativo MongoDB

277

echo "error message: ".$e->getMessage()."\n"; echo "error code: ".$e->getCode()."\n"; } // this will work, though: $cursor->getNext(); $cursor->reset(); $cursor->limit(1); ?>

Get next batch send errors Code: 1 Could not send the query to the database. Make sure the database is still up and the network is okay. cursor not found Code: 2 The driver was trying to fetch more results from the database, but the database did not have a record of the query. This usually means that the cursor timed out on the server side: after a few minutes of inactivity, the database will kill a cursor (see MongoCursor::immortal() for information on preventing this). An example:
<?php try { $cursor = $collection->find(); $cursor->getNext(); // sleep for 15 minutes sleep(60*15); while ($cursor->hasNext()) { $cursor->getNext(); } } catch (MongoCursorException $e) { echo "error message: ".$e->getMessage()."\n"; echo "error code: ".$e->getCode()."\n"; } ?>

cursor->buf.pos is null Code: 3 This may indicate you are out of RAM or some other extraordinary circumstance. couldn't get response header Code: 4 A common error if the database or network goes down. This means that the driver couldn't get a response from the connection. no db response Code: 5 This may not even be an error, for example, the database command "shutdown" returns no response. However, if you were expecting a response, this means the database didn't give one. bad response length: %d, did the db assert? Code: 6 This means that the database said that its response was less than 0. This error probably indicates a network error or database corruption. incomplete header Code: 7 Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem.

Driver nativo MongoDB

278

 incomplete response Code: 8 Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem. couldn't find a response Code: 9 If the response was cached and now cannot be located. error getting socket Code: 10 The socket was closed or encountered an error. The driver should automatically reconnect (if possible) on the next operation. couldn't find reply, please try again Code: 11 The driver saves any database responses it cannot immediately match with a request. This exception occurs if the driver has already passed your request's response and cannot find your response in its cache. error getting database response: errstr WSA error getting database response: errstr "errstr" is an io error reported directly from the C socket subsystem. On Windows, the error message is prefixed with "WSA". Timeout error Code: 13 If there was an error while waiting for a query to complete. couldn't send query: <various> Code: 14 C socket error on send. max number of retries exhausted, couldn't send query Code: 19 The driver will automatically retry "plain" queries (not commands) a couple of times if the first attempt failed for certain reasons. This is to cause fewer exceptions during replica set failover (although you will probably still have to deal with some) and gloss over transient network issues. This can also be caused by the driver not being able to reconnect at all to the database (if, for example, the database is unreachable). Version 1.2.2+.

Errors passed through by the database

Database errors should always trigger MongoCursorExceptions on queries. Error messages and codes are sent directly from the database and you should be able to see matching errors in the database log. A few common database errors are listed below:

E11000 duplicate key error index: foo.bar.$X dup key: { /* ... */ } Code: 11000 Database error for duplicate keys. not master Codes: 10107, 13435, and 10058 Not master errors, piped through by the database. Each of these will cause the driver to disconnect and attempt to find a new master. The actual error you get on failover may not be a "not master" error, depending on when the change in master occurs.

Clases sinopsis

Driver nativo MongoDB

279

MongoCursorException

extends MongoException { }

Driver nativo MongoDB

280

Clase MongoCursorTimeoutException

Introduccin
Lanzado cuando se excede el tiempo mximo de espera de una consulta. Puede establecer el tiempo de espera que se usar antes de lanzar esta excepcin, llamando a MongoCursor::timeout() en el cursor, o mediante MongoCursor::$timeout. Esta variable esttica resulta til para consultas tales como comandos de la base de datos o en MongoCollection::findOne(), las cuales utilizan implcitamente cursores.

Clases sinopsis

MongoCursorTimeoutException

extends MongoCursorException { }

Driver nativo MongoDB

281

Clase MongoConnectionException

Introduccin
Lanzado cuando falla el driver al conectar a la base de datos. Existen varios mensajes de error posibles para ayudar a diagnosticar el problema de conexin:

No server name given. Este error ocurre al pasar "" como nombre de servidor, probablemente por error tipogrfico con interpolacin de strings, p.ej., "$servr" en lugar de "$server". failed to get host [hostname] or port [portnum] from [server]. Indica que el nombre del servidor est malformado. "[hostname"] y "[portnum]" sern lo que el driver haya descifrado que sean. Operation in progress Superado el tiempo de espera de conexin a la base de datos. Transport endpoint is not connected Generalmente indica que la cadena de conexin no es correcta. De hecho, el driver no puede ni encontrar el servidor de bases de datos. couldn't determine master Ninguno de los servidores de la conexin parece ser el maestro. couldn't get host info for [server] Indica que el DNS no puede resolver la direccin de servidor proporcionada. Posiblemente se trate de un error tipogrfico, por ejemplo, "server" en lugar de "$server". Invalid Argument Puede provocarse al intentar conectar a una mquina que est funcionando pero la base de datos no est funcionando. Asegrese de que ha iniciado la base de datos antes de conectar. Permission denied Significa que el socket no pudo ser abierto debido a los permisos. En las variantes de Red hat, puede ser debido a que la configuracin por defecto no permite a Apache crear conexiones de red. Puede modificarse esto ejecutando:
$ /usr/sbin/setsebool -P httpd_can_network_connect 1

y reiniciando Apache. Si el mensaje de error no se encuentra en la lista de arriba, probablemente sea un error del socket C, y podr buscar en la web la causa del mismo.

Clases sinopsis

Driver nativo MongoDB

282

MongoConnectionException

extends MongoException { }

Driver nativo MongoDB

283

Clase MongoGridFSException

Introduccin
Lanzado cuando hay errores al leer o escribir ficheros a la base de datos.

Clases sinopsis

MongoGridFSException

extends MongoException { }

Driver nativo MongoDB

284