Post on 21-Feb-2015
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
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.
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
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á:
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!
?>
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 );
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
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.
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() );}
?>
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
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/")));
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
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
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"));}
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
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" : [
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
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().
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'] . "";
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" }
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"}*/
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"))));
?>
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ónde realizar un ajuste de configuración.
He aquí una breve explicación de las directivas de configuración.
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", ":").
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.
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('!.
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
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.
30Driver nativo MongoDB
Clases del núcleo
Las clases del núcleo son la parte más importante del controlador.
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 */
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.
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.
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.
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.
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.
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
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.
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"));
?>
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"}
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");
?>
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.
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.
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)
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.
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());
47Driver nativo MongoDB
?>
Ver también
• Mongo::setPoolSize()• Mongo::poolDebug()• The connection documentation.
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.
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.
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)
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.
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?>
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.
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();
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.
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.
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).
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.
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 */
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
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.
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.
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.
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
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,
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).
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
68Driver nativo MongoDB
Lanza una excepción por defecto si el nombre no fuera válido.
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
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
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:
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);?>
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)
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.
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
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'];
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
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.
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.
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.
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.
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().
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.
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)}
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)}
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...
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ó.
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
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)
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.
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.
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.
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.
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.
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 ] ] ] )
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.
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.
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
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"...
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.
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)));
102Driver nativo MongoDB
?>
El resultado del ejemplo sería algo similar a:
int(3)int(1)
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
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
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));?>
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)
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)
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
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
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
111Driver nativo MongoDB
Documentación de MongoDB sobre » Ãndices por defecto y sobre » Ãndices geoespaciales.
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
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.
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')));
?>
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.
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.
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 )
118Driver nativo MongoDB
Ver también
• MongoCollection::createDBRef
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.
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.
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.
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
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:
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++; }'));
?>
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
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);
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.
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
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--;}
130Driver nativo MongoDB
?>
Ver también
Documentación de MongoDB sobre » remove.
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
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);
?>
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.
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 [].&.
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
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
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
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.
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.
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.
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 )
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
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.
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.
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));
?>
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
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.
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.
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)
150Driver nativo MongoDB
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.
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.
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.
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();
154Driver 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"]=>
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.
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.
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.
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.
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.
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.
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());
?>
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) }}
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.
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.
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.
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.
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.
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.
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.
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
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);
?>
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.
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));?>
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()) {
176Driver nativo MongoDB
break; } // read all results so far, wait for more sleep(10); } else { $results[] = $cursor->getNext(); }}
?>
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
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.
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.
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.
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.
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
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?
184Driver nativo MongoDB
Si se necesitara insertar documentos que pudieran tener dependencias cíclicas, deberá comprobarse a mano antes de pasarlo al driver.
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 )
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.
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
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
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.
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.
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.
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.
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".
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
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 )}
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; }"}
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))));
?>
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}); } }
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 )}
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
201Driver nativo MongoDB
Ver también
• MongoDate::__toString
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.
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 )}
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
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
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;
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.
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.
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.
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".
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.
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.
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".
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.
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.
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']);
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.
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);?>
219Driver nativo MongoDB
Ver también
• MongoDB::createDBRef• MongoCollection::createDBRef
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
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.
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").
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").
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 )}
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
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.
227Driver nativo MongoDB
Clases de GridFS
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í:
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,
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;
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.
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.
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.
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.
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.
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
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 )
)
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.
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.
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.
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.
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.
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.
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 ] )}
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.
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();?>
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.
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
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');?>
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 )}
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.
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.
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.
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.
255Driver nativo MongoDB
Miscelánea
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;
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
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.
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.
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.
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.
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.
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 )}
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
265Driver nativo MongoDB
• MongoPool::setSize()• MongoPool::info()• Documentación sobre conexiones.
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
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.
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:
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.
270Driver nativo MongoDB
Funciones
271Driver nativo MongoDB
Funciones de Mongo
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.
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.
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.
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
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 {}
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) {
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.
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
280Driver nativo MongoDB
MongoCursorException
extends MongoException {}
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 {}
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
283Driver nativo MongoDB
MongoConnectionException
extends MongoException {}
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 {}