Driver Nativo MongoDB

284
Driver nativo MongoDB

Transcript of Driver Nativo MongoDB

Page 1: Driver Nativo MongoDB

Driver nativo MongoDB

Page 2: Driver Nativo MongoDB

2Driver nativo MongoDB

Manual

Este manual trata algunos detalles sobre cómo usar MongoDB, aunque es más una referencia del driver PHP. Para más información sobre cómo diseñar un esquema, qué significa cada término, o cómo configurar el servidor de bases de datos, revise la » documentación de MongoDB.

Instalación

El controlador MongoDB para PHP debe funcionar en cualquier sistema: Windows, Mac OS X, Unix, y Linux; pequeñas y grandes máquinas; y plataformas de 32- y 64-bits; PHP 5.1, 5.2, y 5.3.

Esta extensión » PECL no se distribuye con PHP. Esta página proporciona información especifica acerca de la instalación en diferentes sistemas y solución de problemas que otros usuarios han resuelto.

• » Instalación en *NIX

• » Instalación manual

• » OS X

• » Gentoo

• » Fedora

• » Instalación en Windows

• » Instrucciones de instalación de terceros

Instalación 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 línea en el fichero php.ini:extension=mongo.so

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

Instalación manual

Page 3: Driver Nativo MongoDB

3Driver nativo MongoDB

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 botón "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:

• Asegúrese de que la variable extension_dir este apuntando a la ubicación 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'Asegúrese 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-20060613Si no es así, cambia extension_dir en php.ini o mueva mongo.so

• Para cargar la extensión en el arranque de PHP, agregar una línea:extension=mongo.so

OS X

Si su sistema no puede encontrar autoconf, necesitas instalar Xcode (disponible en el DVD de instalación).

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 están disponibles en » Github (descargue la última versión con "osx" junto con el nombre que corresponda a la versión de PHP). Extraer mongo.so desde el fichero y añadalo al directorio de extensiones de MAMP o XAMPP. Agregarextension=mongo.soal 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 versión incorrecta en libtool. Compile desde las fuentes que necesite y ejecute aclocal y autoconf.

Page 4: Driver Nativo MongoDB

4Driver nativo MongoDB

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

Red Hat

Incluye Fedora y CentOS

En estos sistemas, la configuración por omisión 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 1Y finalmente reinicie Apache. (Este comportamiento también se da con SELinux.)

Instalación en Windows

Los binarios precompilados para cada versión están 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 omisión).

El último (no publicado) código 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 versión exacta en uso. (El número 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 versión 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 línea al fichero php.ini:extension=php_mongo.dll

Instrucciones de instalación de terceros

Page 5: Driver Nativo MongoDB

5Driver nativo MongoDB

Un gran número de personas han creado excelentes tutoriales de instalación 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 instalación de Apache, PHP, Xdebug, MongoDB, y Lithium por Jon Adams.

• » Instalando MongoDB y el controlador de PHP en Ubuntu 9.04 Artículo en castellano por Javier Aranda ( » Traducción en inglés ).

• » OS X: Instalando MongoDB y el controlador de PHP Por Matt Butcher.

Tutorial

Introducción

Gracias al driver de PHP para MongoDB de 10gen.

Código de ejemplo para conectar, insertar documentos, consultar documentos, recorrer el resultado de una consulta, y desconectar de MongoDB. Encontrará más 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 colección (equivalente a una tabla en una base de datos relacional)$collection = $db->cartoons;

// añadir un registro$obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );$collection->insert($obj);

// añadir un nuevo registro, con un distinto "perfil"$obj = array( "title" => "XKCD", "online" => true );$collection->insert($obj);

// encontrar todo lo que haya en la colección$cursor = $collection->find();

// recorrer el resultadoforeach ($cursor as $obj) { echo $obj["title"] . "\n";}

?>

Mostrará:

Page 6: Driver Nativo MongoDB

6Driver nativo MongoDB

Calvin and HobbesXKCD

Estableciendo una Conexión

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 omisión: 27017)$connection = new Mongo( "example.com:65432" ); // conecta a un host remoto en el puerto facilitado

?>

No es necesario desconectar explícitamente de la base de datos. Cuando $connection queda fuera de ámbito, la conexión se cierra automáticamente y todos sus recursos se liberan.

Ver también

El capítulo connecting cubre los distintos tipos de conexiones.

Tanto la documentación de la API de la clase Mongo como Mongo::__construct() proporcionan un exhaustivo repaso a todas las opciones disponibles, y un gran número 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 sólo seleccionarlas.

¡Tenga cuidado con los errores tipográficos! Podría, 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!

?>

Page 7: Driver Nativo MongoDB

7Driver nativo MongoDB

Ver También

La documentación API de la clase MongoDB contiene más información sobre los objetos de bases de datos.

Obteniendo Una Colección

Para obtener una conexión 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 análogos a las tablas (para aquéllos que estén familiarizados con bases de datos relacionales).

Ver También

La documentación API de la clase MongoCollection contiene más información sobre objetos de colecciones.

Insertando un Documento

Los objetos básicos para almacenar en una colección de una base de datos son los arrays asociativos. Un "documento" cualquiera podría 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 );

Page 8: Driver Nativo MongoDB

8Driver nativo MongoDB

?>

Ver También

La documentación API de MongoCollection::insert() contiene más información sobre la inserción de datos.

Localizando documentos usando MongoCollection::findOne()

Para comprobar que el documento que insertamos en el paso anterior se encuentra ahí, podemos realizar una operación MongoCollection::findOne() para obtener un único documento de la colección. Este método es útil cuando sólo hay un documento que concuerde con la consulta, o cuando sólo 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 añadido automáticamente al documento. _id es el campo de

Page 9: Driver Nativo MongoDB

9Driver nativo MongoDB

la "clave primaria". Si el documento no especifica una, el driver la añadirá automáticamente.

Si se ha especificado un campo _id, debe ser único en toda la colección. Por ejemplo:

<?php

$db->foo->insert(array("_id" => 1), array("safe" => true));// esto emitirá una excepción$db->foo->insert(array("_id" => 1), array("safe" => true));

// aquí no habría problemas, ya que es otra colección$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 inserción. Por omisión, el driver no espera para escribir a que la base de datos responda, por lo que el driver no capturaría 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 opción "safe" (en los ejemplos anteriores se ha omitido para simplificarlos).

Ver También

MongoCollection::findOne() contiene más información sobre cómo localizar datos.

MongoId ofrece más detalles de los identificadores únicos.

La sección writes trata las escrituras seguras en mayor profundidad, así como las funciones de escritura como MongoCollection::insert(), MongoCollection::update(), o MongoCollection::remove().

Añadiendo Múltiples Documentos

Para hacer más interesante el tema de las consultas, vamos a añadir varios documentos a la colección. Estos documentos serán 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 colección arrays con conjuntos de claves diferente. A esta característica nos refereemos cuando decimos que MongoDB es independiente de esquemas.

Page 10: Driver Nativo MongoDB

10Driver nativo MongoDB

Contando los Documentos de una Colección

Ahora que hemos insertado 101 documentos (los 100 del bucle, junto con el primero), podemos comprobar si los tenemos todos usando el método 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 método 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 colección. $id es el campo _id del documento (transformado a string) y $value es el documento en sí.

Ver También

La documentación API de MongoCollection::find() contiene más información sobre cómo localizar datos.

Estableciendo el Criterio de la Consulta

Podemos crear una consulta para pasar al método MongoCollection::find() y así obtener un subconjunto de documentos de nuestra colección. Por ejemplo, si quisiéramos encontrar el documento cuyo valor en el campo "i" es 71, haríamos lo siguiente:

<?php

$query = array( "i" => 71 );$cursor = $collection->find( $query );

while( $cursor->hasNext() ) { var_dump( $cursor->getNext() );}

?>

Page 11: Driver Nativo MongoDB

11Driver nativo MongoDB

y debería 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 colección. Por ejemplo, si quisiéramos obtener todos los documentos en los que "i" > 50, podríamos poner:

<?php

$query = array( "i" => array( '$gt' => 50 ) ); //fíjese en las comillas simples de '$gt'$cursor = $coll->find( $query );

while( $cursor->hasNext() ) { var_dump( $cursor->getNext() );}

?>

lo cual mostraría los documentos en que i > 50. Podemos también 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 símbolo $ o utilizar comillas simples. Si no, PHP lo interpretará como la variable $gt.

Creando un Índice

MongoDB soporta índices, y es muy fácil añadirlos a una colección. Para crear un Índice, debe indicar el nombre del campo y la dirección: ascendente (1) o descendente (-1). A continuación, creamos un índice ascendente en el campo "i":

<?php

Page 12: Driver Nativo MongoDB

12Driver nativo MongoDB

$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 indexación se vuelve crítica para un buen rendimiento de lectura. Si no está familiarizado con las indexaciones, revise la documentación de MongoCollection::ensureIndex() y l a » documentación de indexación de MongoDB.

Tabla de correlación de SQL a Mongo

Esta es una versión específica de PHP de la tabla de correlación de » SQL a Mongo de la documentación principal.

Sentencia SQL Sentencia en el Lenguaje de Consulta Mongo

CREATE TABLE USERS (a Number, b Number)

Implícito, o utilice MongoDB::createCollection().

INSERT INTO USERS VALUES(1,1) $db->users->insert(array("a" => 1, "b" => 1));

SELECT a,b FROM users $db->users->find(array(), array("a" => 1, "b" => 1));

SELECT * FROM users WHERE age=33 $db->users->find(array("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 ORDER BY name

$db->users->find(array("age" => 33), array("a" => 1, "b" => 1))->sort(array("name" => 1));

SELECT * FROM users WHERE age>33 $db->users->find(array("age" => array('$gt' => 33)));

SELECT * FROM users WHERE age<33 $db->users->find(array("age" => array('$lt' => 33)));

SELECT * FROM users WHERE name LIKE "%Joe%"

$db->users->find(array("name" => new MongoRegex("/Joe/")));

Page 13: Driver Nativo MongoDB

13Driver nativo MongoDB

SELECT * FROM users WHERE name LIKE "Joe%"

$db->users->find(array("name" => new MongoRegex("/^Joe/")));

SELECT * FROM users WHERE age>33 AND age<=40

$db->users->find(array("age" => array('$gt' => 33, '$lte' => 40)));

SELECT * FROM users ORDER BY name DESC

$db->users->find()->sort(array("name" => -1));

CREATE INDEX myindexname ON users(name)

$db->users->ensureIndex(array("name" => 1));

CREATE INDEX myindexname ON users(name,ts DESC)

$db->users->ensureIndex(array("name" => 1, "ts" => -1));

SELECT * FROM users WHERE a=1 and b='q'

$db->users->find(array("a" => 1, "b" => "q"));

SELECT * FROM users LIMIT 10 SKIP 20 $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 $db->users->find()->limit(1);

EXPLAIN SELECT * FROM users WHERE z=3

$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 $db->users->count();

SELECT COUNT(*y) FROM users where AGE > 30

$db->users->find(array("age" => array('$gt' => 30)))->count();

SELECT COUNT(AGE) from users $db->users->find(array("age" => array('$exists' => true)))->count();

UPDATE users SET a=1 WHERE b='q' $db->users->update(array("b" => "q"), array('$set' => array("a" => 1)));

UPDATE users SET a=a+2 WHERE b='q' $db->users->update(array("b" => "q"), array('$inc => array("a" => 2)));

DELETE FROM users WHERE z="abc" $db->users->remove(array("z" => "abc"));

Conexión

Page 14: Driver Nativo MongoDB

14Driver nativo MongoDB

La Conexión a MongoDB es tan fácil como usar new Mongo, pero hay muchas más opciones y configuraciones adicionales. La página Mongo::__construct() cubre todas las opciones del API, pero está página ofrece más detalles y consejos para casos de uso prácticos.

Acceso a la conexión

Si MongoDB se inicia con la opción --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 método: si la conexión a la base de datos se cae y luego se reconecta, la conexión ya no estará autentificada.

Si se utiliza la forma de conexión mediante cadena, como se describe en Mongo::__construct(), la base de datos se autentificará al conectarse y se autentificará de nuevo si la conexión se cae y se restablece.

Hace lo mismo que el código anterior, a excepción que las reconexiones a la base de datos serán automáticamente autentificadas:

<?php

$m = new Mongo("mongodb://${username}:${password}@localhost");

?>

Por omisión, 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 después del host. Este ejemplo iniciará la sesión al usuario en la base de datos "blog":

<?php

$m = new Mongo("mongodb://${username}:${password}@localhost/blog");

?>

Grupos replica

Para conectarse a un grupo réplica, se debe especificar uno o más miembros del grupo usando la opción replicaSet.

<?php

Page 15: Driver Nativo MongoDB

15Driver nativo MongoDB

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

?>

Se require la versión 1.0.9+ del driver para conectar a un grupo réplica (versiones anteriores del driver no auto-detectarán el master o no se reconectarán correctamente).

El driver de PHP hará una petición 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 conexión se establecerá con éxito. Si no se puede realizar una conexión a ninguno de los servidores listados o no puede encontrar el master, MongoConnectionException devolverá una excepción.

Si el master no se encuentra disponible, los slaves no promocionarán un nuevo master por algunos segundos. Durante ese tiempo, el controlador no podrá realizar ninguna operación en la base de datos (excepto las conexiones a los slaves que seguirán 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 excepción.

Una vez el master es elegido, al realizar una lectura o escritura el driver detectará cual es el nuevo master. Establecerá la conexión como como primaria y continuará operando normalmente.

Para obtener más información acerca de grupos replica, consulte la » documentación del núcleo.

Connexiones persistentes

Crear una nueva conexión cada vez a la base de datos es muy lento. Para minimizar el número de conexiones que se necesite, se pueden usar las conexiones persistentes. Una conexión persistente es guardada por PHP, para que pueda usarse la misma conexión en múltiples 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 apróximadamente 18 segundos en ejecutarse. Pero si lo cambiamos para que utilice una conexión persistente:

<?php

for ($i=0; $i<1000; $i++) { $m = new Mongo("localhost:27017", array("persist" => "x"));}

Page 16: Driver Nativo MongoDB

16Driver nativo MongoDB

?>

...tardará menos de 0.02 segundos en ejecutarse, ya que solo se realiza una sola conexión a la base de datos.

Las conexiones persistentes necesitan indicarse usando la variable de identificación (tal y como se muestra "x" en el ejemplo anterior). Para que la conexión persistente pueda usarse, el hostname, puerto, variable persist y el usuario y contraseña (si es necesario) debe coincidir con una conexión persistente ya existente. De lo contrario, se creará una nueva conexión los datos proporcionados.

Las conexiones persistentes son altamente recomendables y se deberían usar siempre en producción a no ser que exista una razón con fundamento para hacer lo contrario. La mayoría de razones por las cuales no son recomendadas para bases de datos relacionales son totalmente irrelevantes para MongoDB.

Las conexiones persistentes serán el tipo de conexión por omisión 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 versión 1.0.9 o superior del driver, se puede conectar a la base de datos vía fichero. MongoDB automáticamente abre un fichero socket al iniciarse: /tmp/mongodb-<port>.sock.

Para conectarse al fichero socket, especifique la ruta de la conexión MongoDB:

<?php

$m = new Mongo("mongodb:///tmp/mongo-27017.sock");

?>

Si se quiere utilizar autenticación en la conexión (tal y como se indica más arriba) usando un fichero socket, se debe especificar el puerto 0 para que el analizador de la cadena de conexión sepa donde acaba la cadena de conexión.

<?php

$m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");

?>

Escrituras

Operaciones Seguras

Por omisión, 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 rápido, pero no puede saberse si realmente han

Page 17: Driver Nativo MongoDB

17Driver nativo MongoDB

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 inválida (p.ej., escribir en una colección del sistema).

Para obtener una respuesta de la base de datos, utilice la opción safe, disponible en todos los tipos de escritura. Esta opción se asegura de que la base de datos realiza la escritura antes de notificar del éxito. Si la escritura falla, emitirá una excepción MongoCursorException(), explicando la razón 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 producción, pueden usarse escrituras no seguras sobre datos "no importantes". Los datos no importantes dependen de la aplicación, pero se suele tratar de datos automáticos (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 excepción, sabrá que hay un problema con la base de datos.

Hay más 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 omisión, MongoDB sincroniza en disco las escrituras una vez por minuto).

La forma más segura de realizar una escritura consiste en usar réplicas y en especificar el número de servidores en que se harán las escrituras antes de obtener el éxito. (En producción siempre deben usarse réplicas, revise la sección de Conexión para más información sobre conjuntos de réplicas.)

$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" : [

Page 18: Driver Nativo MongoDB

18Driver nativo MongoDB

{ "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, podríamos no conocer el índice del comentario que necesitamos modificar, sólo 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 réplicas y un driver versión 1.1.0 o superior, éste puede hacer que senvíen las consultas automáticamente a los esclavos. Este comportamiento no existe en las versiones anteriores del driver y no puede ser usado en un maestro-esclavo "normal".

Por omisión, el driver enviará todas las consultas al maestro. Si se habilita la opción "slaveOkay", el driver enviará todas las consultas a un servidor no primario, siempre y

Page 19: Driver Nativo MongoDB

19Driver nativo MongoDB

cuando fuera posible. La opción "slaveOkay" puede habilitarse a cualquier "nivel": conexión, base de datos, colección, y cursor. Cada clase hereda el ajuste "slaveOkay" de su clase superior, de modo que si hiciéramos:

<?php

$db->setSlaveOkay(true);$c = $db->myCollection;

$cursor = $c->find();

?>

la consulta se ejecutaría contra un esclavo (la colección hereda "slaveOkay" de la base de datos y el cursor lo hereda de la colección).

Cómo 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 tuviéramos un cliente PHP en Europa y otro en Australia y tuviéramos un secundario en cada uno de estos centros de datos, podríamos:

<?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: australianHostel 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 tardía 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 enviaría 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().

Page 20: Driver Nativo MongoDB

20Driver nativo MongoDB

Si disfruta tocando botones que probablemente no debería tocar, puede solicitar al driver un nuevo esclavo usando Mongo::switchSlave(). Esto escogería un nuevo esclavo (si hubiera alguno disponible), pero no debería 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 sólo lectura, también se envían siempre al primario.

La salud y estado de un esclavo se comprueba cada 5 secundos o al realizarse la siguiente operación antes de que venzan los 5 segundos. También se volverá a comprobar la configuración cuando el driver tenga problemas accediendo a algún servidor.

Tenga en cuenta que un servidor no primario podría encontrarse detrás 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 automáticamente un campo _id único, a menudo útil para usar en consultas.

Supongamos que queremos localizar el documento que acabamos de insertar. Las inserciones añaden 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 más 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 vacío. Por ejemplo:<?php

$person = array("name" => "joe");

$people->insert($person);

// convertimos el _id a texto$pid = $person['_id'] . "";

Page 21: Driver Nativo MongoDB

21Driver nativo MongoDB

// 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 combinación de claves y valores. Los arrays "normales" se definen como arrays con un índice numérico ascendente que comienza por 0 y se incrementa en uno por cada elemento. Estos son, normalmente, los arrays de PHP más comunes.

Por ejemplo, si se quisiera guardar una lista de premios en un documento, podríamos 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 más 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" }

Page 22: Driver Nativo MongoDB

22Driver nativo MongoDB

]}

Incluso aquí, ignorando que se trata de un array, podemos usar la misma notación 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, sólo por mantenerlo más legible).

Puede también usarse un array para consultar un determinado número de posibles valores. Por ejemplo, si buscáramos documentos "gold" o "copper", podríamos hacer:

<?php

$cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper"))));

?>

Actualizaciones

Las actualizaciones quizás sean las operaciones más complicadas de las disponibles en MongoDB. Combinan una consulta junto con una acción, modificando los documentos que concuerdan con los criterios de selección. Son también muy potentes, permitiendo cambiar rápidamente los documentos y reemplazarlos. Se realiza al momento (siempre y cuando sea posible), minimizando el consumo de recursos.

Modificación o reemplazo de documentos

Existen dos tipos de actualizaciones: actualizaciones de modificación y actualizaciones de reemplazado. Las actualizaciones de modificación 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 actualización de modificación puede añadir 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 sería así:* {"username" : "joe", "password" : "...", "email" : "...", "twitter" : "@joe4153"}*/

Page 23: Driver Nativo MongoDB

23Driver nativo MongoDB

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 términos de operandos $.

Por ejemplo, una actualización 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 quedaría 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"))));

?>

Page 24: Driver Nativo MongoDB

24Driver nativo MongoDB

El Operador Posicional

El operador posicional $es útil a la hora de actualizar objetos en arrays. En el ejemplo anterior, por ejemplo, podríamos no conocer el índice del comentario que necesitamos modificar, sólo 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 configuración de php.ini.

Opciones de configuración Mongo

Nombre Por defecto Cambiable

mongo.native_long false * PHP_INI_ALL

mongo.long_as_object false PHP_INI_ALL

mongo.default_host "localhost" PHP_INI_ALL

mongo.default_port 27017 PHP_INI_ALL

mongo.auto_reconnect true PHP_INI_SYSTEM

mongo.allow_persistent true PHP_INI_SYSTEM

mongo.chunk_size 262144 PHP_INI_SYSTEM

mongo.cmd "$" PHP_INI_ALL

mongo.utf8 "1" PHP_INI_ALL

mongo.allow_empty_keys false 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 explicación de las directivas de configuración.

Page 25: Driver Nativo MongoDB

25Driver nativo MongoDB

mongo.native-long intEste valor por omisión 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, sólo se podrán 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 también 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 podría provocar pérdida de precisión. 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 excepción MongoCursorException alertando de que no se puede evitar la pérdida de precisión en la lectura. Se recomienda que, en sistemas de 32 bits, además de esto se habilite mongo.long_as_object.

mongo.long_as_object stringDevuelve eun BSON_LONG como una instancia de MongoInt64 (en lugar de usar el tipo primitivo).

mongo.default_host stringNombre de host por omisión en caso de que no se especifique en el constructor.

mongo.default_port stringPuerto TCP por omisión al conectar al servidor de bases de datos en caso de que no se especifique ningún puerto. El puerto por omisión es 27017.

mongo.auto_reconnect boolIndica si se debe reconectar o no a la base de datos al perder la conexión.

mongo.allow_persistent boolIndica si se permiten o no conexiones persistentes.

mongo.chunk_size intNúmero de bytes por bloque. Se usa al fragmentar ficheros GridFS. Este valor debe ser al menos 100 veces menor que 4 megabytes (máx: 4194204) y se recomienda que sea incluso menor.

mongo.cmd stringCarácter que se utiliza en lugar de $ en los modificadores y comparaciones. En vista de que es fácil olvidar escapar el carácter "$", puede elegirse cualquier otro en su lugar. Escoja un carácter que no aparezca en sus nombres de clave, como por ejemplo ":":mongo.cmd = ":"Ahora, para hacer una comparación, sería:<?php

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

?>Puede cambiarse también en tiempo de ejecución usando ini_set("mongo.cmd", ":").

Page 26: Driver Nativo MongoDB

26Driver nativo MongoDB

Por supuesto, también pueden usarse comillas simples o la barra \ para escapar el carácter $.

mongo.utf8 intIndica si se debe lanzar una excepción con textos que no sean UTF8. Hasta la versión 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 opción, emulando el comportamiento anterior en que no se emitían excepciones. Sin embargo, esta opción será eliminada en la versión 1.1.0, de manera que siempre se emitirán excepciones en textos no UTF8.

mongo.allow_empty_keys intAñadido en la versión 1.0.11. Indica si se permiten un texto vacío ("") como nombre de claves. Por omisión, el driver emitirá una excepción al proporcionar un texto vacío como clave en la base de datos. Es muy fácil pasar esto por alto al usar comillas dobles con operandos $, por lo que se recomienda dejar el valor por omisión. Sin embargo, si fuera necesario almacenar claves vacías, puede asignarse true a esta opción, de manera que el driver permita usar un texto vacío a la base de datos.

Seguridad

Ataques de Inyección de Petición

Al pasar parámetros $_GET a una consulta, debemos asegurarnos de que se han convertido en strings. Un usuario puede insertar un array asociativo en una petición GET, provocando consultas $ no deseadas.

Un ejemplo aparentemente inofensivo: supongamos que estamos buscando información de un usuario con la petición http://www.example.com?username=bob. La aplicación realiza la consulta $collection->find(array("username" => $_GET['username'])).

Alguien podría alterarlo realizando una consulta a http://www.example.com?username[$ne]=foo, con lo que PHP lo convertirá automáticamente 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 parámetros $_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 interacción con una base de datos que localice documentos, incluyendo actualizaciones, busquedas con modificación, y eliminaciones.

Gracias a » Phil por apuntar esto.

Page 27: Driver Nativo MongoDB

27Driver nativo MongoDB

Para más información sobre ataques tipo inyección SQL con MongoDB revise » la documentación principal.

Ataques de Inyección de Código

Si se está usando JavaScript, debemos asegurarnos que cualquier variable que cruce los límites PHP-JavaScript se pasa en el campo scope de MongoCode, y no interpolado en el código JavaScript. Esto sucede al llamar a MongoDB::execute(), consultas $where, MapReduces, agrupaciones, y cualquier otra situación en que se proporcione código JavaScript a la base de datos.

Nota

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

Por ejemplo, supongamos que tenemos un código JavaScript para saludar a los usuarios en los registros de la base de datos. Podríamos:

<?php

// ¡no haga esto!

$username = $_POST['username'];$db->execute("print('Hola, $username!');");

?>

Pero, ¿qué ocurriría si un usuario malicioso metiera código JavaScript?

<?php

// ¡no haga esto!

// $username tiene como valor "'); db.users.drop(); print('"$db->execute("print('Hola, $username!');");

?>

Ahora MongoDB ejecuta el código JavaScript "print('Hola, '); db.users.drop(); print('!');". Este ataque es fácil 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 añade la variable user al ámbito de JavaScript. Si ahora alguien quisiera añadir código malicioso, MongoDB imprimiría, sin causar daños, Hello, '); db.dropDatabase(); print('!.

Page 28: Driver Nativo MongoDB

28Driver nativo MongoDB

El uso de scope ayuda a prevenir que se ejecutene en la base de datos entradas maliciosas. Sin embargo, debe asegurarse de que su código no cambie y ejecute los datos de entrada. Por ejemplo, nunca utilice la función 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 código los datos de entrada del usuario.

Solución a problemas

En caso de que tuviera problemas, existe un gran número de recursos que consultar.

• IRC El canal IRC oficial de MongoDB es irc.freenode.net/#mongodb. Éste es el método mas rápido 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 rápido) método para encontrar respuestas.

• Seguimiento de fallos ¿Ha encontrado un fallo? ¿Echa algo en falta? ¿Tiene alguna pregunta? Archívela en el » bug track del driver de PHP.

Puede habilitar la depuración verbosa compilando el driver con el flag de depuración.

$ ./configure CFLAGS=-DDEBUG

DEBUG habilita todas las depuraciones. Se pueden habilitar también flags de depuración específicos. En el último código fuente, los flags disponibles son:

• DEBUG_CONN Depuración de conexiones.

Ejecutando los Test del Driver

El paquete PECL no incluyen los test, pero están 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

Page 29: Driver Nativo MongoDB

29Driver nativo MongoDB

directorio tests/ ). También necesitará » PHPUnit para ejecutar los test. PHPUnit también se puede instalar mediante PEAR (hay un par de prerrequisitos que podrá consultar en las instrucciones de instalación).

Algunos test esperarán 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 obtendrán errores que indicaran que el test esperaba que se emitiera una alerta o error.

Para ejecutarlos, asegúrese de que el servidor de MongoDB se está ejecutando en local en el puerto 27017. Antes de notificar de un error, por favor, asegúrese de que ha ejecutado los test contra la última versión de desarrollo de MongoDB: a veces hay errores para funcionalidades que ya no se encuentran en la versión estable.

La suite de pruebas usa la base de datos "phpunite". En caso de que utilice en su aplicación una base de datos llamada "phpunit", asegúrese de indicar a MongoDB un nuevo directorio de datos antes de ejecutar los test.

Asegúrese de que se encuentra en el directorio principal del código 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 están expuertas a PHP. Si deseara ejecutar estos test, deberá compilar PHP con la bandera --enable-embed. Después, 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 dentrán 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 debería obtener ningún error de acceso no válido 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. Podría 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.

Page 30: Driver Nativo MongoDB

30Driver nativo MongoDB

Clases del núcleo

Las clases del núcleo son la parte más importante del controlador.

Page 31: Driver Nativo MongoDB

31Driver nativo MongoDB

La clase Mongo

Introducción

Conexión entre PHP y MongoDB.

Esta clase se utiliza para crear y administrar conexiones. Un uso típico es:<?php

$m = new Mongo(); // conectar$db = $m->foo; // obtener la base de datos con nombre "foo"

?>

Consulte Mongo::__construct() y la sección connecting para más información sobre cómo 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;

/* Métodos */

Page 32: Driver Nativo MongoDB

32Driver nativo MongoDB

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::VERSIONVersión del driver PHP. Puede estar precedida por "+" o "-" si se encuentra entre varias versiones.

Mongo::DEFAULT_HOST "localhost"Host de conexión en caso de que no se especifique ninguno.

Page 33: Driver Nativo MongoDB

33Driver nativo MongoDB

Mongo::DEFAULT_PORT 27017Puerto de conexión si no se especifica ningún otro.

Fields

statusSi se trata de una conexión persistente, si la conexión se ha creado para este objeto, o si está siendo reutilizada. Si no se trata de una conexión persistente, este campo debe estar a NULL.

Ver también

Documentación de MongoDB sobre » conexiones.

Page 34: Driver Nativo MongoDB

34Driver nativo MongoDB

Mongo::close

Mongo::close -- Cierra la conexión

Descripción

public bool Mongo::close ( void )

Salvo en circunstancias excepcionales, no es necesario invocar a este método. Cuando la instancia de Mongo quede fuera de ámbito, el driver cerrará la conexión con la base de datos automáticamente.

En caso de que los objetos no salgan de ámbito entre las peticiones, quizás se deee invocar a este método al final de la ejecución para eliminar todas las conexiones residuales. Sin embargo, es probable que sea más eficiente utilizar una conexión persistente, que creará automáticamente una conexión cuando sea necesaria y la utilizaría para tntas peticiones como fuera posible.

Si se está conectado a un conjunto de réplicas, close() sólo cerrará la conexión a la primaria.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Indica si la conexión se cerró o no con éxito.

Page 35: Driver Nativo MongoDB

35Driver nativo MongoDB

Mongo::connect

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

Descripción

public bool Mongo::connect ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Indica si la conexión tuvo éxito.

Errores/Excepciones

Lanza MongoConnectionException si falla la conexión a la base de datos.

Page 36: Driver Nativo MongoDB

36Driver nativo MongoDB

Mongo::connectUtil

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

Descripción

protected bool Mongo::connectUtil ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Indica si la conexión tuvo éxito.

Errores/Excepciones

Emite MongoConnectionException si falla la conexión a la base de datos.

Page 37: Driver Nativo MongoDB

37Driver nativo MongoDB

Mongo::__construct

Mongo::__construct -- Crear un nuevo objeto de conexión a base de datos

Descripción

Mongo::__construct ( [ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE ) ] ] )

Si no se pasa ningún parámetro, 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 conexión siempre comienza con mongodb://, para indicar que es una cadena de conexión de esta forma.

Si se especifica username y password, el constructor autenticará la conexión con la base de datos antes de devolver el control. Son parámetros opcionales, y si se especifican, deben estar seguidos por una @.

Al menos debe proporcionarse un host (el puerto es opcional, por omisión 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 excepción MongoConnectionException.

Finalmente, si se especificó usuario y contraseña, se puede especificar también la base de datos contra la que se autentica. Si db no se especifica, se utilizará "admin".

Parámetros

server

Nombre del servidor.

options

Array con las opciones de conexión. Las opciones disponibles actualmente son:

• "connect" Si el constructor debe o no conectar antes de devolver el control. Por omisión, TRUE.

• "timeout" Tiempo máximo que esperará el driver para conectar a la base de datos (en milisegundos).

• "replicaSet" Nombre del conjunto de réplicas 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 más detalles, revise el ejemplo de abajo sobre

Page 38: Driver Nativo MongoDB

38Driver nativo MongoDB

réplicas.

• "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 contraseña. Es útil en caso de que una contraseña incluya una "@". Esto reemplaza una contraseña 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 conexión a base de datos.

Errores/Excepciones

Emite MongoConnectionException si intentara conectar a la base de datos en todos hosts proporcionados, y fallara. También emitirá MongoConnnectionException si el nombre de usuario o contraseña fueran inválidos. Revise la documentación de MongoConnectionException para conocer las excepciones y sus causas.

Historial de cambios

Versión Descripción

1.2.0Eliminada la opción de persistencia, ya que ahora todas las conexiones lo son. Se puede seguir usando, pero no tendrá ningún efecto."persist"

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

Page 39: Driver Nativo MongoDB

39Driver nativo MongoDB

Ahora el parámetro "replicaSet" espera un strings, y no un booleano (aunque todavía se aceptaría un booleano).

1.0.2 Cambiado el constructor para que acepte un array de opciones. Antes de 1.0.2, el constructor tenía los siguientes parámetros:server

Nombre de servidor.

connect

Parámetro booleano opcional para especificar si el constructor debe o no conectar a la base de datos antes de devolver el control. Por omisión, TRUE.

persistent

Si la conexión debe o no ser persistente.

paired

Si la conexión debe vincularse.

1.0.9 Añadida la opción replicaSet.

1.2.0 Añadidas las opciones username y password.

Ejemplos

Ejemplo #1 - Ejemplo de conjunto de réplicas con Mongo::__construct()

Este ejemplo muestra cómo conectar el driver a un conjunto de réplicas. 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"));

// sólo 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"));

?>

Page 40: Driver Nativo MongoDB

40Driver nativo MongoDB

Si el maestro falla, el driver averiguará qué servidor secundario se convierte en el nuevo maestro y comenzará a usar automáticamente la conexión. La recuperación automática 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 réplicas.

Si se incluyen semillas de dos juegos de replicas separados, el comporamiento será inesperado.

Para más información, revise la » documentation sobre conjuntos de réplicas.

Ejemplo #2 - Conectando a un socket de dominio

En la versión 1.0.9 o superior, se puede usar un socket de dominio UNIX para conectar a una instancia de MongoDB local. Es ligeramente más rápido que una conexión de red.

En la versión 1.5.0, el servidor MongoDB abre automáticamente un socket en /tmp/mongodb-<port>.sock. Puede coenctarse a él especificando la ruta en la cadena de conexión:

<?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 conexión a localhost$m = new MongoDB("mongodb:///tmp/mongodb-27017.sock,localhost:27017");

?>

Ejemplo #3 - Ejemplo de autenticación 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 adminswitched to db admin> db.addUser("testUser", "testPass");{ "_id" : ObjectId("4b21272fd9ab21611d19095c"), "user" : "testUser", "pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"}

Page 41: Driver Nativo MongoDB

41Driver nativo MongoDB

>

Tras crear un usuario con, en este caso, el nombre "testUser" y la contraseña "testPass", puede crearse una conexión autenticada:

<?php

$m = new Mongo("mongodb://testUser:testPass@localhost");

?>

Page 42: Driver Nativo MongoDB

42Driver nativo MongoDB

Mongo::dropDB

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

Descripción

public array Mongo::dropDB ( mixed $db )

Advertencia

Deprecated

Use MongoDB::drop() instead.

Parámetros

db

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

Valores devueltos

Returns the database response.

Page 43: Driver Nativo MongoDB

43Driver nativo MongoDB

Mongo::__get

Mongo::__get -- Gets a database

Descripción

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;

?>

Parámetros

dbname

The database name.

Valores devueltos

Returns a new db object.

Errores/Excepciones

Throws a generic exception if the database name is invalid.

Page 44: Driver Nativo MongoDB

44Driver nativo MongoDB

Mongo::getHosts

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

Descripción

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.

Parámetros

Esta función no tiene parámetros.

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)

Page 45: Driver Nativo MongoDB

45Driver nativo MongoDB

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

Page 46: Driver Nativo MongoDB

46Driver nativo MongoDB

Mongo::getPoolSize

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

Descripción

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.

Parámetros

Esta función no tiene parámetros.

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 -1echo "pool size is: ".Mongo::getPoolSize()."\n";

echo "setting pool size to 200\n";

Mongo::setPoolSize(200);

// pool size is 200echo "pool size is: ".Mongo::getPoolSize()."\n";

$conn2 = new Mongo("host2");

// remaining for host1 is -2// remaining for host2 is 199var_dump(Mongo::poolDebug());

Page 47: Driver Nativo MongoDB

47Driver nativo MongoDB

?>

Ver también

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

Page 48: Driver Nativo MongoDB

48Driver nativo MongoDB

Mongo::getSlave

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

Descripción

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.

Parámetros

Esta función no tiene parámetros.

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.

Page 49: Driver Nativo MongoDB

49Driver nativo MongoDB

Mongo::getSlaveOkay

Mongo::getSlaveOkay -- Consultar el valor slaveOkay de esta conexión

Descripción

public bool Mongo::getSlaveOkay ( void )

Revise la sección de consultas de este manual para saber cómo distribuir lecturas a esclavos.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el valor de slaveOkay de esta instancia.

Page 50: Driver Nativo MongoDB

50Driver nativo MongoDB

Mongo::listDBs

Enumera todas las bases de datos disponibles

Descripción

public array Mongo::listDBs ( void )

Parámetros

Esta función no tiene parámetros.

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, tamaño y si está o no vacía. Los otros dos campos son totalSize (tamaño total en bytes) y ok, que será 1 cuando este método se ejecute con éxito.

Ejemplos

Ejemplo #1 - Ejemplo de Mongo::listDBs

Ejemplo que muestra cómo usar listDB y la estructura de datos devuelta.

<?php

$mongo = new Mongo();$dbs = $mongo->listDBs();print_r($dbs);

?>

El resultado del ejemplo sería algo similar a:

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

[totalSize] => 218103808 [ok] => 1)

Page 51: Driver Nativo MongoDB

51Driver nativo MongoDB

Mongo::poolDebug

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

Descripción

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.

Parámetros

Esta función no tiene parámetros.

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.

Page 52: Driver Nativo MongoDB

52Driver nativo MongoDB

Mongo::selectCollection()

Obtiene una colección de base datos

Descripción

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

Parámetros

db

Nombre de la base de datos.

collection

Nombre de la colección.

Valores devueltos

Devuelve un nuevo objeto de colección.

Errores/Excepciones

Emite InvalidArgumentException si el nombre de la base de datos o de la colección fuera inválido.

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 conexión?>

Page 53: Driver Nativo MongoDB

53Driver nativo MongoDB

Mongo::selectDB

Mongo::selectDB -- Obtener una base de datos

Descripción

public MongoDB Mongo::selectDB ( string $name )

Parámetros

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 válido.

Page 54: Driver Nativo MongoDB

54Driver nativo MongoDB

Mongo::setPoolSize

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

Descripción

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.

Parámetros

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 serverMongo::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();

Page 55: Driver Nativo MongoDB

55Driver nativo MongoDB

?>

El resultado del ejemplo sería algo similar a:

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

Ver también

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

Page 56: Driver Nativo MongoDB

56Driver nativo MongoDB

Mongo::setSlaveOkay

Mongo::setSlaveOkay -- Cambia el ajuste de slaveOkay de esta conexión

Descripción

public bool Mongo::setSlaveOkay ( [ bool $ok = true ] )

Revise la sección de consultas de este manual para conocer cómo distribuir lecturas entre esclavos.

Parámetros

ok

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

Valores devueltos

Devuelve el valor anterior de slaveOkay que tenía esta instancia.

Page 57: Driver Nativo MongoDB

57Driver nativo MongoDB

Mongo::switchSlave

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

Descripción

public string Mongo::switchSlave ( void )

Elije un esclavo aleatoriamente para crear una conexión de lectura. Se invoca automáticamente 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 sección de consultas de este manual para obtener más información sobre lescturas distribuidas en esclavos.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

La dirección del esclavo que está usando esta conexió para realizar lecturas. Podría ser la misma que la anterior, ya que se eligen aleatoriamente. Si sólo hubiera un secundario (o sólo el primario) únicamente se devolvería una dirección.

Por ejemplo, si tuviéramos un conjunto de réplicas de tres miembros, con un primario, secundario, y un árbitro, este método siempre devolvería la dirección del secundario. Si éste no estvuiera disponible, este método devolvería la dirección del primario. Si éste tampoco estuviera disponible, se emitiría una excepción, ya que un árbitro no puede realizar operaciones de lectura.

Errores/Excepciones

Si se le llama desde una conexión sin conjuntos de réplicas, emite MongoException (código de error 15). También emite MongoException si no pudiera encontrar ningún elemento (primario o secundario) del que leer (código de error 16).

Page 58: Driver Nativo MongoDB

58Driver nativo MongoDB

Mongo::__toString

Mongo::__toString -- Representación en forma de texto de esta conexión

Descripción

public string Mongo::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre de host y el puerto de esta conexión.

Page 59: Driver Nativo MongoDB

59Driver nativo MongoDB

Clase MongoDB

Introducción

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 prácticamente cualquier carácter del rango ASCII. Sin embargo no pueden contener ni " ", "." ni un texto vacío. El nombre "system" también está reservado.

Hay algunos nombres poco usuales de bases de datos que sí son válidos: "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;

/* Métodos */

Page 60: Driver Nativo MongoDB

60Driver nativo MongoDB

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

Page 61: Driver Nativo MongoDB

61Driver nativo MongoDB

Niveles de Logs de MongoDB

MongoDB::PROFILING_OFF 0Profiling deshabilitado.

MongoDB::PROFILING_SLOW 1Profiling habilitado para operaciones lentas (>100 ms).

MongoDB::PROFILING_ON 2Profiling habilitado para todas las operaciones.

Campos

w 1Número 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 sólo 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 operación "segura" ( MongoCollection::insert(), MongoCollection::update(), MongoCollection::remove(), MongoCollection::save(), y MongoCollection::ensureIndex() soportan la opción segura). Con el valor por omisión (1), una operación segura devolverá el control cuando el servidor de bases de datos obtenga la operación. Si el servidor se cayera antes de que la operación se replicara a un esclavo, podría perderse la operación 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 operación antes de que se considere que ha habido éxito. Por ejemplo, si w fuera 2, tanto el servidor principal como un esclavo tendrán un registro de la operación. Si no, el driver emitirá una excepción MongoCursorException. Puede ser tentador establecer en w el total de esclavos + maestro, pero entonces, si un esclavo se cayera, la operación fallaría y se emitiría una excepción, por lo que suele ser más seguro establecer w=2 (maestro + 1 esclavo).

wtimeout 10000Número de milisegundos a esperar a que las réplicas de MongoDB::$w tengan lugar. Se hereda por las instancias de MongoCollection que deriven de este objeto. w sólo 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 omisión el driver esperará 10 segundos. Puede modificarse este valor para alterar este comportamiento.

Ver también

Documentación de MongoDB de » bases de datos.

Page 62: Driver Nativo MongoDB

62Driver nativo MongoDB

MongoDB::authenticate

MongoDB::authenticate -- Iniciar sesión en esta base de datos

Descripción

public array MongoDB::authenticate ( string $username, string $password )

Este método hace que esta conexión sea autenticada. Si el servidor de bases de datos tiene la autenticación habilitada (de forma predeterminada, no lo está), deberá iniciar sesión antes de poder hacer cualquier cosa.

En general, deberá se recomienda utilizar la autenticación que incorpora Mongo::__construct() antes que este método. Si se autentica sobre la conexión, y la conexión se cae y se reconecta durante la sesión, automáticamente será re-autenticado. Si se autentica manualmente usando este método, y la conexión se cae, deberá llamar a este método de nuevo cuando la conexión vuelva.

Este método 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 conexión ha sido autenticada, sólo puede ser des-autenticada mediante el comando de base de datos "logout":<?php

$db->command(array("logout" => 1));

?>

Parámetros

username

Nombre de usuario.

Page 63: Driver Nativo MongoDB

63Driver nativo MongoDB

password

La contraseña (en texto plano).

Valores devueltos

Devuelve la respuesta de la base de datos. Si el inicio de sesión tuvo éxito, devolverá:<?phparray("ok" => 1);?>Si algo fue mal, devolverá:<?phparray("ok" => 0, "errmsg" => "auth fails");?>("auth fails" puede ser otro mensaje, dependiendo de la versión de la base de datos y de qué fuera mal).

Ver también

Documentación de MongoDB sobre » autenticación.

Page 64: Driver Nativo MongoDB

64Driver nativo MongoDB

MongoDB::command

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

Descripción

public array MongoDB::command ( array $command )

Prácticamente todo lo que no son operaciones CRUD se puede realizar con un comando de base de datos. ¿Necesita conocer la versión de la base de datos? Hay un comando para ello. ¿Necesita hacer una agregación? Hay un comando para ello. ¿Necesia habilitar registros de mensajes? Se puede hacer una idea.

Este método es equivalente a:<?php

public function command($data) { return $this->selectCollection('$cmd')->findOne($data);}

?>

Parámetros

command

Consulta que se enviará.

Historial de cambios

Versión Descripción

1.2.0 Añadido el parámetro options con una única opción: timeout.

Valores devueltos

Devuelve la respuesta de la base de datos.

Ejemplos

Page 65: Driver Nativo MongoDB

65Driver nativo MongoDB

Ejemplo #1 - Ejemplo de MongoDB::command() con "distinct"

Localizando todos los valores distintos de una clave.

<?php

$gente = $db->gente;

$gente->insert(array("nombre" => "Joe", "edad" => 4));$gente->insert(array("nombre" => "Sally", "edad" => 22));$gente->insert(array("nombre" => "Dave", "edad" => 22));$gente->insert(array("nombre" => "Molly", "edad" => 87));

$edades = $db->command(array("distinct" => "gente", "key" => "edad"));

foreach ($edades['values'] as $edad) { echo "$edad\n";}

?>

El resultado del ejemplo sería algo similar a:

42287

Ejemplo #2 - Ejemplo de MongoDB::command() con MapReduce

Obtener todos los usuarios con al menos un evento "sale" (venta), y cuántas 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));

// construcción del mapa y función 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,

Page 66: Driver Nativo MongoDB

66Driver nativo MongoDB

"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 sería 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 también 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 añairlas al ámbito global usando el campo opcional de ámbito con el comando de la base de datos. Consulte la » documentación de MapReduce para más información.

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 escribían a una colección temporal, que se eliminaba cuando se cerrara la conexión. A partir de la versión 1.8.0, el argumento out es obligatorio. Consulte la » documentación de MapReduce para más información.

Si va a usar MapReduce, Prajwal Tuldhar ha creado una API para usuarios de Mongo PHP que ofrece una interfaz más elegante que el comando 'al desnudo'. Puede descarlo desde » Github y hay un » artículo de blog sobre cómo usarlo.

Ver también

Documentación de MongoDB sobre » comandos de base de datos y comando individuales: » findAndModify, » getLastError, y » repair (existen muchos más, éstos son sólo unos pocos ejemplos).

Page 67: Driver Nativo MongoDB

67Driver nativo MongoDB

MongoDB::__construct

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

Descripción

MongoDB::__construct ( Mongo $conn, string $name )

Este método 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 párrafo 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');

?>

Parámetros

Mongo connConexión a la base de datos.

name

Nombre de la base de datos.

Valores devueltos

Devuelve la base de datos.

Errores/Excepciones

Page 68: Driver Nativo MongoDB

68Driver nativo MongoDB

Lanza una excepción por defecto si el nombre no fuera válido.

Page 69: Driver Nativo MongoDB

69Driver nativo MongoDB

MongoDB::createCollection

MongoDB::createCollection -- Crea una colección

Descripción

public MongoCollection MongoDB::createCollection ( string $name [, bool $capped = FALSE [, int $size = 0 [, int $max = 0 ] ] ] )

Este método se usa para crear colecciones "capped" (de tamaño fijo) y otras colecciones que requieren opciones especiales. Es idéntico a ejecutar:<?php

$collection = $db->command(array("create" => $name, "size" => $size, "capped" => $capped, "max" => $max));

?>Consulte MongoDB::command() para más información sobre comandos de base de datos.

Parámetros

name

Nombre de la colección.

capped

Si la colección debe ser o no de tamaño fijo.

size

Si la colección fuera de tamaño fijo, aquí indicamos su tamaño en bytes.

max

Si la colección fuera de tamaño fijo, aquí establecemos el número máximo de elementos que podrá almacenar.

Valores devueltos

Devuelve un objeto de colección que representa la nueva colección.

Ejemplos

Ejemplo #1 - Ejemplo de MongoDB::createCollection() para colección de tamaño fijo

Una colección "capped" es un tipo especial de colección que tiene un tamaño fijo o un número fijo de elementos. Una vez que la colección está "llena", los elementos más viejos se eliminan cada vez que añadimos nuevos. Estas colecciones pueden ser muy

Page 70: Driver Nativo MongoDB

70Driver nativo MongoDB

útiles para usos como registro de mensajes, donde quizás se desee mantener una determinada cantidad de espacio para mensajes sin preocuparse por si crece demasiado.

Este ejemplo crea una colección de mensajes de error muy pequeña, 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 sería algo similar a:

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

Page 71: Driver Nativo MongoDB

71Driver nativo MongoDB

MongoDB::createDBRef

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

Descripción

public array MongoDB::createDBRef ( string $collection, mixed $a )

Este método es una interfaz flexible que permite crear referencias a bases de datos (vea MongoDBRef ).

Parámetros

collection

Colección 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 cómo 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 sería algo similar a:

Page 72: Driver Nativo MongoDB

72Driver nativo MongoDB

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 más adelante con MongoDB::getDBRef o con MongoCollection::getDBRef.

Ejemplo #2 - Ejemplo de MongoDB::createDBRef()

Ejemplo que muestra cómo crear una referencia a base de datos a partir de un id.

<?php

$id = new MongoId('47cc67093475061e3d9536d2');$ref = $db->createDBRef('articulos', $id);?>

Page 73: Driver Nativo MongoDB

73Driver nativo MongoDB

MongoDB::drop

MongoDB::drop -- Borra esta base de datos

Descripción

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));}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la respuesta de la base de datos.

Ejemplos

Ejemplo #1 - Ejemplo de MongoDB::drop()

Este ejemplo muestra cómo borrar una base de datos mongo.

<?php

$db = $mongo->foo;$response = $db->drop();print_r($response);

?>

El resultado del ejemplo sería algo similar a:

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

Page 74: Driver Nativo MongoDB

74Driver nativo MongoDB

MongoDB::dropCollection

MongoDB::dropCollection -- Borra una colección [obsoleto]

Descripción

public array MongoDB::dropCollection ( mixed $coll )

Advertencia

Obsoleto

Utilice en su lugar MongoCollection::drop().

¡Esta función tiene fugas de memoria en versiones 1.0.7 y anteriores!

Parámetros

coll

MongoCollection o nombre de la colección a borrar.

Valores devueltos

Devuelve la respuesta de la base de datos.

Page 75: Driver Nativo MongoDB

75Driver nativo MongoDB

MongoDB::execute

MongoDB::execute -- Ejecuta código JavaScript en el servidor de bases de datos

Descripción

public array MongoDB::execute ( mixed $code [, array $args = array() ] )

El servidor de bases de datos de Mongo contiene un motor JavaScript. Este método permite ejecutar cualquier código 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. Asegúrese de que tiene esto en consideración antes de ejecutar scripts costosos.

Este método es una envoltura de un comando de base de datos. Básicamente, sería:<?php

public function execute($code, $args) { return $this->command(array('$eval' => $code, args => $args));}

?>

Si se tuviera una única sentencia en una única línea, MongoDB devuelve un valor. Esto puede provocar comportamientos inesperados. Por ejemplo, el siguiente código devuelvo "foo":

<?php

$db->execute('"foo";');

?>

Sin embargo, este código devuelve NULL:

<?php

$db->execute('"bar"; "foo";'); // más de una sentencia

$db->execute('db.foo.count();'); // más de una línea

?>

Para evitar estos comportamientos, lo mejor es no dejar que MongoDB decida qué devolver, usando en su lugar una sentencia "return" explícita. Podríamos cambiar los ejemplos superiores por lo siguiente:

<?php

Page 76: Driver Nativo MongoDB

76Driver nativo MongoDB

$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 colección "foo".

Parámetros

code

MongoCode o texto a ejecutar.

args

Argumentos que se deben pasar a code.

Valores devueltos

Devuelve el resultado de la evaluación.

Ejemplos

Ejemplo #1 - Ejemplo sencillo de MongoDB::execute()

<?php

$response = $db->execute("function() { return 'Hola, mundo!'; }");echo $response['retval'];

?>

El resultado del ejemplo sería algo similar a:

Hola, mundo!

Ejemplo #2 - Ejemplo de parámetros en MongoDB::execute()

Pasaremos a la función JavaScript valores del array del parámetro opcional.

<?php

$response = $db->execute("function(despedida, nombre) { return despedida+', '+nombre+'!'; }", array("Hasta pronto", "Juan"));echo $response['retval'];

Page 77: Driver Nativo MongoDB

77Driver nativo MongoDB

?>

El resultado del ejemplo sería algo similar a:

Hasta pronto, Juan!

Ejemplo #3 - Ejemplo de ámbito

Si en lugar de un string, usáramos un MongoCode en el primer parámetro, 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 sería algo similar a:

Hasta pronto, Juan, dice Fran

Page 78: Driver Nativo MongoDB

78Driver nativo MongoDB

MongoDB::forceError()

Crea un error de base de datos

Descripción

public bool MongoDB::forceError ( void )

Este método 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 genérico después de ejecutar este comando.

Este comando es idéntico a la ejecución de:<?php

public function forceError() { return $this->command(array('forceerror' => 1));}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la respuesta de base de datos.

Page 79: Driver Nativo MongoDB

79Driver nativo MongoDB

MongoDB::__get

MongoDB::__get -- Obtiene una colección

Descripción

public MongoCollection MongoDB::__get ( string $name )

Ésta es la forma más fácil de obtener uan colección a partir de un objeto de base de datos. Si el nombre de la colección contiene caracteres extraños, se usará en su lugar MongoDB::selectCollection().<?php

$mongo = new Mongo();

// las dos siguientes líneas son equivalentes$collection = $mongo->selectDB("foo")->selectCollection("bar");$collection = $mongo->foo->bar;

?>

Parámetros

name

Nombre de la colección.

Valores devueltos

Devuelve la colección.

Page 80: Driver Nativo MongoDB

80Driver nativo MongoDB

MongoDB::getDBRef

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

Descripción

public array MongoDB::getDBRef ( array $ref )

Parámetros

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 cómo obtener una referencia a una base de datos y cuáles son los datos de entrada esperados.

<?php

$ref = array( '$ref' => 'profiles', '$id' => '47cc67093475061e3d9536d2');

$profile = $db->getDBRef($ref);?>

Revise MongoDB::createDBRef() para más información sobre cómo crear referencias a bases de datos.

Page 81: Driver Nativo MongoDB

81Driver nativo MongoDB

MongoDB::getGridFS

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

Descripción

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

Parámetros

prefix

Prefijo de la colección 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 cómo obtener una instancia de MongoGridFS.

<?php

$db = $mongo->my_db;

$prefix = 'files';$collection = $db->getGridFS($prefix);

?>

Lea más sobre MongoGridFS para aprender cómo almacenar ficheros con MongoDB.

Page 82: Driver Nativo MongoDB

82Driver nativo MongoDB

MongoDB::getProfilingLevel

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

Descripción

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 ejecución de consultas. Si se habilita (digamos, usando MongoDB::setProfilingLevel() o por consola), puede consultar cuánta consultas tardan más que un determinado número 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 función es equivalente a:<?php

public function getProfilingLevel() { return $this->command(array('profile' => -1));}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nivel de perfilado.

Ver también

Documentación de MongoDB sobre » profiling y MongoDB::setProfilingLevel().

Page 83: Driver Nativo MongoDB

83Driver nativo MongoDB

MongoDB::getSlaveOkay

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

Descripción

public bool MongoDB::getSlaveOkay ( void )

Revise la sección de consultas de este manual para más información sobre distribución de lecturas a esclavos.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el valor de slaveOkay para esta instancia.

Page 84: Driver Nativo MongoDB

84Driver nativo MongoDB

MongoDB::lastError

MongoDB::lastError -- Comprueba si hubo un error en la última operación de base de datos llevada a cabo

Descripción

public array MongoDB::lastError ( void )

Este método es equivalente a:<?php

public function lastError() { return $this->command(array('getlasterror' => 1));}

?>

Parámetros

Esta función no tiene parámetros.

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 sería algo similar a:

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

Page 85: Driver Nativo MongoDB

85Driver nativo MongoDB

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 sería algo similar a:

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

Page 86: Driver Nativo MongoDB

86Driver nativo MongoDB

MongoDB::listCollections

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

Descripción

public array MongoDB::listCollections ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve una lista de MongoCollections.

Ejemplos

Ejemplo #1 - Ejemplo de MongoDB::listCollections()

El siguiente ejemplo muestra cómo 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 sería algo similar a:

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

Page 87: Driver Nativo MongoDB

87Driver nativo MongoDB

MongoDB::prevError

MongoDB::prevError -- Comprueba el último error emitido durante una operación de base de datos

Descripción

public array MongoDB::prevError ( void )

En general, se recomienda utilizar MongoDB::lastError() en lugar de este método. Este método devuelve el último error de base de datos que tuvo lugar, y hace cuántas operaciones sucedió. Ha quedado prácticamente obsoleto.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el error y hace cuántas operaciones sucedió.

Page 88: Driver Nativo MongoDB

88Driver nativo MongoDB

MongoDB::repair

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

Descripción

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 vacíos que encuentre. Esta operación es muy lenta en bases de datos extensas.

Generalmente se ejecuta desde la consola o desde la línea de comandos, y no por el driver.

Es equivalente a la función:<?php

public function repair() { return $this->command(array('repairDatabase' => 1));}

?>

Parámetros

preserve_cloned_files

Indica si los ficheros clonados deben mantenerse cuando la reparación 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 también

Documentación de MongoDB sobre » reparación.

Ejemplos

Page 89: Driver Nativo MongoDB

89Driver nativo MongoDB

Ejemplo #1 - Ejemplo de MongoDB::repair()

Este ejemplo muestra cómo reparar y compactar una base de datos.

<?php

$db = $mongo->foo;

$response = $db->repair();print_r($response);

?>

El resultado del ejemplo sería algo similar a:

Array( [ok] => 1)

Page 90: Driver Nativo MongoDB

90Driver nativo MongoDB

MongoDB::resetError

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

Descripción

public array MongoDB::resetError ( void )

Generalmente, este método 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));}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la respuesta de la base de datos.

Page 91: Driver Nativo MongoDB

91Driver nativo MongoDB

MongoDB::selectCollection

MongoDB::selectCollection -- Obtiene una colección

Descripción

public MongoCollection MongoDB::selectCollection ( string $name )

Parámetros

name

Nombre de la colección.

Valores devueltos

Devuelve la colección.

Page 92: Driver Nativo MongoDB

92Driver nativo MongoDB

MongoDB::setProfilingLevel

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

Descripción

public int MongoDB::setProfilingLevel ( int $level )

Modifica el nivel actual de profiling de la base de datos.

Esta función es equivalente a:<?php

public function setProfilingLevel($level) { return $this->command(array('profile' => $level));}

?>

Las opciones de niveles son 0 (deshabilitado), 1 (consultas de más de 100ms), y 2 (todas las consultas). Si se deseara perfilar tan sólo las consultas que llevan más que otro periodo de tiempo, utilice el comando de base de datos con un segundo parámetro: el número de milisegundos. Por ejemplo, para perfil todas las consultas que llevan más de on segundo, ejecute:<?php

$result = $this->command(array('profile' => 1, 'slowms' => 1000));

?>

Las consultas perfiladas aparecerán en la colección system.profile de esta base de datos.

Parámetros

level

Nivel de perfilado.

Valores devueltos

Devuelve el valor anterior del nivel de perfilado.

Page 93: Driver Nativo MongoDB

93Driver nativo MongoDB

MongoDB::setSlaveOkay

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

Descripción

public bool MongoDB::setSlaveOkay ( [ bool $ok = true ] )

Revise la sección de consultas de este manual para más información sobre distribución de lecturas a esclavos.

Parámetros

ok

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

Valores devueltos

Devuelve el valor anterior de slaveOkay de esta instancia.

Page 94: Driver Nativo MongoDB

94Driver nativo MongoDB

MongoDB::__toString

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

Descripción

public string MongoDB::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre de esta base de datos.

Page 95: Driver Nativo MongoDB

95Driver nativo MongoDB

Clase MongoCollection

Introducción

Representa una colección de base de datos.

Los nombres de colecciones pueden usar cualquier carácter del código ASCII. Algunos ejemplos de nombres válidos de colecciones son "", "...", "mi coleccion", y "*&#@".

Los nombres de colecciones definidos por usuario no pueden contener el símbolo $. Existen colecciones del sistema que utilizan $ en sus nombres (p.ej., local.oplog.$main), pero es un carácter reservado. Si se intentara crear y usar una colección 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;

/* Métodos */

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 ] ] ] )

Page 96: Driver Nativo MongoDB

96Driver nativo MongoDB

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 1Sentido ascendente en ordenaciones y creaciones de índices.

Page 97: Driver Nativo MongoDB

97Driver nativo MongoDB

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

Campos

dbLa base de datos "padre" de esta colección.

wNúmero 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 más detallada cómo funciona w.

wtimeoutNúmero de milisegundos a esperar a que las operaciones se realicen en las $this->w réplicas. Este valor se hereda de la base de datos padre. La clase MongoDB indica de forma más detallada cómo funciona wtimeout.

Ver también

Documentación principal de MongoDB sobre » collections.

Page 98: Driver Nativo MongoDB

98Driver nativo MongoDB

MongoCollection::batchInsert

MongoCollection::batchInsert -- Inerta múltiples documentos en esta colección

Descripción

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

Parámetros

a

Array de arrays.

options

Opciones de inserción.

• "safe" Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución 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 inserción no tenga éxito, emitirá una excepción de tipo MongoCursorException. Si safe fuera un entero, replicará la inserción a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espra; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

• "fsync" Booleano, por omisión FALSE. Obliga a que la inserción se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una inserción 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 operación por lotes se envió con éxito, o FALSE en caso contrario.

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" estuviera habilitada y la inserción fallara.

Lanza MongoCursorTimeoutException si la opción "safe" tuviera un valor mayor que uno, y la base de datos no pudiera replicar la operación en MongoCollection::$wtimeout milisegundos.

Historial de cambios

Page 99: Driver Nativo MongoDB

99Driver nativo MongoDB

Versión Descripción

1.0.5 Añadido el parámetro "options".

1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".

Ejemplos

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

Las inserciones por lotes son una forma rápida de añadir 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 sería algo similar a:

4bf43ac68ead0e19710000004bf43ac68ead0e19710100004bf43ac68ead0e1971020000...string(5) "user1"string(5) "user2"string(5) "user3"...

Page 100: Driver Nativo MongoDB

100Driver nativo MongoDB

MongoCollection::__construct

MongoCollection::__construct -- Crea una nueva colección

Descripción

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

Parámetros

MongoDB dbBase de datos padre.

name

Nombre de esta colección.

Valores devueltos

Devuelve un nuevo objeto de tipo colección.

Errores/Excepciones

Si el nombre no fuera válido, emite una excepción por defecto.

Page 101: Driver Nativo MongoDB

101Driver nativo MongoDB

MongoCollection::count

MongoCollection::count -- Cuenta el número de documentos de esta colección

Descripción

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

Parámetros

query

Array asociativo u objeto con los campos que deben coincidir.

limit

Especifica una cota superior del número devuelto.

skip

Especifica el número de resultados a partir del cual se ignorarán.

Valores devueltos

Devuelve el número de documentos que coinciden con la consulta.

Historial de cambios

Versión Descripción

1.0.7 Añadidos los parámetros 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)));

Page 102: Driver Nativo MongoDB

102Driver nativo MongoDB

?>

El resultado del ejemplo sería algo similar a:

int(3)int(1)

Page 103: Driver Nativo MongoDB

103Driver nativo MongoDB

MongoCollection::createDBRef

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

Descripción

public array MongoCollection::createDBRef ( array $a )

Parámetros

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 canción$manamana = $songs->findOne(array('titulo' => 'Ma na ma na'));$refACancioin = $songs->createDBRef($manamana);

// añade la referencia a mi lista de reproducción$listasDeReproduccion->update(array('usuario' => 'yo'), array('$push' => array('listadecanciones' => $refToSong)));

?>

Ver también

• MongoCollection::getDBRef

Page 104: Driver Nativo MongoDB

104Driver nativo MongoDB

MongoCollection::deleteIndex

MongoCollection::deleteIndex -- Elimina un índice de esta colección

Descripción

public array MongoCollection::deleteIndex ( string|array $keys )

Este método es identico a:

<?php

public function deleteIndexes($keys) { // toIndexString es un método '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 opción "name" de MongoCollection::ensureIndex() ) o generado por el driver a partir de una combinación de nombres de clave y de direcciones. Usaremos después este nombre con MongoCollection::deleteIndex() para eliminar el índice.

Desafortunadamente, el método 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 reazón, 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 haríamos así:

<?php

$db->command(array("deleteIndexes" => $collection->getName(), "index" => "superfast query");

?>

Para averiguar cómo se llama un índice, puede consultar colección system.indexes de una base de datos y analizar el campo name (nombre).

Parámetros

keys

Page 105: Driver Nativo MongoDB

105Driver nativo MongoDB

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 cómo pasar tanto un stringo como un array a la función.

<?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));?>

Page 106: Driver Nativo MongoDB

106Driver nativo MongoDB

MongoCollection::deleteIndexes

MongoCollection::deleteIndexes -- Elimina todos los índices de esta colección

Descripción

public array MongoCollection::deleteIndexes ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la respuesta de la base de datos.

Ejemplos

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

Este ejemplo demuestra cómo eliminar todos los índices de una colección, y muestra también la respuesta esperada.

<?php

$collection = $mongo->my_db->articles;$response = $collection->deleteIndexes();print_r($response);

?>

El resultado del ejemplo sería algo similar a:

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

Page 107: Driver Nativo MongoDB

107Driver nativo MongoDB

MongoCollection::drop

MongoCollection::drop -- Borra esta colección

Descripción

public array MongoCollection::drop ( void )

Borra esta colección y elimina sus índices.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la respuesta de la base de datos.

Ejemplos

Ejemplo #1 - MongoCollection::drop() example

Este ejemplo demuestra cómo borrar una colección, y muestra también la respuesta esperada.

<?php

$collection = $mongo->my_db->articles;$response = $collection->drop();print_r($response);

?>

El resultado del ejemplo sería algo similar a:

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

Page 108: Driver Nativo MongoDB

108Driver nativo MongoDB

MongoCollection::ensureIndex

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

Descripción

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 sería NULL y, por tanto, no sería único.

Parámetros

keys

Campo o campos a usar como índice.

options

Este parámetro 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 versión 1.3.2 o superior, se podrán crear índices de fondo mientras se realiza otras operaciones. Por omisión, la creación de índices sucede de forma síncrona. Si se especifica TRUE en esta opción, la creación de índices será asíncrona.

• "safe" Desde la versión 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 creación del índice, el driver emitiría una excepción de tipo MongoCursorException. Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará.

• "name" Desde la versión 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 omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto tiempo (en milisegundos) esperará el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo

Page 109: Driver Nativo MongoDB

109Driver nativo MongoDB

de tiempo, se lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Devuelve TRUE.

Historial de cambios

Versión Descripción

1.2.0 Añadida la opción timeout.

1.0.11 "safe" emitirá fallos del maestro, cuando proceda.

1.0.11 Se lanza MongoException si el nombre de índice (generado o asignado) es superior a 128 bytes.

1.0.2 Cambiado el parámetro "options" de booleano a array. Antes de 1.0.2, el segundo parámetro era un valor booleano opcional que especificaba un índice único.

Errores/Excepciones

Lanza MongoException si el nombre de índice es superior a 128 bytes. (Versión 1.0.11+)

Lanza MongoCursorException si la opción "safe" está habilitada y falla la creación del índice.

Lanza MongoCursorTimeoutException si la opción "safe" está habilitada y la operación lleva más de MongoCursor::$timeout milisegundos para ser completada. Esto no paraliza la operación en el servidor, es sólo un límite 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

Page 110: Driver Nativo MongoDB

110Driver nativo MongoDB

$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 creación 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 colección*/$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) fallarán*/$collection->insert(array("username" => "joeschmoe"));

?>

Ejemplo #3 - Indexación Geoespacial

Mongo soporta índices geoespaciales, que permiten buscar documentos cercanos a una determinada localización o que estén dentro de una determinada forma. Por ejemplo, para crear un índice geoespacial en el campo "loc":

<?php

$collection->ensureIndex(array("loc" => "2d"));

?>

Ver también

Page 111: Driver Nativo MongoDB

111Driver nativo MongoDB

Documentación de MongoDB sobre » Ã­ndices por defecto y sobre » Ã­ndices geoespaciales.

Page 112: Driver Nativo MongoDB

112Driver nativo MongoDB

MongoCollection::find

MongoCollection::find -- Realiza una consulta a la colección

Descripción

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

Parámetros

query

Campos en los que buscar.

fields

Campos del resultado que se devolverán.

Valores devueltos

Devuelve un cursor para el resultado de la búsqueda.

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 más información sobre cómo trabajar con cursores.

Ejemplo #2 - Ejemplo de MongoCollection::find() usando $where

Este ejemplo demuestra cómo buscar en una colección usando código javascript para reducir el conjunto de resultados.

<?php

Page 113: Driver Nativo MongoDB

113Driver nativo MongoDB

$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 cómo buscar una colección 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 más cómoda usando arrays. Para convertir un cursor en un array, utilice la función 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 tamaño máximo de memoria!

Además, 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 también

Documentación de MongoDB sobre » find.

Page 114: Driver Nativo MongoDB

114Driver nativo MongoDB

MongoCollection::findOne

MongoCollection::findOne -- Realiza una consulta a esta colección, devolviendo sólo un elemento

Descripción

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

Parámetros

query

Campos a los que consultar.

fields

Campos del resultado que devolver.

Valores devueltos

Devuelve el registro que coincide con la búsqueda, o NULL.

Errores/Excepciones

Si no se pudiera acceder a la base de datos, lanzaría una excepción de tipo MongoConnectionException.

Ejemplos

Ejemplo #1 - Ejemplo de MongoCollection::findOne buscando por id.

Este ejemplo muestra cómo buscar un documento en una colección a partir de su id.

<?php

$articulos = $mongo->mi_bd->articulos;

$articulo = $articulos->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2')));

?>

Page 115: Driver Nativo MongoDB

115Driver nativo MongoDB

Ejemplo #2 - Ejemplo de MongoCollection::findOne a partir de una condición.

Este ejemplo muestra como buscar un documento en una colección a partir de una condición, 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 sería algo similar a:

Array( [_id] => MongoId Object ( )

[password] => test)

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

Page 116: Driver Nativo MongoDB

116Driver nativo MongoDB

MongoCollection::__get

MongoCollection::__get -- Obtiene una colección

Descripción

public MongoCollection MongoCollection::__get ( string $name )

Forma concisa de obtener una colección con un nombre separado por el carácter punto. Si el nombre de colección contuviera caracteres extraños, se debería 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;

?>

Parámetros

name

Siguiente string en el nombre de la colección.

Valores devueltos

Devuelve la colección.

Page 117: Driver Nativo MongoDB

117Driver nativo MongoDB

MongoCollection::getDBRef

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

Descripción

public array MongoCollection::getDBRef ( array $ref )

Parámetros

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 canción de la lista de reproducciónforeach ($miLista['listacancion'] as $refCancion) { $cancion = $listasdereproduccion->getDBRef($refCancion); echo $cancion['titulo'] . "\n";}

?>

El resultado del ejemplo sería algo similar a:

Dazed and ConfusedMa na ma naBohemian Rhapsody

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

Page 118: Driver Nativo MongoDB

118Driver nativo MongoDB

Ver también

• MongoCollection::createDBRef

Page 119: Driver Nativo MongoDB

119Driver nativo MongoDB

MongoCollection::getIndexInfo

MongoCollection::getIndexInfo -- Devuelve un array con los nombres de índices de esta colección

Descripción

public array MongoCollection::getIndexInfo ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve una lista de nombres de índices.

Page 120: Driver Nativo MongoDB

120Driver nativo MongoDB

MongoCollection::getName

MongoCollection::getName -- Devuelve el nombre de esta colección

Descripción

public string MongoCollection::getName ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre de esta colección.

Ejemplos

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

<?php

$m = new Mongo();$c = $m->foo->bar->baz;

echo "Trabajando con la colección " . $c->getName() . ".\n";

// El espacio de nombres completo viene dado por el método MongoCollection::__toString()echo "Trabajando en el espacio de nombres $c.\n";

?>

El resultado del ejemplo sería algo similar a:

Trabajando con la colección bar.baz.Trabajando en el espacio de nombres foo.bar.baz.

Page 121: Driver Nativo MongoDB

121Driver nativo MongoDB

MongoCollection::getSlaveOkay

MongoCollection::getSlaveOkay -- Consulta el valor de slaveOkay de esta colección

Descripción

public bool MongoCollection::getSlaveOkay ( void )

Revise la sección de consultas de este manual para más información sobre distribución de lecturas a esclavos.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el valor de slaveOkay para esta instancia.

Page 122: Driver Nativo MongoDB

122Driver nativo MongoDB

MongoCollection::group

MongoCollection::group -- Lleva a cabo una operación similar al comando GROUP BY de SQL

Descripción

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

Parámetros

keys

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

initial

Valor inicial del objeto contador combinado.

reduce

Una función que toma dos argumentos (el documento actual y la agregación en este punto) y realiza la agregación.

options

Parámetros opcionales para el comando group. Las opciones válidas incluyen:

• "condition" Condición para incluir un documento a la agregación.

• "finalize" Función que se invoca por cada clave única que toma la salida de la función reduce.

Valores devueltos

Devuelve un array que contiene el resultado.

Ejemplos

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

Agrupa los documentos por categoría y crea una lista de los nombres que hay dentro de la categoría.

<?php

Page 123: Driver Nativo MongoDB

123Driver nativo MongoDB

$collection->insert(array("categoria" => "fruta", "nombre" => "manzana"));$collection->insert(array("categoria" => "fruta", "nombre" => "melocoton"));$collection->insert(array("categoria" => "fruta", "nombre" => "platano"));$collection->insert(array("categoria" => "verdura", "nombre" => "maiz"));$collection->insert(array("categoria" => "verdura", "nombre" => "brocoli"));

$keys = array("categoria" => 1);

$initial = array("items" => array());

$reduce = "function (obj, prev) { prev.items.push(obj.nombre); }";

$g = $collection->group($keys, $initial, $reduce);

echo json_encode($g['retval']);

?>

El resultado del ejemplo sería 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. Además, usa una condición: sólo los documentos que la cumplan, serán procesados por la función de agrupación.

<?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);

// función JavaScript a realizar$reduce = "function (obj, prev) { prev.count++; }";

// usar sólo 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 sería algo similar a:

Page 124: Driver Nativo MongoDB

124Driver nativo MongoDB

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

Ejemplo #3 - Pasando una función a keys

Si se desea agrupar por algo distinto a un nombre de campo, se puede pasar una función como primer parámetro de MongoCollection::group() y se ejecutará con cada documento. Se usará el valor devuelto de la función como valor de agrupación.

Este ejemplo demuestra cómo agrupar por el campo num módulo 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++; }'));

?>

Page 125: Driver Nativo MongoDB

125Driver nativo MongoDB

MongoCollection::insert

MongoCollection::insert -- Inserta un array en la colección

Descripción

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

Todas las cadenas de texto que se envíen a la base de datos deben estar en UTF-8. Si un string no estuviera en UTF-8, se lanzaría una excepción MongoException. Para insertar (o para consultar) un texto que no sea UTF-8, utilice MongoBinData.

Parámetros

a

Un array.

options

Opciones de inserción.

• "safe" Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución 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 inserción no tenga éxito, emitirá una excepción de tipo MongoCursorException. Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará. Si safe fuera un entero, replicará la inserción a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

• "fsync" Booleano, por omisión FALSE. Obliga a que la inserción se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una inserción segura (safe) y sobrescribirá el ajuste safe a FALSE.

• "timeout" Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto 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 lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Page 126: Driver Nativo MongoDB

126Driver nativo MongoDB

Si safe está habilitado, devuelve un array con el estado de la inserción. En cualquier otro caso, devuelve un booleano indicando si el array no estaba vacío (un array vacío no se insertará).

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" estuviera habilitada y fallara la inserción. (Versión 1.0.1+)

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y la operación llevara más de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción

1.0.5 Cambiado el segundo parámetro a un array de opciones. Antes de 1.0.5, el segundo parámetro era un booleano indicando la opción "safe".

1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".

1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.

1.2.0 Añadida la opción "timeout".

Ejemplos

Ejemplo #1 - Ejemplo de MongoCollection::insert() con _id

Al insertar un objeto se le añadirá 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);

Page 127: Driver Nativo MongoDB

127Driver nativo MongoDB

?>

El resultado del ejemplo sería 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 cómo al insertar dos elementos con el mismo _id, se provoca que se lance una excepción 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 excepcióntry { $colecction->insert($persona, true);}catch(MongoCursorException $e) { echo "No se puede guardar dos veces la misma persona!\n";}

?>

Ver también

Documentación de MongoDB sobre » insert.

Page 128: Driver Nativo MongoDB

128Driver nativo MongoDB

MongoCollection::remove

MongoCollection::remove -- Eliminar registros de esta colección

Descripción

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

Parámetros

criteria

Descripción de los registros que se eliminarán.

options

Opciones de eliminación.

• "justOne" Eliminar solamente uno de los registros que cumplan las condiciones.

• "safe" Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución 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 eliminación no tuviera éxito. Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará. Si safe fuera un entero, replicará la eliminación a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

• "fsync" Booleano, por omisión FALSE. Obliga a que la eliminación se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una eliminación segura (safe) y sobrescribirá el ajuste safe a FALSE.

• "timeout" Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto 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 lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Si "safe" está habilitado, devuelve un array asociativo con el estado de la eliminación ("ok"), el número de elementos eliminados ("n"), y cualquier error que pudiera haber

Page 129: Driver Nativo MongoDB

129Driver nativo MongoDB

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

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" está habilitada y la eliminación falla.

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y la operación llevara más de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción

1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".

1.0.5 Cambiado el segundo parámetro a un array de opciones. Antes de 1.0.5, el segundo parámetro era un booleano indicando la opción "justOne" y no había opción "safe".

1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.

1.2.0 Añadida la opción "timeout".

Ejemplos

Ejemplo #1 - Ejemplo de MongoCollection::remove() con justOne

<?php

$radioactivo = $db->radioactivo;

// contar cuánto plution queda$restante = $radioactivo->count(array('type' => 94));

$vidamedia = $restante/2;

// eliminar la mitadwhile ($vidamedia > 0) { $radioactivo->remove(array('type' => 94), array("justOne" => true)); $vidamedia--;}

Page 130: Driver Nativo MongoDB

130Driver nativo MongoDB

?>

Ver también

Documentación de MongoDB sobre » remove.

Page 131: Driver Nativo MongoDB

131Driver nativo MongoDB

MongoCollection::save

MongoCollection::save -- Guarda un objeto en esta colección

Descripción

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

Si el objeto fuera de la base de datos, se actualizaría. En caso contrario, se insertaría.

Parámetros

a

Array a guardar.

options

Opciones de guardado.

• "safe" Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución 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 inserción no tuviera éxito. Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará. Si safe fuera un entero, replicará la inserción a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

• "fsync" Booleano, por omisión FALSE. Obliga a que la inserción se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una inserción segura (safe) y sobrescribirá el ajuste safe a FALSE.

• "timeout" Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto 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 lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Si safe estuviera habilitado, devolvería un array que contiene el estado de la escritura. En cualquier otro caso, devuelve un booleano que representa si el array no estaba vacío (un

Page 132: Driver Nativo MongoDB

132Driver nativo MongoDB

array vacío no se insertará).

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" está habilitada y fallara al guardar.

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y a la operación llevara más de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción

1.0.5 Añadido el parámetro "options".

1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".

1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.

1.2.0 Añadida la opción "timeout".

Ejemplos

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

<?php

$obj = array('x' => 1);

// insertar $obj en la base de datos$collection->save($obj);

// añadir otro campo$obj['foo'] = 'bar';

// $obj no puede insertarse de nuevo; provoca un error de _id duplicado$collection->insert($obj);

// la función save actualiza $obj con el nuevo campo$collection->save($obj);

?>

Page 133: Driver Nativo MongoDB

133Driver nativo MongoDB

MongoCollection::setSlaveOkay

MongoCollection::setSlaveOkay -- Cambia el valor de slaveOkay de esta colección

Descripción

public bool MongoCollection::setSlaveOkay ( [ bool $ok = true ] )

Revise la sección de consultas de este manual para más información sobre distribución de lecturas a esclavos.

Parámetros

ok

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

Valores devueltos

Devuelve el valor anterior de slaveOkay de esta instancia.

Page 134: Driver Nativo MongoDB

134Driver nativo MongoDB

MongoCollection::__toString

MongoCollection::__toString -- Representación en forma de string de esta colección

Descripción

public string MongoCollection::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre completo de esta colección.

Ejemplos

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

<?php

$m = new Mongo();

$c1 = $m->foo->bar->baz;echo "Trabajando con la colección $c1.";

$c2 = $m->selectCollection('[]', '&');echo "Trabajando con la colección $c2.";

?>

El resultado del ejemplo sería algo similar a:

Trabajando con la colección foo.bar.baz.Trabajando con la colección [].&.

Page 135: Driver Nativo MongoDB

135Driver nativo MongoDB

MongoCollection::update

MongoCollection::update -- Actualizar registros basándose en los criterios proporcionados

Descripción

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

Parámetros

criteria

Descripción de los objetos a actualizar.

newobj

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

options

Este parámetro es un array asociativo de la forma array("optionname" => <boolean>, ...). Las opciones soportadas actualmente son:

• "upsert" Si ningún documento cumplira las condiciones de $criteria, se crearía un nuevo documento a partir de $criteria y $newobj (revise más abajo el ejemplo de upsert).

• "multiple" Todos los documentos que cumplan las condiciones de $criteria se actualizarán. MongoCollection::update() tiene exactamente el comportamiento contrario que MongoCollection::remove(): de forma predeterminada, actualiza sólo un documento, no todos los que cumplan las condiciones. Se recomienda especificar siempre se si deben actualizar múltiples documentos o un único documento, ya que el comportamiento predeterminado de la base de datos podría cambiar en el futuro.

• "safe" Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución 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 inserción no tuviera éxito. Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará. Si safe fuera un entero, replicará la actualización a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

• "fsync" Booleano, por omisión FALSE. Obliga a que la actualización se sincronice

Page 136: Driver Nativo MongoDB

136Driver nativo MongoDB

en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una actuaización segura (safe) y sobrescribirá el ajuste safe a FALSE.

• "timeout" Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto 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 lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Devuelve un booleano indicando si la actualización se envió o no con éxito a la base de datos.

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" estuviera habilitada y la actualización fallara.

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y a la operación llevara más de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción

1.0.1 Cambiado el parámetro "opciones" de un booleano a un array. Antes de 1.0.1, el segundo parámetro era un booleano opcional cuyo valor indicaba si era o no upsert.

1.0.5 Añadida la opción "safe".

1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".

1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.

1.2.0 Añadida la opción "timeout".

Ejemplos

Page 137: Driver Nativo MongoDB

137Driver nativo MongoDB

Ejemplo #1 - MongoCollection::update()

Añadiendo el campo dirección 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 sería 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 código, ya que con una sóla línea 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 sería algo similar a:

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

Si newobj no contuviera operadores $, upsert podría crear a partir de él un nuevo

Page 138: Driver Nativo MongoDB

138Driver nativo MongoDB

documento. Esto coincide con el comportamiento normal de una actualización: si no se usaran operadores $, se sobrescribiría todo el documento.

<?php

$c->update(array("nombre" => "juan"), array("usuario" => "juan12", "fechaAlta" => new MongoDate()), array("upsert" => true));

?>

El resultado del ejemplo sería algo similar a:

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

Ejemplo #3 - Ejemplo de múltiples MongoCollection::update()

De forma predeterminada, MongoCollection::update() sólo actualizará el primer documento que encuentre que cumpla las condiciones de $criteria. Si fuera necesario, mediante la opción "multiple" podremos sobrescribir este comportamiento.

Este ejemplo añade un campo "regalo" a cada persona cuyo cumpleaños sea el próximo día.

<?php

$hoy = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));$gente->update(array("cumpleaños" => $hoy), array('$set' => array('regalo' => $surprise)), array("multiple" => true));

?>

Ver también

La documentación de PHP sobre actualizaciones y la » documentacion en MongoDB.

Page 139: Driver Nativo MongoDB

139Driver nativo MongoDB

MongoCollection::validate

MongoCollection::validate -- Valida esta colección

Descripción

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

Parámetros

scan_data

Sólo valida los índices, no la colección base.

Valores devueltos

Devuelve la evaluación de la base de datos de este objeto.

Page 140: Driver Nativo MongoDB

140Driver nativo MongoDB

Clase MongoCursor

Introducción

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 podría:<?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).

Supóngase que, en el ejemplo superior, $collection fuera una colección de 50GB. No quisiéramos tener que alojar en memoria todo de una vez, y esto es lo que solucionan los cursores: permiten al cliente acceder a la colección gota a gota.

Si tuviéramos un resultado extenso, podríamos 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 colección, cargando y eliminando de memoria cada documento según se necesite.

Debe tenerse en cuenta que esto significa que un cursor no "contiene" el resultado de la base de datos, sino que sólo lo gestiona. Por tanto, si se imprimiera un cursor (con, digamos, var_dump() o print_r() ), sólo se obtendría el propio objeto cursor, sin los documentos. Para obtener los documentos en sí, debe utilizarse alguno de los métodos 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 límites, saltos, ordenaciones y más opciones avanzadas.

Page 141: Driver Nativo MongoDB

141Driver nativo MongoDB

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);

// todavía no se ha consultado la base de datos, de modo que se pueden añadir más opciones$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());// ya se ha consultado la base de datos, y no se pueden añadir más opciones

// por lo que esto lanzaría una excepción:$cursor->skip(4);?>

Clases sinopsis

MongoCursor

implements Iterator {

/* Campos Estáticos */

static boolean slaveOkay = FALSE;

static integer timeout = 20000;

/* Métodos */

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 )

Page 142: Driver Nativo MongoDB

142Driver nativo MongoDB

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 Estáticas

MongoCursor::slaveOkaySi la consulta debe o no tener asignada la bandera "slaveOkay", la cual permite leer en un esclavo (por omisión, los esclavos son para hacer copias de seguridad). Puede sobrescribirse con MongoCursor::slaveOkay().

MongoCursor::timeoutEstablecer el tiempo de espera en milisegundos para las respuestas de todas las

Page 143: Driver Nativo MongoDB

143Driver nativo MongoDB

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

Ver también

Documentación de MongoDB sobre » cursores.

Page 144: Driver Nativo MongoDB

144Driver nativo MongoDB

MongoCursor::addOption

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

Descripción

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.

Parámetros

key

Fieldname to add.

value

Value to add.

Valores devueltos

Returns this cursor.

Page 145: Driver Nativo MongoDB

145Driver nativo MongoDB

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));

?>

Page 146: Driver Nativo MongoDB

146Driver nativo MongoDB

MongoCursor::batchSize

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

Descripción

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

?>

Parámetros

num

The number of results to return in the next batch.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Page 147: Driver Nativo MongoDB

147Driver nativo MongoDB

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.

Page 148: Driver Nativo MongoDB

148Driver nativo MongoDB

MongoCursor::__construct

MongoCursor::__construct -- Create a new cursor

Descripción

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

Parámetros

connection

Database connection.

ns

Full name of database and collection.

query

Database query.

fields

Fields to return.

Valores devueltos

Returns the new cursor.

Page 149: Driver Nativo MongoDB

149Driver nativo MongoDB

MongoCursor::count

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

Descripción

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.

Parámetros

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 sería algo similar a:

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

Page 150: Driver Nativo MongoDB

150Driver nativo MongoDB

Errores/Excepciones

Throws MongoConnectionException if it cannot reach the database.

Page 151: Driver Nativo MongoDB

151Driver nativo MongoDB

MongoCursor::current

MongoCursor::current -- Returns the current element

Descripción

public array MongoCursor::current ( void )

This returns NULL until MongoCursor::next() is called.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

The current result as an associative array.

Page 152: Driver Nativo MongoDB

152Driver nativo MongoDB

MongoCursor::dead

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

Descripción

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.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

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

Page 153: Driver Nativo MongoDB

153Driver nativo MongoDB

MongoCursor::doQuery

MongoCursor::doQuery -- Execute the query.

Descripción

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).

Parámetros

Esta función no tiene parámetros.

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();

Page 154: Driver Nativo MongoDB

154Driver nativo MongoDB

} }}

?>

Page 155: Driver Nativo MongoDB

155Driver nativo MongoDB

MongoCursor::explain

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

Descripción

public array MongoCursor::explain ( void )

Parámetros

Esta función no tiene parámetros.

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 sería 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"]=>

Page 156: Driver Nativo MongoDB

156Driver nativo MongoDB

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 también

MongoDB core docs on » explain.

Page 157: Driver Nativo MongoDB

157Driver nativo MongoDB

MongoCursor::fields

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

Descripción

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));

?>

Parámetros

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.

Page 158: Driver Nativo MongoDB

158Driver nativo MongoDB

MongoCursor::getNext

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

Descripción

public array MongoCursor::getNext ( void )

This is identical to the function:

<?php

public function getNext() { $this->next(); return $this->current();}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns the next object.

Errores/Excepciones

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

Page 159: Driver Nativo MongoDB

159Driver nativo MongoDB

MongoCursor::hasNext

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

Descripción

public bool MongoCursor::hasNext ( void )

Parámetros

Esta función no tiene parámetros.

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.

Page 160: Driver Nativo MongoDB

160Driver nativo MongoDB

MongoCursor::hint

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

Descripción

public MongoCursor MongoCursor::hint ( array $key_pattern )

Parámetros

key_pattern

Indexes to use for the query.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Throws MongoCursorException if this cursor has started iterating.

Page 161: Driver Nativo MongoDB

161Driver nativo MongoDB

MongoCursor::immortal

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

Descripción

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.

Parámetros

liveForever

If the cursor should be immortal.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Throws MongoCursorException if this cursor has started iterating.

Page 162: Driver Nativo MongoDB

162Driver nativo MongoDB

MongoCursor::info

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

Descripción

public array MongoCursor::info ( void )

This can be called before or after the query.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

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

Historial de cambios

Versión Descripción

1.0.10 Added started_iterating field, a boolean indicating if cursor is pre- or post-query.

1.1.0 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() ).

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());

?>

Page 163: Driver Nativo MongoDB

163Driver nativo MongoDB

El resultado del ejemplo sería 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) }}

Page 164: Driver Nativo MongoDB

164Driver nativo MongoDB

MongoCursor::key

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

Descripción

public string MongoCursor::key ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

The current result's _id as a string.

Page 165: Driver Nativo MongoDB

165Driver nativo MongoDB

MongoCursor::limit

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

Descripción

public MongoCursor MongoCursor::limit ( int $num )

Parámetros

num

The number of results to return.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Throws MongoCursorException if this cursor has started iterating.

Ver también

MongoDB core docs on » limit.

Page 166: Driver Nativo MongoDB

166Driver nativo MongoDB

MongoCursor::next

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

Descripción

public void MongoCursor::next ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

NULL.

Errores/Excepciones

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

Page 167: Driver Nativo MongoDB

167Driver nativo MongoDB

MongoCursor::partial

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

Descripción

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.

Parámetros

okay

If receiving partial results is okay.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Throws MongoCursorException if this cursor has started iterating.

Page 168: Driver Nativo MongoDB

168Driver nativo MongoDB

MongoCursor::reset

MongoCursor::reset -- Clears the cursor

Descripción

public void MongoCursor::reset ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

NULL.

Page 169: Driver Nativo MongoDB

169Driver nativo MongoDB

MongoCursor::rewind

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

Descripción

public void MongoCursor::rewind ( void )

This is identical to the function:

<?php

public function rewind() { $this->reset(); $this->next();}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

NULL.

Errores/Excepciones

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

Page 170: Driver Nativo MongoDB

170Driver nativo MongoDB

MongoCursor::skip

MongoCursor::skip -- Skips a number of results

Descripción

public MongoCursor MongoCursor::skip ( int $num )

Parámetros

num

The number of results to skip.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Throws MongoCursorException if this cursor has started iterating.

Page 171: Driver Nativo MongoDB

171Driver nativo MongoDB

MongoCursor::slaveOkay

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

Descripción

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().

Parámetros

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

Page 172: Driver Nativo MongoDB

172Driver nativo MongoDB

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);

?>

Page 173: Driver Nativo MongoDB

173Driver nativo MongoDB

MongoCursor::snapshot

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

Descripción

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.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Returns this cursor.

Errores/Excepciones

Throws MongoCursorException if this cursor has started iterating.

Page 174: Driver Nativo MongoDB

174Driver nativo MongoDB

MongoCursor::sort

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

Descripción

public MongoCursor MongoCursor::sort ( array $fields )

Parámetros

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));?>

Page 175: Driver Nativo MongoDB

175Driver nativo MongoDB

MongoCursor::tailable

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

Descripción

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().

Parámetros

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()) {

Page 176: Driver Nativo MongoDB

176Driver nativo MongoDB

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

?>

Page 177: Driver Nativo MongoDB

177Driver nativo MongoDB

MongoCursor::timeout

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

Descripción

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.

Parámetros

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

Page 178: Driver Nativo MongoDB

178Driver nativo MongoDB

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.

Page 179: Driver Nativo MongoDB

179Driver nativo MongoDB

MongoCursor::valid

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

Descripción

public bool MongoCursor::valid ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

If the current result is not null.

Page 180: Driver Nativo MongoDB

180Driver nativo MongoDB

Tipos

MongoDB permite a los programadores guardar y consultar datos expresados tanto en los tipos básicos 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.

Números

En MongoDB los números son distintos de los strings: "123" no es lo mismo que 123. Por tanto, si se desea asegurar de que los números se ordenan y comparan correctamente, debe asegurarse de que realmente se almacenan como números.

<?php

$doc = array("a" => 123, "b" => "123");$collection->insert($doc);

$doc->find(array("a" => 123)); // coincide$doc->find(array("a" => "123")); // no coincide$doc->find(array("a" => 123.0)); // coincide$doc->find(array("b" => 123)); // no coincide$doc->find(array("b" => "123")); // coincide

?>

Como vemos, los números en coma flotante se comparan y coinciden con los números enteros tal como cabría esperar.

Números Largos

Por omisión, en sistemas de 32 bits, los números se envían a la base de datos como enteros de 32 bit. En sistemas 64 bits, se envían como enteros de 64 bit. Para guardar la compatibilidad, todos los sistemas deserializan los enteros de 64 bit como números en coma flotante. Los números en coma flotante no son exactos. Si fuera necesario usar valores exactos, habría 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 devolverán como objetos MongoInt64. El entero se almacenará en el campo value con una precisión perfecta (como un string). MongoInt64 puede usarse también para guardar enteros de 64 bit en máquinas de 32 bits.

Page 181: Driver Nativo MongoDB

181Driver nativo MongoDB

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 máquinas 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 omisión (para prevenir futuros cambios de estos valores).

Vea también: » 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 imágenes, 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 interactúe con los entresijos de réplicas o sharding, se deberá usar MongoDate, y no MongoTimestamp.

Ids Únicos

El driver creará automáticamente 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 máquina Dos registros no pueden tener el mismo id si se han insertado en máquinas diferentes.

Page 182: Driver Nativo MongoDB

182Driver nativo MongoDB

• 2 bytes de id de hebra Dos registros no pueden tener el mismo id si se han insertado por diferentes hebras en la misma máquina.

• 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 máquina trate de insertar 256^3 (más 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 código JavaScript en las consultas (usando la claúsula $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 código no requiera de valores externos, se puede o bien usar MongoCode o símplemente un string. Revise la » sección de seguridad para más información sobre cómo enviar código JavaScript a la base de datos.

Arrays y Objetos

También pueden guardarse arrays y objetos en la base de datos. Los arrays con clave numérica incremental se almacenarán como arrays. En cualquier otro caso, se almacenarán 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 también objetos PHP arbitrarios (pese a que se devolverán como arrays asociativos). Los campos se usan para pares clave/valor. Por ejemplo, la entrada de un blog podría ser así:<?php

Page 183: Driver Nativo MongoDB

183Driver nativo MongoDB

// clase de la entrada de un blog class Entrada {

var $autor; var $contenido; var $comentarios = array(); var $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 restricción 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 más para el título$entrada2->establecerTitulo("Segunda Entrada");

$blog->insert($entrada2);

?>

En la consola de la base de datos, lo veríamos 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 cíclicas en arrays ni en objetos. Por ejemplo, esto emitiría un error fatal:<?php

$collection->insert($GLOBALS);

?>

Fatal error: Nesting level too deep - recursive dependency?

Page 184: Driver Nativo MongoDB

184Driver nativo MongoDB

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

Page 185: Driver Nativo MongoDB

185Driver nativo MongoDB

Clase MongoId

Introducción

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 añadirá con una instancia de MongoId. Si los datos tuvieran un campo único natural (como p.ej., un nombre de usuario o una fecha) no habría problema en usarlo como _id, y en este caso no se reemplazaría por un MongoId.

Las instancias de MongoId cumplen la función 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 rápidamente cuál será el siguiente número. Esta clase establece las limitaciones necesarias para generar rápidamente 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 máquina del cliente, los dos siguiente son los bytes menos significativos del id del proceso en ejecución 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;

/* Métodos */

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

public static string MongoId::getHostname ( void )

public int MongoId::getInc ( void )

Page 186: Driver Nativo MongoDB

186Driver nativo MongoDB

public int MongoId::getPID ( void )

public int MongoId::getTimestamp ( void )

public static MongoId MongoId::__set_state ( array $props )

public string MongoId::__toString ( void )}

Campos

$idEste campo contiene la respresentación string de este objeto.

Ver también

Documentación de MongoDB sobre » ids.

Page 187: Driver Nativo MongoDB

187Driver nativo MongoDB

MongoId::__construct

MongoId::__construct -- Crea un nuevo id

Descripción

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

Parámetros

id

Texto a usar como identificador. Debe estar formado por 24 caracteres hexadecimales. Si se pasara un valor inválido a este constructor, lo ignoraría y crearía un nuevo valor para id.

Valores devueltos

Devuelve un nuevo id.

Ejemplos

Ejemplo #1 - MongoId::__construct() example

Este ejemplo muestra cómo crear un nuevo id. Rara vez neceasrio usar esto, ya que el driver añade automáticamente 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 sería algo similar a:

49a7011a05c677b9a916612a49a702d5450046d3d515d10d

Ejemplo #2 - Ejemplo con parámetros

Este ejemplo muestra cómo usar el parámetro para inicializar un MongoId con el valor

Page 188: Driver Nativo MongoDB

188Driver nativo MongoDB

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 sería algo similar a:

bool(true)

Ver también

• MongoId::__toString

Page 189: Driver Nativo MongoDB

189Driver nativo MongoDB

MongoId::getHostname

MongoId::getHostname -- Obtiene el nombre de host que se usa para el id de esta máquina

Descripción

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 idéntico a esta función:

<?php

public static function getHostname() { return gethostname();}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre de host.

Page 190: Driver Nativo MongoDB

190Driver nativo MongoDB

MongoId::getInc

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

Descripción

public int MongoId::getInc ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el valor incremental usado para crear este MongoId.

Page 191: Driver Nativo MongoDB

191Driver nativo MongoDB

MongoId::getPID

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

Descripción

public int MongoId::getPID ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el PID usado para crear este MongoId.

Page 192: Driver Nativo MongoDB

192Driver nativo MongoDB

MongoId::getTimestamp

MongoId::getTimestamp -- Devuelve el número de segundos desde la fecha de referencia con el que se creó este id

Descripción

public int MongoId::getTimestamp ( void )

Devuelve lo mismo que cuando se ejecuta time() al crear el id.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el número de segundos desde la fecha de referencias con el que se creó este id. Tan sólo hay cuatro bytes para almacenar el timestamp, por lo que MongoDate es una opción mejor si se desea almacenar fechas exacta de alto alcance.

Page 193: Driver Nativo MongoDB

193Driver nativo MongoDB

MongoId::__set_state

MongoId::__set_state -- Crea un MongoId vacío

Descripción

public static MongoId MongoId::__set_state ( array $props )

Esta función sólo se usa internamente por PHP, por lo que no debería necesitar ser nunca invocada por el usuario.

Es idéntica a esta función:

<?php

public static function __set_state($props) { return new MongoId("000000000000000000000000");}

?>

Parámetros

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 parámetro no se usa.

Valores devueltos

Un nuevo id con el valor "000000000000000000000000".

Page 194: Driver Nativo MongoDB

194Driver nativo MongoDB

MongoId::__toString

MongoId::__toString -- Devuelve la representación hexadecimal de este id

Descripción

public string MongoId::__toString ( void )

Parámetros

Esta función no tiene parámetros.

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 sería algo similar a:

49a7011a05c677b9a916612a49a702d5450046d3d515d10d

Page 195: Driver Nativo MongoDB

195Driver nativo MongoDB

Clase MongoCode

Introducción

Representa código JavaScript para la base de datos.

Los objetos MongoCode se componen de dos partes: el texto del código y un ámbito opcional. El texto del código debe ser JavaScript válido. El ámbito es un array asociativo de pares nombre/valor.

Clases sinopsis

MongoCode

MongoCode {

/* Métodos */

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

public string MongoCode::__toString ( void )}

Page 196: Driver Nativo MongoDB

196Driver nativo MongoDB

MongoCode::__construct

MongoCode::__construct -- Crea un nuevo objeto de código

Descripción

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

Parámetros

code

Texto del código.

scope

Ámbito que se usará para este código.

Valores devueltos

Devuelve un nuevo objeto de código.

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 sería 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; }"}

Page 197: Driver Nativo MongoDB

197Driver nativo MongoDB

Ejemplo #2 - Usando MongoCode() con $where

Este ejemplo consulta la colección de elementos cuyos campos 'x' valgan menos que $y. Tenga en cuenta que se pasan objetos PHP al ámbito de JavaScript y que la función JavaScript devuelve un booleano.

<?php

$cursor = $collection->find(array('$where' => new MongoCode('function() { return this.x < y; }', array('y'=>$y))));

?>

Page 198: Driver Nativo MongoDB

198Driver nativo MongoDB

MongoCode::__toString

MongoCode::__toString -- Devuelve este código en forma de texto

Descripción

public string MongoCode::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Este código. 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 sería algo similar a:

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

Page 199: Driver Nativo MongoDB

199Driver nativo MongoDB

Clase MongoDate

Introducción

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 información de zonas horarias. Si fuera necesario, la zona horaria deberá ser almacenada en otro campo. Además, esto significa que cualquier nivel de precisión más 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;

/* Métodos */

MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] )

public string MongoDate::__toString ( void )}

Page 200: Driver Nativo MongoDB

200Driver nativo MongoDB

MongoDate::__construct

MongoDate::__construct -- Crea un nuevo objeto fecha

Descripción

MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] )

Crea una nueva fecha. Si no se rellena ningún parámetro, se utilizará la hora actual.

Parámetros

sec

Número 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 cómo crear una nueva fecha con la hora actual y una nueva fecha con la hora proporcionada.

<?php

$d = new MongoDate();echo "$d\n";$d = new MongoDate(1234567890);echo "$d\n";$d = new MongoDate(strtotime("2009-05-01 00:00:01"));echo "$d\n";

?>

El resultado del ejemplo sería algo similar a:

0.23660600 12356850670.00000000 12345678900.00000000 1241150401

Page 201: Driver Nativo MongoDB

201Driver nativo MongoDB

Ver también

• MongoDate::__toString

Page 202: Driver Nativo MongoDB

202Driver nativo MongoDB

MongoDate::__toString

MongoDate::__toString -- Devuelve una representación en forma de texto de esta fecha

Descripción

public string MongoDate::__toString ( void )

Devuelve una representación en forma de texto de esta fecha, similar a la representación que devuelve microtime().

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Esta fecha.

Page 203: Driver Nativo MongoDB

203Driver nativo MongoDB

Clase MongoRegex

Introducción

Esta clase se puede usar para crear expresiones regulares. Normalmente, estas expresiones se usarán para consultar la base de datos y localizar textos que coincidan. Con menos frecuencia, se almacenarán en la base de datos para su posterior consulta.

Mongo reconoce seis banderas de expresiones regulares:

• i Insensible a mayúsculas

• m Multilínea

• x Puede contener comentarios

• l local

• s "." coincidirá con todo, incluyendo cambios de línea

• u unicode

Clases sinopsis

MongoRegex

MongoRegex {

/* Campos */

public string regex;

public string flags;

/* Métodos */

MongoRegex::__construct ( string $regex )

public string MongoRegex::__toString ( void )}

Page 204: Driver Nativo MongoDB

204Driver nativo MongoDB

MongoRegex::__construct

MongoRegex::__construct -- Crea una nueva expresión regular

Descripción

MongoRegex::__construct ( string $regex )

Crea una nueva expresión regular.

Parámetros

regex

Texto de la expresión regular, con la forma /expresión/banderas.

Valores devueltos

Devuelve una nueva expresión regular.

Ejemplos

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

Este ejemplo usa una expresión 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 también

• MongoRegex::__toString

Page 205: Driver Nativo MongoDB

205Driver nativo MongoDB

MongoRegex::__toString

MongoRegex::__toString -- Representación en forma de texto de esta expresión regular

Descripción

public string MongoRegex::__toString ( void )

Devuelve la representación en forma de texto de esta expresión regular.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Esta expresión regular en la forma "/expresión/banderas".

Ejemplos

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

<?php

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

?>

El resultado del ejemplo sería algo similar a:

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

Page 206: Driver Nativo MongoDB

206Driver nativo MongoDB

Clase MongoBinData

Introducción

Objeto para almacenar y consultar datos binarios de la base de datos.

El tamaño máximo de un objeto que puede insertarse en la base de datos es 4Mb. Para datos superiores (películas, música, autobiografía de Henry Kissinger), utilice MongoGridFS. Para datos inferiores a 4Mb, lo más probable es que lo más sencillo sea empotrarlo al documento utilizando MongoBinData.

Por ejemplo, para empotrar una imagen a un documento, se podría 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 especificación BSON). Por omisión, 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;

Page 207: Driver Nativo MongoDB

207Driver nativo MongoDB

const int MongoBinData::CUSTOM = 128;

/* Fields */

public string bin;

public int type = 2;

/* Métodos */

public MongoBinData::__construct ( string $data [, int $type = 2 ] )

public string MongoBinData::__toString ( void )}

Constantes predefinidas

Tipos de Datos Binarios

MongoBinData::FUNC 0x01Función.

MongoBinData::BYTE_ARRAY 0x02Array de bytes.

MongoBinData::UUID 0x03Identificador Único Universal.

MongoBinData::MD5 0x05MD5.

MongoBinData::CUSTOM 0xf0Tipo definido por el usuario.

Page 208: Driver Nativo MongoDB

208Driver nativo MongoDB

MongoBinData::__construct

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

Descripción

public MongoBinData::__construct ( string $data [, int $type = 2 ] )

Crea un nuevo objeto de datos binarios

Hay cinco tipos reconocidos de datos binarios según la especificación BSON: función (0x01), matriz de bytes (0x02), UUID (0x03), MD5 (0x05), y definido por el usuario (0x80). El tipo por omisión es matriz de bytes (0x02). No hay ninguna diferencia en particilar sobre cómo 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 número (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 función con datos binarios de este tipo.

Parámetros

data

Datos binarios.

type

Tipo de datos.

Valores devueltos

Devuelve un nuevo objeto de datos binarios.

Page 209: Driver Nativo MongoDB

209Driver nativo MongoDB

MongoBinData::__toString

MongoBinData::__toString -- Representación en forma de string de este objeto de datos binarios

Descripción

public string MongoBinData::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

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

Page 210: Driver Nativo MongoDB

210Driver nativo MongoDB

Clase MongoInt32

Introducción

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;

/* Métodos */

public MongoInt32::__construct ( string $value )

public string MongoInt32::__toString ( void )}

Campos

valueEste es el valor en forma de texto del número de 64 bits. Por ejemplo, el valor de 123 sería "123".

Page 211: Driver Nativo MongoDB

211Driver nativo MongoDB

MongoInt32::__construct

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

Descripción

public MongoInt32::__construct ( string $value )

Crea un nuevo número de 32 bits con el valor proporcionado.

Parámetros

value

Un número.

Valores devueltos

Devuelve un nuevo entero.

Page 212: Driver Nativo MongoDB

212Driver nativo MongoDB

MongoInt32::__toString

MongoInt32::__toString -- Devuelve al representación en forma de texto de este entero de 32 bits

Descripción

public string MongoInt32::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la representación en forma de texto de este entero.

Page 213: Driver Nativo MongoDB

213Driver nativo MongoDB

Clase MongoInt64

Introducción

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;

/* Métodos */

public MongoInt64::__construct ( string $value )

public string MongoInt64::__toString ( void )}

Campos

valueEste es el valor en forma de texto del número de 64 bits. Por ejemplo, el valor de 123 sería "123".

Page 214: Driver Nativo MongoDB

214Driver nativo MongoDB

MongoInt64::__construct

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

Descripción

public MongoInt64::__construct ( string $value )

Crea un nuevo número de 64 bits con el valor proporcionado.

Parámetros

value

Un número.

Valores devueltos

Devuelve un nuevo entero.

Page 215: Driver Nativo MongoDB

215Driver nativo MongoDB

MongoInt64::__toString

MongoInt64::__toString -- Devuelve la representación en forma de texto de este entero de 64 bits

Descripción

public string MongoInt64::__toString ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve la representación en forma de texto de este entero.

Page 216: Driver Nativo MongoDB

216Driver nativo MongoDB

Clase MongoDBRef

Introducción

Esta clase puede usarse para crear enlaces ligeros entre objetos de diferencias colecciones.

Motivación: Supongamos que necesitamos referirnos a un documento en otra colección. La forma más fácil es crear un nuevo campo en el documento actual. Por ejemplo, si tenemos una colección "personas" y una colección "direcciones", quizás queramos crear un enlace entre cada documento de persona y un documento de dirección:<?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 dirección de la persona consultando la colección "direcciones" con el MongoId que almacenamos en la colección "personas".

Supongamos ahora que tenemos un caso más general, donde no sabemos qué colección (o incluso qué base de datos) contiene el documento referenciado. MongoDBRef es una buena elección para estos casos, ya que es un formato común que todos los drivers y bases de datos podrán 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., podríamos usar MongoDBRef para seguir la pista de con qué colección se asocia cada gusto:<?php

$personas = $db->selectCollection("personas");

// modelismo ferroviario está en la colección "hobbies"$ferroRef = MongoDBRef::create("hobbies", $modelismoFerroviario['_id']);// fútbol está en la colección "deportes"$futbolRef = MongoDBRef::create("deportes", $futbol['_id']);

Page 217: Driver Nativo MongoDB

217Driver nativo MongoDB

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

?>

Las referencias a bases de datos se pueden concebir como hipervínculos: proporcionan una dirección única a otro documento, pero no cargan ni redirigen automáticamente 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 métodos estáticos para poder manipular las referencias a bases de datos.

Clases sinopsis

MongoDBRef

MongoDBRef {

/* Métodos */

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 también

Documentación de MongoDB sobre » referencias a bases de datos.

Page 218: Driver Nativo MongoDB

218Driver nativo MongoDB

MongoDBRef::create

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

Descripción

public static array MongoDBRef::create ( string $collection, mixed $id [, string $database ] )

Si no se especifica ninguna base de datos, se utiliza la actual.

Parámetros

collection

Nombre de la colección (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 colección addresses. La función MongoCollection::getName() devuelve el nombre de la colección (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);?>

Page 219: Driver Nativo MongoDB

219Driver nativo MongoDB

Ver también

• MongoDB::createDBRef• MongoCollection::createDBRef

Page 220: Driver Nativo MongoDB

220Driver nativo MongoDB

MongoDBRef::get

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

Descripción

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

Parámetros

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 dirección$direccion = MongoDBRef::get($gente->db, $persona['direccion']);

?>

Ver también

• MongoDB::getDBRef• MongoCollection::getDBRef

Page 221: Driver Nativo MongoDB

221Driver nativo MongoDB

MongoDBRef::isRef

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

Descripción

public static bool MongoDBRef::isRef ( mixed $ref )

Esta función 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 válido de referencias de bases de datos (objeto o array con los campos $ref y $id).

Parámetros

ref

Array u objeto a comprobar.

Valores devueltos

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

Page 222: Driver Nativo MongoDB

222Driver nativo MongoDB

Clase MongoMinKey

Introducción

MongoMinKey es un tipo especial de la base de datos que se evalúa 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 posición.

MongoMinKey no tiene ni campos, ni métodos, ni constantes asociados. Es simplemente el valor "más 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" => "reunión 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 después el documento de reunión de personal. El documento de almorzar siempre será el primero, independientemente de lo que añadamos a la colección (a no ser que se añadan otros documentos con MongoMinKey en el campo "hacer el").

Page 223: Driver Nativo MongoDB

223Driver nativo MongoDB

Clase MongoMaxKey

Introducción

MongoMaxKey es un tipo especial de la base de datos que se evalúa 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 métodos, ni constantes asociados. Es simplemente el valor "más 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" => "reunión de personal", "hacer el" => new MongoDate(strtotime("+4 days"))));

$cursor = $collection->find()->sort(array("hacer el" => 1));

?>

El cursor contendrá el documento de la reunión de personal, y después el documento de fregar platos. El documento de fregar platos siempre será el último, independientemente de lo que añadamos a la colección (a no ser que se añadan otros documentos con MongoMaxKey en el campo "hacer el").

Page 224: Driver Nativo MongoDB

224Driver nativo MongoDB

Clase MongoTimestamp

Introducción

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 añadiendo/actualizando el timestamp de un documento. A no ser que se esté usando algo que interactúe con sharding, deténgase, y vaya directamente a MongoDate, no esté aquí de paso. Ésta no es la clase que está buscando.

Si está escribiendo herramientas de sharding, continúe.

Clases sinopsis

MongoTimestamp

MongoTimestamp {

/* Campos */

public int sec = 0;

public int inc = 0;

/* Métodos */

MongoTimestamp::__construct ( [ int $sec = time() [, int $inc ] ] )

public string MongoTimestamp::__toString ( void )}

Page 225: Driver Nativo MongoDB

225Driver nativo MongoDB

MongoTimestamp::__construct

MongoTimestamp::__construct -- Crea un nuevo timestamp

Descripción

MongoTimestamp::__construct ( [ int $sec = time() [, int $inc ] ] )

Crea un nuevo timestamp. Si no se rellenan los parámetros, se usa la hora actual con incremento automático. El incremento se establece a 0 cuando se carga el módulo, y se incrementa cada vez que se invoca a este constructor (cuando no se rellene el parámetro $inc).

Parámetros

sec

Número de segundos desde el 1 de enero de 1970.

inc

Incremento.

Valores devueltos

Devuelve el nuevo timestamp.

Ver también

• MongoTimestamp::__toString

Page 226: Driver Nativo MongoDB

226Driver nativo MongoDB

MongoTimestamp::__toString

MongoTimestamp::__toString -- Devuelve la representación en forma de texto de este timestamp

Descripción

public string MongoTimestamp::__toString ( void )

Devuelve el campo "sec" del timestamp.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

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

Page 227: Driver Nativo MongoDB

227Driver nativo MongoDB

Clases de GridFS

Page 228: Driver Nativo MongoDB

228Driver nativo MongoDB

Clase MongoGridFS

Introducción

Utilidad para almacenar y extraer ficheros de la base de datos.

GridFS es una especificación 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 tamaño, automáticamente se dividiría en porciones menores, y cada bloque se guardará como un documento en la colección de bloques.

Cada documento de la colección de ficheros contiene el nombre de fichero, fecha de subida, y un código hash md5. También contiene un campo único _id, que se puede utilizar para consultar el contenido del fichero en la colección de bloques. Cada documento de la colección de bloques contiene un bloque de datos binarios, un campo files_id que se corresponde con el _id de su fichero, y la posición de este bloque respecto a los demás.

Por ejemplo, el documento de ficheros podría ser algo tal que así:<?phparray("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);?>mientras que los documentos de bloques:<?phparray("files_id" => 123456789, "n" => 0, "data" => new MongoBinData("abc"));array("files_id" => 123456789, "n" => 1, "data" => new MongoBinData("def"));array("files_id" => 123456789, "n" => 2, "data" => new MongoBinData("ghi"));array("files_id" => 123456789, "n" => 3, "data" => new MongoBinData("jkl"));?>Por supuesto, el tamaño por omisión 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 información que se desee que vean. Por ejemplo, en lugar de:

<?php

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

?>

utilice algo así:

Page 229: Driver Nativo MongoDB

229Driver nativo MongoDB

<?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 métodos de MongoCollection, que actúan sobre las colecciones de ficheros:

<?php

$grid = $db->getGridFS();$grid->update(array("filename" => "foo"), $newObj); // actualización en la colección de ficheros

?>

Otro ejemplo de manipulación de metadatos:

<?php

// guardar un fichero$id = $grid->storeFile("juego.tgz");$juego = $grid->findOne();

// añadir 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 también acceder a los bloques de una colección a partir de una instancia de MongoGridFS:

<?php

$chunks = $grid->chunks; // $chunks es un MongoCollection normal$chunks->insert(array("x" => 4));

?>

Hay algunos métodos de MongoGridFS que comparten nombres con métodos de MongoCollection, pero que se comportan de un modo ligeramente diferente. Por ejemplo,

Page 230: Driver Nativo MongoDB

230Driver nativo MongoDB

MongoGridFS::remove() eliminará cualquier objeto, junto con su contenido en la colección de bloques, cuando se cumplan los criterios de la colección de ficheros.

Para almacenar cualquier otra cosa en GridFS, hay varias opciones. Si se tuviera un nombre de fichero, se podría 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 colección 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 ningún método que cree automáticamente un flujo de bloques, pero resulta muy sencillo hacer escrituras realizando consultas a la colección $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;

Page 231: Driver Nativo MongoDB

231Driver nativo MongoDB

protected string chunksName = NULL;

/* Métodos */

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 también

Documentación principal de MongoDB de » GridFS. Hay también una buena introducción a » cómo guardar datos subidos por usuarios y a » cómo añadir metadatos en LightCubeSolutions.com.

Page 232: Driver Nativo MongoDB

232Driver nativo MongoDB

MongoGridFS::__construct

MongoGridFS::__construct -- Crea una nueva colección de ficheros

Descripción

MongoGridFS::__construct ( MongoDB $db [, string $prefix = "fs" [, mixed $chunks = "fs" ] ] )

Los ficheros se almacenan en dos colecciones. La primera contiene información descriptiva de los ficheros. La segunda contiene los bloques del contenido real del fichero. Por omisión, 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 utilizaría las colecciones misficheros.files y misficheros.chunks.

Parámetros

db

Base de datos.

files

Prefijo opcional para el nombre de la colección.

Page 233: Driver Nativo MongoDB

233Driver nativo MongoDB

MongoGridFS::delete

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

Descripción

public bool MongoGridFS::delete ( mixed $id )

Parámetros

id

_id del fichero a eliminar.

Valores devueltos

Devuelve un indicador de si la orden de eliminación se envió o no con éxito a la base de datos.

Page 234: Driver Nativo MongoDB

234Driver nativo MongoDB

MongoGridFS::drop

MongoGridFS::drop -- Da de baja una colección de ficheros y de bloques

Descripción

public array MongoGridFS::drop ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Respuesta de la base de datos.

Page 235: Driver Nativo MongoDB

235Driver nativo MongoDB

MongoGridFS::find

MongoGridFS::find -- Selecciona ficheros

Descripción

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

Parámetros

query

La consulta

fields

Campos que devolverá.

Valores devueltos

Un objeto de la clase MongoGridFSCursor.

Page 236: Driver Nativo MongoDB

236Driver nativo MongoDB

MongoGridFS::findOne

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

Descripción

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

Parámetros

query

El nombre del fichero o las condiciones de búsqueda.

Valores devueltos

Devuelve un MongoGridFSFile o NULL.

Ejemplos

Ejemplo #1 - Ejemplo de MongoGridFS::findOne

Ejemplo que muestra cómo 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 más información sobre cómo trabajar con ficheros.

El resultado del ejemplo sería algo similar a:

MongoGridFSFile Object( [file] => Array ( [_id] => MongoId Object ( )

[filename] => nombredefichero.tgz

Page 237: Driver Nativo MongoDB

237Driver nativo MongoDB

[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 )

)

Page 238: Driver Nativo MongoDB

238Driver nativo MongoDB

MongoGridFS::get

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

Descripción

public MongoGridFSFile MongoGridFS::get ( mixed $id )

Parámetros

id

_id del fichero a localizar.

Valores devueltos

Devuelve el fichero si se le encuentra, o NULL.

Page 239: Driver Nativo MongoDB

239Driver nativo MongoDB

MongoGridFS::put

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

Descripción

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

Parámetros

filename

Nombre del fichero.

extra

Otra metainformación a añadir junto con el fichero almacenado.

Valores devueltos

Devuelve el _id del objeto guardado.

Page 240: Driver Nativo MongoDB

240Driver nativo MongoDB

MongoGridFS::remove

MongoGridFS::remove -- Elimina ficheros de las colecciones

Descripción

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

Parámetros

query

Nombre de fichero o condiciones de búsqueda.

options

Opciones para la eliminación. Las opciones válidas son:

• "safe" Comprobar que la eliminación ha tenido éxito.

Valores devueltos

Devuelve un indicador sobre si la eliminación se envió o no con éxito a la base de datos.

Page 241: Driver Nativo MongoDB

241Driver nativo MongoDB

MongoGridFS::storeBytes

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

Descripción

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

Parámetros

bytes

Un string con los bytes a almacenar.

extra

Otra metainformación a añadir 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 opción "safe" y la inserción falla.

Page 242: Driver Nativo MongoDB

242Driver nativo MongoDB

MongoGridFS::storeFile

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

Descripción

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

Parámetros

filename

Nombre del fichero.

extra

Otra metainformación a añadir 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 opción "safe" está establecida y la inserción falla.

Page 243: Driver Nativo MongoDB

243Driver nativo MongoDB

MongoGridFS::storeUpload

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

Descripción

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 parámetro name.

Parámetros

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

Versión Descripción

1.2.5 Cambiado el segundo parámetro a un array de metadatos. Antes de la versión 1.2.5, el segundo parámetro fue un string opcional reemplazando el nombre de archivo.

Page 244: Driver Nativo MongoDB

244Driver nativo MongoDB

Clase MongoGridFSFile

Introducción

Objeto fichero de una base de datos.

Clases sinopsis

MongoGridFSFile

MongoGridFSFile {

/* Campos */

public array file = NULL;

protected MongoGridFS gridfs = NULL;

/* Métodos */

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 ] )}

Page 245: Driver Nativo MongoDB

245Driver nativo MongoDB

MongoGridfsFile::__construct

MongoGridfsFile::__construct -- Crea un nuevo fichero GridFS

Descripción

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

Parámetros

gridfs

La instancia padre de MongoGridFS.

file

Un fichero de la base de datos.

Valores devueltos

Devuelve un nuevo MongoGridFSFile.

Page 246: Driver Nativo MongoDB

246Driver nativo MongoDB

MongoGridFSFile::getBytes

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

Descripción

public string MongoGridFSFile::getBytes ( void )

Aviso: se cargará el fichero en memoria. Si el fichero es de mayor tamaño que la memoria, provocará un problema.

Parámetros

Esta función no tiene parámetros.

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();?>

Page 247: Driver Nativo MongoDB

247Driver nativo MongoDB

MongoGridFSFile::getFilename

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

Descripción

public string MongoGridFSFile::getFilename ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nombre de fichero.

Page 248: Driver Nativo MongoDB

248Driver nativo MongoDB

MongoGridFSFile::getSize

MongoGridFSFile::getSize -- Devuelve el tamaño de este fichero

Descripción

public int MongoGridFSFile::getSize ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el tamaño de este fichero

Page 249: Driver Nativo MongoDB

249Driver nativo MongoDB

MongoGridFSFile::write

MongoGridFSFile::write -- Escribe este fichero en disco

Descripción

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

Parámetros

filename

La ubicación en la que se escribirá el fichero. Si no se da ninguno, se usará el nombre del fichero almacenado.

Valores devueltos

Devuelve el número 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');?>

Page 250: Driver Nativo MongoDB

250Driver nativo MongoDB

Clase MongoGridFSCursor

Introducción

Cursor para los resultados de ficheros de bases de datos.

Clases sinopsis

MongoGridFSCursor

extends MongoCursor {

/* Campos */

protected MongoGridFS gridfs = NULL;

/* Métodos */

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 )}

Page 251: Driver Nativo MongoDB

251Driver nativo MongoDB

MongoGridFSCursor::__construct

MongoGridFSCursor::__construct -- Crea un nuevo cursor

Descripción

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

Parámetros

gridfs

Colección GridFS relacionada.

connection

Conexión a la base de datos.

ns

Nombre completo de la base de datos y de la colección.

query

Consulta a la base de datos.

fields

Campos que se desea obtener.

Valores devueltos

Devuelve el nuevo cursor.

Page 252: Driver Nativo MongoDB

252Driver nativo MongoDB

MongoGridFSCursor::current

MongoGridFSCursor::current -- Devuelve el fichero actual

Descripción

public MongoGridFSFile MongoGridFSCursor::current ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Fichero actual.

Page 253: Driver Nativo MongoDB

253Driver nativo MongoDB

MongoGridFSCursor::getNext

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

Descripción

public MongoGridFSFile MongoGridFSCursor::getNext ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el siguiente fichero.

Page 254: Driver Nativo MongoDB

254Driver nativo MongoDB

MongoGridFSCursor::key

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

Descripción

public string MongoGridFSCursor::key ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Nombre de fichero del resultado actual.

Page 255: Driver Nativo MongoDB

255Driver nativo MongoDB

Miscelánea

Page 256: Driver Nativo MongoDB

256Driver nativo MongoDB

Clase MongoLog

Introducción

Se puede utilizar para obtener información 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 omisión, estos registros están deshabilitados. Esta clase permite habilitar niveles específicos de informes para determinadas áreas del driver. Algunos ejemplos:

<?php

// muestra todos los mensajes posiblesMongoLog::setLevel(MongoLog::ALL); // todos los niveles de registrosMongoLog::setModule(MongoLog::ALL); // todas las partes del driver

// muestra eventos significativos sobre fallos en conjuntos de réplicasMongoLog::setLevel(MongoLog::INFO);MongoLog::setModule(MongoLog::RS);

// muestra registros de nivel de información y de seguimiento sobre conjuntos de réplicas y sobre agrupamientos de conexionesMongoLog::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;

Page 257: Driver Nativo MongoDB

257Driver nativo MongoDB

const int MongoLog::FINE;

constantes de módulos {

const int MongoLog::RS;

const int MongoLog::POOL;

const int MongoLog::IO;

/* Campos */

public int level;

public int module;

/* Métodos */

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::NONEConstante para deshabilitar los registros.

MongoLog::ALLConstante para notificar todos los registros.

Constantes de Nivel de MongoLog

Estas constantes pueden usarse por MongoLog::setLevel().

MongoLog::WARNINGMuestra mensajes sobre situaciones excepcionales no críticas.

MongoLog::INFOMuestra eventos que pudieran ser de interes para administradores, pero no especialmente notorios.

MongoLog::FINE

Page 258: Driver Nativo MongoDB

258Driver nativo MongoDB

Muestra la mayor parte de eventos que realiza el driver. Dependiendo del módulo que se esté analizando, este nivel podría ser demasiado ruidoso. Se usa principalmente para depuración.

Constantes de módulos de MongoLog

Estas constantes pueden usarse por MongoLog::setModule().

MongoLog::RSRegistra las actividades de los conjuntos de réplicas. Caídas, comprobaciones, elección de secundarios a los que leer, etc..

MongoLog::POOLRegistra las actividades de los agrupamientos de conexiones. Creación de nuevas conexiones, reutilización de conexiones, y cierre de conexiones.

MongoLog::IORegistra el tráfico de y desde la base de datos. Este modo generará un gran número de mensajes de registro, salvo en el caso de que la aplicación sea trivial.

Page 259: Driver Nativo MongoDB

259Driver nativo MongoDB

MongoLog::getLevel

MongoLog::getLevel -- Obtiene el nivel de registro

Descripción

public static int MongoLog::getLevel ( void )

Esto puede ser usado para ver el nivel de registro. Utilice las constantes descritas en la sección MongoLog con los operadores bit a bit para comprobar el nivel.

<?php

if (MongoLog::getLevel() & MongoLog::FINE) { echo "un montón de logs\n";}

if (MongoLog::getLevel() ^ MongoLog::NONE) { echo "logging, al menos un poco\n";}

if (MongoLog::getLevel() == MongoLog::ALL) { echo "logging al más alto nivel\n";}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve el nivel actual.

Page 260: Driver Nativo MongoDB

260Driver nativo MongoDB

MongoLog::getModule

MongoLog::getModule -- Devuelve los módulos que están actualmente se están registrando

Descripción

public static int MongoLog::getModule ( void )

Esta función se puede usar para conocer qué partes del driver se están registrando. Utilice las constantes descritas en la sección de MongoLog con operadores a nivel de bits para comprobar si algún módulo específico está siendo registrado.

<?php

if (MongoLog::getModule() & MongoLog::RS) { echo "registrando conjuntos de réplicas\n";}

if (MongoLog::getModule() ^ MongoLog::NONE) { echo "registrando algo\n";}

if ((MongoLog::getModule() & MongoLog::IO) == 0) { echo "no se están registrando entradas/salidas\n";}

?>

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Devuelve los módulos que actualmente se están registrando.

Page 261: Driver Nativo MongoDB

261Driver nativo MongoDB

MongoLog::setLevel

MongoLog::setLevel -- Establece el nivel de informe de mensajes

Descripción

public static void MongoLog::setLevel ( int $level )

Esta función se puede usar para establecer el nivel de detalles que se mostrarán, así como el tipo de información que se registrará. Utilice las constantes descritas en la sección MongoLog con operadores a nivel de bits para especificar estos niveles.

<?php

// primero, habilitamos todos los mensajes para un móduloMongoLog::setModule(MongoLog::POOL);

// registramos los mensajes de todos los nivelesMongoLog::setLevel(MongoLog::ALL);

// registramos mensaje de tipo 'aviso' e informativosMongoLog::setLevel(MongoLog::WARNING|MongoLog::INFO);

// registramos todo, excepto actividades de grano finoMongoLog::setLevel(MongoLog::ALL & (~MongoLog::FINE));

?>

Tenga presente que también puede llamar a MongoLog::setModule() para escoger qué partes del driver registrar.

Parámetros

level

Nivel que se desea registrar.

Page 262: Driver Nativo MongoDB

262Driver nativo MongoDB

MongoLog::setModule

MongoLog::setModule -- Establece de qué funcionalidades se deben notificar eventos

Descripción

public static void MongoLog::setModule ( int $module )

Esta función puede usarse para establecer de qué partes del driver se deben registrar eventos. Para especificar los módulos, utilice las constantes descritas en la sección MongoLog con operadores a nivel de bits.

<?php

// primero, habilitamos todos los niveles de registroMongoLog::setLevel(MongoLog::ALL);

// registramos las actividades de conjuntos de réplicasMongoLog::setModule(MongoLog::RS);

// registramos las actividades de conjuntos de réplicas y de agrupamientos de conexionesMongoLog::setModule(MongoLog::RS|MongoLog::ALL);

// registramos todo excepto actividades de E/SMongoLog::setModule(MongoLog::ALL & (~MongoLog::IO));

?>

Tenga presente que también se puede invocar a MongoLog::setLevel() para habilitar el registro de mensajes.

Parámetros

module

El/los módulo/s que desea registrar.

Page 263: Driver Nativo MongoDB

263Driver nativo MongoDB

Clase MongoPool

Introducción

En la versión 1.2.0 del driver se incorporaron los agrupamiento (pools) de conexiones. Esta clase ofrece herramientras de control e información sobre agrupamientos.

Nota

Originalmente, las funciones de esta clase eran miembros estáticos de Mongo. Se recomienda encarecidamente utilizar esta clase en un futuro, ya que las funciones estáticas de Mongo están consideradas obsoletas.

Clases sinopsis

MongoPool

MongoPool {

/* Métodos */

public static int MongoPool::getSize ( void )

public array MongoPool::info ( void )

public static bool MongoPool::setSize ( int $size )}

Page 264: Driver Nativo MongoDB

264Driver nativo MongoDB

MongoPool::getSize

MongoPool::getSize -- Devuelve el tamaño actual de un agrupamiento de conexiones

Descripción

public static int MongoPool::getSize ( void )

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Retorna el tamaño actual del agrupamiento.

Ejemplos

Ejemplo #1 - Cambiar el tamaño de un agrupamiento

Devuelve el tamaño por omisión del agrupamiento, esatblece un nuevo tamaño, y muestra el nuevo tamaño junto con información de depuración. Tenga presente que esta acción sólo afecta a las nuevas conexiones; no modifica las anteriores.

<?php

$connection = new Mongo("host1");

// tamaño de agrupamiento: -1echo "tamaño de agrupamiento: ".MongoPool::getSize()."\n";

echo "establecemos un tamaño de agrupamiento de 200\n";

MongoPool::setSize(200);

// tamaño de agrupamiento: 200echo "tamaño de agrupamiento: ".MongoPool::getSize()."\n";

$conn2 = new Mongo("host2");

// conexiones disponibles en host1: -2// conexiones disponibles en host2: 199var_dump(Mongo::poolDebug());

?>

Ver también

Page 265: Driver Nativo MongoDB

265Driver nativo MongoDB

• MongoPool::setSize()• MongoPool::info()• Documentación sobre conexiones.

Page 266: Driver Nativo MongoDB

266Driver nativo MongoDB

MongoPool::info

MongoPool::info -- Devuelve información sobre todos los agrupamientos de conexiones

Descripción

public array MongoPool::info ( void )

Devuelve un array con información sobre los agrupamientos de conexiones.

Parámetros

Esta función no tiene parámetros.

Valores devueltos

Cada agrupamiento de conexión tiene un identificador, que comienza con el nombre de host. Se muestra la siguiente información para cada agrupamiento:in use

Número de conexiones actualmente en uso por instancias de Mongo.

in pool

Número de conexiones que hay actualmente en el agrupamiento (sin usar).

remaining

Número de conexiones que se pueden crear en este agrupamiento. Por ejemplo, supongamos que un agrupamiento tenía 5 conexiones pendientes y 3 conexiones en agrupamiento. Podríamos 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 número negativo indica que este agrupamiento puede lanzar conexiones ilimitadas. Antes de crear un agrupamiento, se puede cambiar su número máximo de conexiones invocando a Mongo::setPoolSize(). Una vez que se ha llamado a esta función, no se podrá modificar su tamaño.

total

Número total de conexiones permitidas en este agrupamiento. Será mayor o igual a la suma de "in use" + "in pool" (o -1).

timeout

Tiempo máximo de espera para las conexiones de este agrupamiento. Indica por cuánto tiempo las conexiones intentarán conectar con un servidor antes de darse por vencidas.

waiting

Si se ha restringido el tamaño del agrupamiento, los procesos que soliciten conexiones de este agrupamiento podrán quedarse bloqueados hasta que otros procesos devuelvan sus conexiones. Este campo indica por cuántos

Page 267: Driver Nativo MongoDB

267Driver nativo MongoDB

milisegundos quedarán bloqueados esperando a que se libere una conexión. Si este número creciera demasiado, quizás sea conveniente usar MongoPool::setSize() para añadir más conexiones al agrupamiento.

Page 268: Driver Nativo MongoDB

268Driver nativo MongoDB

MongoPool::setSize

MongoPool::setSize -- Establece el tamaño de los nuevos agrupamientos de conexiones

Descripción

public static bool MongoPool::setSize ( int $size )

Establece el número máximo de conexiones que podrán crear los nuevos agrupamientos.

Parámetros

size

Número máximo de conexiones que podrán crear los nuevos agrupamientos. Un número negativo indica que el agrupamiento podrá lanzar un número infinito de conexiones.

Valores devueltos

Devuelve el valor anterior de tamaño de agrupamiento.

Ejemplos

Ejemplo #1 - Ejemplo de Mongo::setPoolSize()

Si se establece un tamaño de agrupamiento de n y creamos n conexiones, al intentar crear la conexión n+1 se lanzará una excepción de tipo MongoConnectionException.

<?php

// sólo permitimos una conexión al servidorMongoPool::setSize(1);

// creamos una conexión a localhost:27017$m1 = new Mongo();

// intentamos crear una segunda conexión a localhost:27017// puesto que sólo se permite una, se emitirá una excepción$m2 = new Mongo();

?>

El resultado del ejemplo sería algo similar a:

Page 269: Driver Nativo MongoDB

269Driver nativo MongoDB

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

Ver también

• MongoPool::getSize()• MongoPool::info()• Documentación sobre conexiones.

Page 270: Driver Nativo MongoDB

270Driver nativo MongoDB

Funciones

Page 271: Driver Nativo MongoDB

271Driver nativo MongoDB

Funciones de Mongo

Page 272: Driver Nativo MongoDB

272Driver nativo MongoDB

bson_decode

bson_decode -- Decodifica un objecto BSON a un array PHP

Descripción

array bson_decode ( string $bson )

Esta función es muy beta todavía y es inútil para el 99% de usuarios. Solo es útil en casos especiales, como cuando se necesita escribir tu propio driver encima del driver de PHP.

Parámetros

bson

El BSON a ser decodificado.

Valores devueltos

Devuelve un objecto BSON decodificado.

Page 273: Driver Nativo MongoDB

273Driver nativo MongoDB

bson_encode

bson_encode -- Serializa una variable PHP a un string BSON

Descripción

string bson_encode ( mixed $anything )

Esta función es muy beta todavía y es inútil para el 99% de usuarios. Solo es útil en casos especiales, como cuando se necesita escribir tu propio driver encima del driver de PHP.

Parámetros

anything

La variable ha serializar.

Valores devueltos

Devuelve un string serializado.

Page 274: Driver Nativo MongoDB

274Driver nativo MongoDB

Excepciones

Peculiaridades en VMWare

Si se está ejecutando VMWare en Windows, y se usa CIFS, al pausar la máquina 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 documentación de Ubuntu para ver las instrucciones más actualizadas.

Page 275: Driver Nativo MongoDB

275Driver nativo MongoDB

Clase MongoException

Introducción

Excepción Mongo predeterminada.

Abarca un gran número de condiciones de error que, eventualmente, podrán moverse a excepciones más específicas, pero que en cualquier caso siempre extenderán MongoException.

• The MongoSomething object has not been correctly initialized by its constructor Código: 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? Código: 1 Se ha intentado guardar el valor "" como clave. En general, no se debe hacer esto. "" podría provocar errores al acceder a subobjetos, además 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 comprobación. Si se sobrescribe, se recomienda encarecidamente establecer la comprobación estricta de errores para evitar errores de interpolación de textos.

• '.' not allowed in key: <key> Código: 2 Se ha intentado escribir una clave que contiene un ".", lo cual está prohibido.

• insert too large: <size>, max: <max> Código: 3 Se ha intentado enviar demasiada información de una vez a la base de datos: la base de datos sólo acepta inserciones de hasta un determinado tamaño (actualmente 16 MB).

• no elements in doc Código: 4 Se ha intentado guardar un documento que no contiene ningún campo.

• size of BSON doc is <size> bytes, max <max>MB Código: 5 Se ha intentado guardar un documento con un tamaño superior al que MongoDB puede guardar.

• no documents given Código: 6 Se ha intentado insertar por lotes un array vacío de documentos.

• MongoCollection::group takes an array, object, or MongoCode key Código: 7 Se han enviado a MongoCollection::group() parámetros del tipo equivocado

• field names must be strings Código: 8 Deben formatearse los selectores de la siguiente forma: array("field1" => 1, "field2" => 1, ..., "fieldN" => 1).

• invalid regex Código: 8 La expresión regular pasada a MongoRegex no cumple la forma correcta.

• MongoDBRef::get: $ref field must be a string Código: 10

• MongoDBRef::get: $db field must be a string Código: 11

Page 276: Driver Nativo MongoDB

276Driver nativo MongoDB

• non-utf8 string: <str> Código: 12 Sucede cuando se intenta enviar un texto que no es utf8 a la base de datos. Todos los textos que se envíen a la base de datos deben estar en UTF8. Revise las opciones de php.ini para conocer la opción de transición que evita esta excepción.

• mutex error: <err> Código: 13 En entornos multihebra, el driver utiliza mutex para sincronizar las peticiones y las respuestas. Este es un error crítico que no se puede trazar. Es poco usual y debe notificarse a los mantenedores junto con cualquier información del sistema y los pasos que se han seguido para reproducir el error.

• index name too long: <len>, max <max> characters Código: 14 No se crearán índices con nombres superiores a 128 caracteres. Si se obtuviera este error, se debería usar la opción "name" de MongoCollection::ensureIndex() para crear un nombre más corto para el índice.

Clases sinopsis

MongoException

extends Exception {}

Page 277: Driver Nativo MongoDB

277Driver nativo MongoDB

The MongoCursorException class

Introducción

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_ dup key: { : 1 }error code: 11000Note 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) {

Page 278: Driver Nativo MongoDB

278Driver nativo MongoDB

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.

Page 279: Driver Nativo MongoDB

279Driver nativo MongoDB

• 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

Page 280: Driver Nativo MongoDB

280Driver nativo MongoDB

MongoCursorException

extends MongoException {}

Page 281: Driver Nativo MongoDB

281Driver nativo MongoDB

Clase MongoCursorTimeoutException

Introducción

Lanzado cuando se excede el tiempo máximo de espera de una consulta. Puede establecer el tiempo de espera que se usará antes de lanzar esta excepción, llamando a MongoCursor::timeout() en el cursor, o mediante MongoCursor::$timeout. Esta variable estática resulta útil para consultas tales como comandos de la base de datos o en MongoCollection::findOne(), las cuales utilizan implícitamente cursores.

Clases sinopsis

MongoCursorTimeoutException

extends MongoCursorException {}

Page 282: Driver Nativo MongoDB

282Driver nativo MongoDB

Clase MongoConnectionException

Introducción

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 conexión:

• No server name given. Este error ocurre al pasar "" como nombre de servidor, probablemente por error tipográfico con interpolación 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]" serán lo que el driver haya descifrado que sean.

• Operation in progress Superado el tiempo de espera de conexión a la base de datos.

• Transport endpoint is not connected Generalmente indica que la cadena de conexión 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 conexión parece ser el maestro.

• couldn't get host info for [server] Indica que el DNS no puede resolver la dirección de servidor proporcionada. Posiblemente se trate de un error tipográfico, por ejemplo, "server" en lugar de "$server".

• Invalid Argument Puede provocarse al intentar conectar a una máquina que está funcionando pero la base de datos no está funcionando. Asegúrese 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 configuración por defecto no permite a Apache crear conexiones de red. Puede modificarse esto ejecutando:$ /usr/sbin/setsebool -P httpd_can_network_connect 1y 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

Page 283: Driver Nativo MongoDB

283Driver nativo MongoDB

MongoConnectionException

extends MongoException {}

Page 284: Driver Nativo MongoDB

284Driver nativo MongoDB

Clase MongoGridFSException

Introducción

Lanzado cuando hay errores al leer o escribir ficheros a la base de datos.

Clases sinopsis

MongoGridFSException

extends MongoException {}