Professional Documents
Culture Documents
Manual
Este manual trata algunos detalles sobre cmo usar MongoDB, aunque es ms una referencia del driver PHP. Para ms informacin sobre cmo disear un esquema, qu significa cada trmino, o cmo configurar el servidor de bases de datos, revise la documentacin de MongoDB.
Instalacin
El controlador MongoDB para PHP debe funcionar en cualquier sistema: Windows, Mac OS X, Unix, y Linux; pequeas y grandes mquinas; y plataformas de 32- y 64-bits; PHP 5.1, 5.2, y 5.3. Esta extensin PECL no se distribuye con PHP. Esta pgina proporciona informacin especifica acerca de la instalacin en diferentes sistemas y solucin de problemas que otros usuarios han resuelto.
Instalacin en *NIX Instalacin manual OS X Gentoo Fedora Instalacin en Windows Instrucciones de instalacin de terceros
Instalacin en *NIX
Ejecute:
$ sudo pecl install mongo
Si se est usando CentOS o Redhat, Csoke Arpad ha creado paquetes RPMs para estas distribuciones. Agregar la siguiente lnea en el fichero php.ini:
extension=mongo.so
Si pecl se quedar sin memoria al instalar, asegrese de que memory_limit en php.ini sea de al menos de 32MB.
Instalacin manual
Driver nativo MongoDB 2
Para los desarrolladores de controloladores y gente interesada en las ltimas correcciones, puede compilar el controlador desde las ltimas versiones en Github. Ir a Github y presione en el botn "download". Ejecute:
$ $ $ $ $ tar zxvf mongodb-mongodb-php-driver-<commit_id>.tar.gz cd mongodb-mongodb-php-driver-<commit_id> phpize ./configure sudo make install
Asegrese de que la variable extension_dir este apuntando a la ubicacin de mongo.so. El build se mostrar donde se encuetre instalado el controlador de PHP, la salida ser algo similar a esto:
Installing '/usr/lib/php/extensions/no-debug-zts-20060613/mongo.so'
Si no es as, cambia extension_dir en php.ini o mueva mongo.so Para cargar la extensin en el arranque de PHP, agregar una lnea:
extension=mongo.so
OS X
Si su sistema no puede encontrar autoconf, necesitas instalar Xcode (disponible en el DVD de instalacin). Si usa XAMPP, debe compilar el driver con el siguiente comando:
sudo /Applications/XAMPP/xamppfiles/bin/pecl install mongo
Si usa MAMP ( o XAMPP y el comando anterior no funciona), los binarios precompilados estn disponibles en Github (descargue la ltima versin con "osx" junto con el nombre que corresponda a la versin de PHP). Extraer mongo.so desde el fichero y aadalo al directorio de extensiones de MAMP o XAMPP. Agregar
extension=mongo.so
Gentoo
Gentoo tiene un paquete para el driver de PHP que se llama dev-php5/mongo que puede ser instalado con:
$ sudo emerge -va dev-php5/mongo
Si se utiliza PECL, quiz obtiene un error de versin incorrecta en libtool. Compile desde las fuentes que necesite y ejecute aclocal y autoconf. Driver nativo MongoDB 3
$ phpize && aclocal && autoconf && ./configure && make && make install
Red Hat
Incluye Fedora y CentOS En estos sistemas, la configuracin por omisin de Apache no permite a las peticiones establecer conexiones de red, haciendo que el driver genere errores de "Permiso denegado" cuando se intenta conectar a la base de datos. Si este fuera el caso, pruebe a ejecutar:
$ /usr/sbin/setsebool -P httpd_can_network_connect 1
Instalacin en Windows
Los binarios precompilados para cada versin estn disponibles en Github para una gran variedad de combinaciones de versiones, seguridad en hilos, y bibliotecas VC. Descomprima el fichero y copie php_mongo.dll en el directorio de extensiones de PHP ("ext" por omisin). El ltimo (no publicado) cdigo se compila en archivos binarios en Windows en cada commit. El fichero zip cuenta los ficheros php_mongo.dll y version.txt. Por favor mantega el fichero version.txt de modo que si presenta una pregunta o problema, pueda proporcionar a los desarrolladores la versin exacta en uso. (El nmero es largo y sin sentido, pero tendr sentido para los desarrolladores) Para obtener las ltimas correcciones (y posiblemente errores), descargue el binario correspondiente a la versin instalada de PHP:
PHP 5.2 VC6 Non-Thread-Safe Mongo extension PHP 5.2 VC6 Thread-Safe Mongo extension PHP 5.3 VC6 Non-Thread-Safe Mongo extension PHP 5.3 VC6 Thread-Safe Mongo extension PHP 5.3 VC8 Non-Thread-Safe Mongo extension PHP 5.3 VC8 Thread-Safe Mongo extension PHP 5.3 VC9 Non-Thread-Safe Mongo extension PHP 5.3 VC9 Thread-Safe Mongo extension Agregar la siguiente lnea al fichero php.ini:
extension=php_mongo.dll
Un gran nmero de personas han creado excelentes tutoriales de instalacin de controlador de PHP.
PHP 5.3.1 con Xdebug, MongoDB y Lithium en Ubuntu 9.10 / Apache 2.2 Un excelente video que te llevar paso a paso en la instalacin de Apache, PHP, Xdebug, MongoDB, y Lithium por Jon Adams. Instalando MongoDB y el controlador de PHP en Ubuntu 9.04 Artculo en castellano por Javier Aranda ( Traduccin en ingls ). OS X: Instalando MongoDB y el controlador de PHP Por Matt Butcher.
Tutorial Introduccin
Gracias al driver de PHP para MongoDB de 10gen. Cdigo de ejemplo para conectar, insertar documentos, consultar documentos, recorrer el resultado de una consulta, y desconectar de MongoDB. Encontrar ms detalles en cada uno de los pasos del siguiente tutorial.
<?php // conectar $m = new Mongo(); // seleccionar una base de datos $db = $m->comedy; // seleccionar una coleccin (equivalente a una tabla en una base de datos relacional) $collection = $db->cartoons; // aadir un registro $obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" ); $collection->insert($obj); // aadir un nuevo registro, con un distinto "perfil" $obj = array( "title" => "XKCD", "online" => true ); $collection->insert($obj); // encontrar todo lo que haya en la coleccin $cursor = $collection->find(); // recorrer el resultado foreach ($cursor as $obj) { echo $obj["title"] . "\n"; } ?>
No es necesario desconectar explcitamente de la base de datos. Cuando $connection queda fuera de mbito, la conexin se cierra automticamente y todos sus recursos se liberan.
Ver tambin
El captulo connecting cubre los distintos tipos de conexiones. Tanto la documentacin de la API de la clase Mongo como Mongo::__construct() proporcionan un exhaustivo repaso a todas las opciones disponibles, y un gran nmero de ejemplos.
La base de datos no debe necesariamente haber sido ya creada, sino que pueden crearse con slo seleccionarlas. Tenga cuidado con los errores tipogrficos! Podra, por inadvertencia, crear una nueva base de datos, provocando errores:
<?php $db = $connection->mybiglongdbname; // hacemos algo $db = $connection->mybiglongdbname; // ahora estamos conectando a una nueva base de datos! ?>
Ver Tambin
La documentacin API de la clase MongoDB contiene ms informacin sobre los objetos de bases de datos.
Las colecciones son anlogos a las tablas (para aqullos que estn familiarizados con bases de datos relacionales).
Ver Tambin
La documentacin API de la clase MongoCollection contiene ms informacin sobre objetos de colecciones.
Insertando un Documento
Los objetos bsicos para almacenar en una coleccin de una base de datos son los arrays asociativos. Un "documento" cualquiera podra ser:
<?php $doc = array( "nombre" => "MongoDB", "tipo" => "database", "contador" => 1, "info" => (object)array( "x" => 203, "y" => 102), "versiones" => array("0.9.7", "0.9.8", "0.9.9") ); ?>
Tenga en cuenta que puede tener array y objetos anidados. Para insertar este documento, utilice MongoCollection::insert():
<?php $collection->insert( $doc );
?>
Ver Tambin
La documentacin API de MongoCollection::insert() contiene ms informacin sobre la insercin de datos.
Mostrar:
array(6) { ["_id"]=> object(MongoId)#8 (1) { ["$id"]=> string(24) "4e2995576803fab768000000" } ["nombre"] string(7) "MongoDB" ["tipo"]=> string(8) "database" ["contador"]=> int(1) ["info"]=> array(2) { ["x"]=> int(203) ["y"]=> int(102) } ["versiones"]=> array(3) { [0]=> string(5) "0.9.7" [1]=> string(5) "0.9.8" [2]=> string(5) "0.9.9" } }
Hay un campo _id que se ha aadido automticamente al documento. _id es el campo de Driver nativo MongoDB 8
la "clave primaria". Si el documento no especifica una, el driver la aadir automticamente. Si se ha especificado un campo _id, debe ser nico en toda la coleccin. Por ejemplo:
<?php $db->foo->insert(array("_id" => 1), array("safe" => true)); // esto emitir una excepcin $db->foo->insert(array("_id" => 1), array("safe" => true)); // aqu no habra problemas, ya que es otra coleccin $db->bar->insert(array("_id" => 1), array("safe" => true)); ?>
Tenga en cuenta que estas inserciones proporcionan un segundo array: array("safe" => true). Este campo especifica las opciones de insercin. Por omisin, el driver no espera para escribir a que la base de datos responda, por lo que el driver no capturara el _id. Como se ha especificado una escritura "safe" (segura), el driver esperar la respuesta de la base de datos y ver que la escritura no se ha llevado a cabo. En general, todas las escrituras deben usar la opcin "safe" (en los ejemplos anteriores se ha omitido para simplificarlos).
Ver Tambin
MongoCollection::findOne() contiene ms informacin sobre cmo localizar datos. MongoId ofrece ms detalles de los identificadores nicos. La seccin writes trata las escrituras seguras en mayor profundidad, as como las funciones de escritura como MongoCollection::insert(), MongoCollection::update(), o MongoCollection::remove().
Tenga en cuenta que podemos insertar en una misma coleccin arrays con conjuntos de claves diferente. A esta caracterstica nos refereemos cuando decimos que MongoDB es independiente de esquemas.
y mostrar los 101 documentos de la coleccin. $id es el campo _id del documento (transformado a string) y $value es el documento en s.
Ver Tambin
La documentacin API de MongoCollection::find() contiene ms informacin sobre cmo localizar datos.
10
lo cual mostrara los documentos en que i > 50. Podemos tambin consultar un rango, digamos 20 < i <= 30:
<?php $query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) ); $cursor = $coll->find( $query ); while( $cursor->hasNext() ) { var_dump( $cursor->getNext() ); } ?>
Recuerde escapar siempre el smbolo $ o utilizar comillas simples. Si no, PHP lo interpretar como la variable $gt.
Creando un ndice
MongoDB soporta ndices, y es muy fcil aadirlos a una coleccin. Para crear un ndice, debe indicar el nombre del campo y la direccin: ascendente (1) o descendente (-1). A continuacin, creamos un ndice ascendente en el campo "i":
<?php
11
$coll->ensureIndex( array( "i" => 1 ) ); // creamos un ndice en "i" $coll->ensureIndex( array( "i" => -1, "j" => 1 ) ); // ndice de "i" descendente, "j" ascendente ?>
A medida que los datos crecen, la indexacin se vuelve crtica para un buen rendimiento de lectura. Si no est familiarizado con las indexaciones, revise la documentacin de MongoCollection::ensureIndex() y l a documentacin de indexacin de MongoDB.
Sentencia SQL
Sentencia en el Lenguaje de Consulta Mongo Implcito, o utilice MongoDB::createCollection(). $db->users->insert(array("a" => 1, "b" => 1)); $db->users->find(array(), array("a" => 1, "b" => 1)); $db->users->find(array("age" => 33));
SELECT a,b FROM users WHERE age=33 $db->users->find(array("age" => 33), array("a" => 1, "b" => 1)); SELECT a,b FROM users WHERE age=33 $db->users->find(array("age" => 33), array("a" => 1, "b" => 1)); SELECT a,b FROM users WHERE age=33 $db->users->find(array("age" => 33), ORDER BY name array("a" => 1, "b" => 1))->sort(array("name" => 1)); SELECT * FROM users WHERE age>33 $db->users->find(array("age" => array('$gt' => 33))); $db->users->find(array("age" => array('$lt' => 33)));
SELECT * FROM users WHERE name LIKE $db->users->find(array("name" => new "%Joe%" MongoRegex("/Joe/")));
12
SELECT * FROM users WHERE name LIKE $db->users->find(array("name" => new "Joe%" MongoRegex("/^Joe/"))); SELECT * FROM users WHERE age>33 AND age<=40 SELECT * FROM users ORDER BY name DESC CREATE INDEX myindexname ON users(name) CREATE INDEX myindexname ON users(name,ts DESC) SELECT * FROM users WHERE a=1 and b='q' SELECT * FROM users LIMIT 10 SKIP 20 $db->users->find(array("age" => array('$gt' => 33, '$lte' => 40))); $db->users->find()->sort(array("name" => -1)); $db->users->ensureIndex(array("name" => 1)); $db->users->ensureIndex(array("name" => 1, "ts" => -1)); $db->users->find(array("a" => 1, "b" => "q")); $db->users->find()->limit(10)->skip(20);
SELECT * FROM users WHERE a=1 or b=2 $db->users->find(array('$or' => array(array("a" => 1), array("b" => 2)))); SELECT * FROM users LIMIT 1 EXPLAIN SELECT * FROM users WHERE z=3 $db->users->find()->limit(1); $db->users->find(array("z" => 3))->explain()
SELECT DISTINCT last_name FROM users $db->command(array("distinct" => "users", "key" => "last_name")); SELECT COUNT(*y) FROM users SELECT COUNT(*y) FROM users where AGE > 30 SELECT COUNT(AGE) from users $db->users->count(); $db->users->find(array("age" => array('$gt' => 30)))->count(); $db->users->find(array("age" => array('$exists' => true)))->count(); $db->users->update(array("b" => "q"), array('$set' => array("a" => 1))); $db->users->update(array("b" => "q"), array('$inc => array("a" => 2))); $db->users->remove(array("z" => "abc"));
Conexin
Driver nativo MongoDB 13
La Conexin a MongoDB es tan fcil como usar new Mongo, pero hay muchas ms opciones y configuraciones adicionales. La pgina Mongo::__construct() cubre todas las opciones del API, pero est pgina ofrece ms detalles y consejos para casos de uso prcticos.
Acceso a la conexin
Si MongoDB se inicia con la opcin --auth, las conexiones deben ser autenticadas antes de ser usadas. Se puede hacer a nivel de cada base de datos con MongoDB::authenticate():
<?php $m = new Mongo(); $db = $m->admin; $db->authenticate($username, $password); ?>
Hay una gran desventaja al usar este mtodo: si la conexin a la base de datos se cae y luego se reconecta, la conexin ya no estar autentificada. Si se utiliza la forma de conexin mediante cadena, como se describe en Mongo::__construct(), la base de datos se autentificar al conectarse y se autentificar de nuevo si la conexin se cae y se restablece. Hace lo mismo que el cdigo anterior, a excepcin que las reconexiones a la base de datos sern automticamente autentificadas:
<?php $m = new Mongo("mongodb://${username}:${password}@localhost"); ?>
Por omisin, el controlador autentificar al usuario en la base de datos. Para autentificarse con diferentes base de datos, se especifica el nombre de la base de datos despus del host. Este ejemplo iniciar la sesin al usuario en la base de datos "blog":
<?php $m = new Mongo("mongodb://${username}:${password}@localhost/blog"); ?>
Grupos replica
Para conectarse a un grupo rplica, se debe especificar uno o ms miembros del grupo usando la opcin replicaSet.
<?php
14
Se require la versin 1.0.9+ del driver para conectar a un grupo rplica (versiones anteriores del driver no auto-detectarn el master o no se reconectarn correctamente). El driver de PHP har una peticin a los servidor(es) de base de datos listados para descubrir cual es el master. Mientras se pueda conectar almenos a uno de los servidores listados y pueda encontrar el master, la conexin se establecer con xito. Si no se puede realizar una conexin a ninguno de los servidores listados o no puede encontrar el master, MongoConnectionException devolver una excepcin. Si el master no se encuentra disponible, los slaves no promocionarn un nuevo master por algunos segundos. Durante ese tiempo, el controlador no podr realizar ninguna operacin en la base de datos (excepto las conexiones a los slaves que seguirn disponibles para operaciones de lectura) Por lo tanto, si se intenta hacer cualquier tipo de consulta de lectura o escritura mientras esto suceda, se devolver una excepcin. Una vez el master es elegido, al realizar una lectura o escritura el driver detectar cual es el nuevo master. Establecer la conexin como como primaria y continuar operando normalmente. Para obtener ms informacin acerca de grupos replica, consulte la documentacin del ncleo.
Connexiones persistentes
Crear una nueva conexin cada vez a la base de datos es muy lento. Para minimizar el nmero de conexiones que se necesite, se pueden usar las conexiones persistentes. Una conexin persistente es guardada por PHP, para que pueda usarse la misma conexin en mltiples peticiones. Por ejemplo, este simple programa para conectarse 1000 veces a la base de datos:
<?php for ($i=0; $i<1000; $i++) { $m = new Mongo(); } ?>
Esto tarda aprximadamente 18 segundos en ejecutarse. Pero si lo cambiamos para que utilice una conexin persistente:
<?php for ($i=0; $i<1000; $i++) { $m = new Mongo("localhost:27017", array("persist" => "x")); }
15
?>
...tardar menos de 0.02 segundos en ejecutarse, ya que solo se realiza una sola conexin a la base de datos. Las conexiones persistentes necesitan indicarse usando la variable de identificacin (tal y como se muestra "x" en el ejemplo anterior). Para que la conexin persistente pueda usarse, el hostname, puerto, variable persist y el usuario y contrasea (si es necesario) debe coincidir con una conexin persistente ya existente. De lo contrario, se crear una nueva conexin los datos proporcionados. Las conexiones persistentes son altamente recomendables y se deberan usar siempre en produccin a no ser que exista una razn con fundamento para hacer lo contrario. La mayora de razones por las cuales no son recomendadas para bases de datos relacionales son totalmente irrelevantes para MongoDB. Las conexiones persistentes sern el tipo de conexin por omisin en 1.0.12. Para crear conexiones no persistentes, se deber pasar "persist" => false a Mongo::__construct().
Si se quiere utilizar autenticacin en la conexin (tal y como se indica ms arriba) usando un fichero socket, se debe especificar el puerto 0 para que el analizador de la cadena de conexin sepa donde acaba la cadena de conexin.
<?php $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); ?>
tenido o no xito. Existen varias razones para que una escritura falle: si hay problemas de red, si el servidor de bases de datos se cae, o simplemente que la escritura era invlida (p.ej., escribir en una coleccin del sistema). Para obtener una respuesta de la base de datos, utilice la opcin safe, disponible en todos los tipos de escritura. Esta opcin se asegura de que la base de datos realiza la escritura antes de notificar del xito. Si la escritura falla, emitir una excepcin MongoCursorException(), explicando la razn del fallo. Durante la etapa de desarrollo, deben usarse siempre escrituras seguras (para prevenir errores involuntarios, como errores de claves duplicadas y similares). En el entorno de produccin, pueden usarse escrituras no seguras sobre datos "no importantes". Los datos no importantes dependen de la aplicacin, pero se suele tratar de datos automticos (en lugar de datos generados por el usuario), como un contador de clics o las coordenadas GPS, donde se puede obtener miles de registros por segundo. Para llevar a cabo escrituras seguras sin que ello suponga un impacto en el rendimiento, se recomienda realizar la escritura segura al finalizar una serie de escrituras. Por ejemplo:
$collection->insert($someDoc); $collection->update($criteria, $newObj); $collection->insert($somethingElse); $collection->remove($something, array("safe" => true));
De este modo, si la ltima escritura lanza una excepcin, sabr que hay un problema con la base de datos. Hay ms opciones disponible para asegurar la seguridad de las escrituras. Puede especificarse "fsync" => true para forzar a la base de datos a fsync (sincronizar) todas las escrituras en disco realizadas hasta ahora (por omisin, MongoDB sincroniza en disco las escrituras una vez por minuto). La forma ms segura de realizar una escritura consiste en usar rplicas y en especificar el nmero de servidores en que se harn las escrituras antes de obtener el xito. (En produccin siempre deben usarse rplicas, revise la seccin de Conexin para ms informacin sobre conjuntos de rplicas.)
$collection->insert($someDoc, array("safe" => 3));
Si indica "safe" => N, el servidor MongoDB se asegurar de que al menos N servidores tienen una copia de la escritura antes de notificar el xito. De modo que, si N es 3, el maestro y al menos 2 esclavos deben haber realizado las escrituras.
17
{ "author" : "Mike", "comment" : "I think that blah blah blah...", }, { "author" : "John", "comment" : "I disagree." } ] }
Para cambiar un campo interno, usamos $set (de manera que el resto de campos no se eliminen) con el ndice del comentario a cambiar:
<?php $blog->update($criteria, array('$set' => array("comments.1" => array("author" => "Jim")))); ?>
El Operador Posicional
El operador posicional $es til a la hora de actualizar objetos en arrays. En el ejemplo anterior, por ejemplo, podramos no conocer el ndice del comentario que necesitamos modificar, slo sabemos que queremos cambiar "John" a "Jim". Podemos usar $para lograrlo.
<?php $blog->update( array("comments.author" => "John"), array('$set' => array('comments.$.author' => "Jim"))); ?>
Por omisin, el driver enviar todas las consultas al maestro. Si se habilita la opcin "slaveOkay", el driver enviar todas las consultas a un servidor no primario, siempre y Driver nativo MongoDB 18
cuando fuera posible. La opcin "slaveOkay" puede habilitarse a cualquier "nivel": conexin, base de datos, coleccin, y cursor. Cada clase hereda el ajuste "slaveOkay" de su clase superior, de modo que si hiciramos:
<?php $db->setSlaveOkay(true); $c = $db->myCollection; $cursor = $c->find(); ?>
la consulta se ejecutara contra un esclavo (la coleccin hereda "slaveOkay" de la base de datos y el cursor lo hereda de la coleccin).
Tenga en cuenta que se debe realiza una consulta antes de elegir un esclavo: los esclavos se eligen de forma tarda por el driver. Mongo::getSlave() devolver NULL hasta que se utilice un esclavo. Puede consultarse el estado actual del conjunto de miembros que ve el servidor ejecutando Mongo::getHosts(). Si no pudiera leerse ningun servidor no primario, el driver enviara la lectura al primario (incluso con "slaveOkay" habilitado). Un servidor se considera legible si su estado es 2 (SECONDARY) y su salud es 1. Puede comprobarse esto con Mongo::getHosts(). Driver nativo MongoDB 19
Si disfruta tocando botones que probablemente no debera tocar, puede solicitar al driver un nuevo esclavo usando Mongo::switchSlave(). Esto escogera un nuevo esclavo (si hubiera alguno disponible), pero no debera usarse salvo que se sepa bien qu se est haciendo.
Notas aleatorias
Las escrituras siempre se envian al primario. Los comandos de la base de datos, incluso los comandos de slo lectura, tambin se envan siempre al primario. La salud y estado de un esclavo se comprueba cada 5 secundos o al realizarse la siguiente operacin antes de que venzan los 5 segundos. Tambin se volver a comprobar la configuracin cuando el driver tenga problemas accediendo a algn servidor. Tenga en cuenta que un servidor no primario podra encontrarse detrs de un primario en las operaciones, por lo que su software deber tolerar datos "desfasados" (o si no tendr que usar w en todas las escrituras).
Salvo que se indique lo contrario, el campo _id ser de tipo MongoId. El error ms frecuente consiste en usar una cadena de texto que concuerde con un MongoId. Debe tenerse presente que son dos tipos de datos distintos, y no concuerdan, del mismo modo que el texto "array()" no es lo mismo que un array vaco. Por ejemplo:
<?php $person = array("name" => "joe"); $people->insert($person); // convertimos el _id a texto $pid = $person['_id'] . "";
20
Arrays
Los arrays son especiales por varias razones. En primer lugar, hay dos tipos de arrays que MongoDB utiliza: arrays "normales" y arrays asociativos. Los arrays asociativos pueden tener cualquier combinacin de claves y valores. Los arrays "normales" se definen como arrays con un ndice numrico ascendente que comienza por 0 y se incrementa en uno por cada elemento. Estos son, normalmente, los arrays de PHP ms comunes. Por ejemplo, si se quisiera guardar una lista de premios en un documento, podramos poner:
<?php $collection->save(array("awards" => array("gold", "silver", "bronze"))); ?>
Las consultas pueden llegar hasta los arrays en busca de elementos. Supongamos que queremos encontrar todos los documentos que contienen un elemento de un array con un determinado valor. Por ejemplo, documentos con un premio "gold", como por ejemplo:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : ["gold", "silver", "bronze"]}
Esto puede lograrse con una nica consulta, ignorando el hecho de que "awards" es un array:
<?php $cursor = $collection->find(array("awards" => "gold")); ?>
Supongamos que estamos consultando un objeto ms complejo, si cada elemento del array fuera un objeto en s mismo, como en:
{ "_id" : ObjectId("4b06c282edb87a281e09dad9"), "awards" : [ { "first place" : "gold" }, { "second place" : "silver" }, { "third place" : "bronze" }
21
] }
Incluso aqu, ignorando que se trata de un array, podemos usar la misma notacin para consultar al subobjeto:
<?php $cursor = $collection->find(array("awards.first place" => "gold")); ?>
Debe tenerse en cuenta que no importa que haya espacios en los nombres de campos (pese a que sea mejor no usarlos, slo por mantenerlo ms legible). Puede tambin usarse un array para consultar un determinado nmero de posibles valores. Por ejemplo, si buscramos documentos "gold" o "copper", podramos hacer:
<?php $cursor = $collection->find(array("awards" => array('$in' => array("gold", "copper")))); ?>
Actualizaciones
Las actualizaciones quizs sean las operaciones ms complicadas de las disponibles en MongoDB. Combinan una consulta junto con una accin, modificando los documentos que concuerdan con los criterios de seleccin. Son tambin muy potentes, permitiendo cambiar rpidamente los documentos y reemplazarlos. Se realiza al momento (siempre y cuando sea posible), minimizando el consumo de recursos.
22
Las actualizaciones de reemplazado modifican todo el documento seleccionado por otro nuevo. Generalmente no es tan eficientes como usar operandos $, pero pueden ser muy tiles en operaciones complejas o en actualizaciones que no se pueden expresar en trminos de operandos $. Por ejemplo, una actualizacin de reemplazado puede cambiar por completo la estructura de un documento.
/** supongamos un documento as: * {"username" : "...", "password" : "...", "email" : "..."} */ $coll->update(array("username" => "joe"), array("userId" => 12345, "info" => array( "name" => "joe", "twitter" => "@joe4153", "email" => "..."), "likes" => array())); /** ahora el documento quedara as: * { * "userId" : 12345, * "info" : { * "name" : "joe", * "twitter" : "@joe4153", * "email" : "..." * }, * "likes" : [] * } */
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")))); ?>
23
El Operador Posicional
El operador posicional $es til a la hora de actualizar objetos en arrays. En el ejemplo anterior, por ejemplo, podramos no conocer el ndice del comentario que necesitamos modificar, slo sabemos que queremos cambiar "John" a "Jim". Podemos usar $para lograrlo.
<?php $blog->update( array("comments.author" => "John"), array('$set' => array('comments.$.author' => "Jim"))); ?>
Opciones en php.ini
El comportamiento de estas funciones se ve afectado por la configuracin de php.ini.
Opciones de configuracin Mongo Nombre mongo.native_long mongo.long_as_object mongo.default_host mongo.default_port mongo.auto_reconnect mongo.allow_persistent mongo.chunk_size mongo.cmd mongo.utf8 mongo.allow_empty_keys Por defecto false * false "localhost" 27017 true true 262144 "$" "1" false Cambiable PHP_INI_ALL PHP_INI_ALL PHP_INI_ALL PHP_INI_ALL PHP_INI_SYSTEM PHP_INI_SYSTEM PHP_INI_SYSTEM PHP_INI_ALL PHP_INI_ALL PHP_INI_ALL
Para mayor detalles y definiciones de los modos de PHP_INI_*, vea Dónde realizar un ajuste de configuración. He aqu una breve explicacin de las directivas de configuracin.
24
mongo.native-long
int Este valor por omisin cambiar a TRUE en 2.0.0, por lo que deber asegurarse al establecer el valor deseado (probablemente TRUE ) de manera que el comportamiento del driver no se vea afectado al actualizar. En plataformas de 64 bits, el ajuste mongo.native_long permite almacenar enteros de 64 bits en MongoDB. Si no se habilitara, slo se podrn almacenar enteros de 32 bits. El tipo de dato MongoDB usado en este caso es el BSON LONG, en lugar del BSON INT, que es el que funciona cuando se deshabilita este ajuste. Este ajuste tambin cambia el modo en que los BSON LONG se comportan cuando se consultan en MongoDB. Cuando mongo.native_long no est habilitado, el driver convierte todos los BSON LONG al tipo double de PHP, por lo que podra provocar prdida de precisin. En plataformas de 32 bits, el ajuste mongo.native_log no tiene efecto al almacenar enteros en MongoDB: los enteros se almacenan como BSON INT. Sin embargo, cuando este ajuste est habilitado y se consulta un BSON LONG en MongDB, se emitir una excepcin MongoCursorException alertando de que no se puede evitar la prdida de precisin en la lectura. Se recomienda que, en sistemas de 32 bits, adems de esto se habilite mongo.long_as_object. string Devuelve eun BSON_LONG como una instancia de MongoInt64 (en lugar de usar el tipo primitivo). string Nombre de host por omisin en caso de que no se especifique en el constructor. string Puerto TCP por omisin al conectar al servidor de bases de datos en caso de que no se especifique ningn puerto. El puerto por omisin es 27017. bool Indica si se debe reconectar o no a la base de datos al perder la conexin. bool Indica si se permiten o no conexiones persistentes. int Nmero de bytes por bloque. Se usa al fragmentar ficheros GridFS. Este valor debe ser al menos 100 veces menor que 4 megabytes (mx: 4194204) y se recomienda que sea incluso menor.
mongo.long_as_object
mongo.default_host
mongo.default_port
mongo.auto_reconnect
mongo.allow_persistent
mongo.chunk_size
mongo.cmd
string Carcter que se utiliza en lugar de $ en los modificadores y comparaciones. En vista de que es fcil olvidar escapar el carcter "$", puede elegirse cualquier otro en su lugar. Escoja un carcter que no aparezca en sus nombres de clave, como por ejemplo ":":
mongo.cmd = ":"
Puede cambiarse tambin en tiempo de ejecucin usando ini_set("mongo.cmd", ":"). Driver nativo MongoDB 25
Por supuesto, tambin pueden usarse comillas simples o la barra \ para escapar el carcter $.
mongo.utf8
int Indica si se debe lanzar una excepcin con textos que no sean UTF8. Hasta la versin 1.0.4, el driver de PHP ignoraba las cadenas no UTF8, incluso cuando no se esperaba que se fueran a insertar. Desde 1.0.4, el driver emite una MongoException. Para facilitar la transicion en las aplicaciones que insertan textos no UTF8, puede deshabiltiarse esta opcin, emulando el comportamiento anterior en que no se emitan excepciones. Sin embargo, esta opcin ser eliminada en la versin 1.1.0, de manera que siempre se emitirn excepciones en textos no UTF8. int Aadido en la versin 1.0.11. Indica si se permiten un texto vaco ("") como nombre de claves. Por omisin, el driver emitir una excepcin al proporcionar un texto vaco como clave en la base de datos. Es muy fcil pasar esto por alto al usar comillas dobles con operandos $, por lo que se recomienda dejar el valor por omisin. Sin embargo, si fuera necesario almacenar claves vacas, puede asignarse true a esta opcin, de manera que el driver permita usar un texto vaco a la base de datos.
mongo.allow_empty_keys
26
Para ms informacin sobre ataques tipo inyeccin SQL con MongoDB revise la documentacin principal.
Nota MapReduce ignora el campo scope de MongoCode, pero hay una opcin scope disponible en el comando que puede utilizarse en su lugar.
Por ejemplo, supongamos que tenemos un cdigo JavaScript para saludar a los usuarios en los registros de la base de datos. Podramos:
<?php // no haga esto! $username = $_POST['username']; $db->execute("print('Hola, $username!');"); ?>
Ahora MongoDB ejecuta el cdigo JavaScript "print('Hola, '); db.users.drop(); print('!');". Este ataque es fcil de evitar: utilice scope al pasar variables de PHP a Javascript:
<?php $scope = array("user" => $username); $db->execute(new MongoCode("print('Hello, '+user+'!');", $scope)); ?>
Esto aade la variable user al mbito de JavaScript. Si ahora alguien quisiera aadir cdigo malicioso, MongoDB imprimira, sin causar daos, Hello, '); db.dropDatabase(); print('!. Driver nativo MongoDB 27
El uso de scope ayuda a prevenir que se ejecutene en la base de datos entradas maliciosas. Sin embargo, debe asegurarse de que su cdigo no cambie y ejecute los datos de entrada. Por ejemplo, nunca utilice la funcin eval de JavaScript con los datos de entrada de un usuario:
<?php // no haga esto! // $jsShellInput es "db.users.drop();" $scope = array("input" => $jsShellInput); $db->execute(new MongoCode("eval(input);", $scope)); ?>
Use siempre scope y nunca permita que la base de datos ejecute como cdigo los datos de entrada del usuario.
Solucin a problemas
En caso de que tuviera problemas, existe un gran nmero de recursos que consultar.
IRC El canal IRC oficial de MongoDB es irc.freenode.net/#mongodb. ste es el mtodo mas rpido para conseguir ayuda... siempre y cuando haya gente conectada. Listas de correo La lista de correo de MongoDB es un buen (y por lo general rpido) mtodo para encontrar respuestas. Seguimiento de fallos Ha encontrado un fallo? Echa algo en falta? Tiene alguna pregunta? Archvela en el bug track del driver de PHP. Puede habilitar la depuracin verbosa compilando el driver con el flag de depuracin.
$ ./configure CFLAGS=-DDEBUG
DEBUG habilita todas las depuraciones. Se pueden habilitar tambin flags de depuracin especficos. En el ltimo cdigo fuente, los flags disponibles son: DEBUG_CONN Depuracin de conexiones.
TEst PHPUnit
Para ejecutarlos, debe descargar el driver de Github (los test se encuentran en el Driver nativo MongoDB 28
directorio tests/ ). Tambin necesitar PHPUnit para ejecutar los test. PHPUnit tambin se puede instalar mediante PEAR (hay un par de prerrequisitos que podr consultar en las instrucciones de instalacin). Algunos test esperarn que se produzcan alertas y errores, por lo que se debe asignar error_reporting en php.ini a E_STRICT | E_ALL para que pasen estos test. En caso contrario, se obtendrn errores que indicaran que el test esperaba que se emitiera una alerta o error. Para ejecutarlos, asegrese de que el servidor de MongoDB se est ejecutando en local en el puerto 27017. Antes de notificar de un error, por favor, asegrese de que ha ejecutado los test contra la ltima versin de desarrollo de MongoDB: a veces hay errores para funcionalidades que ya no se encuentran en la versin estable. La suite de pruebas usa la base de datos "phpunite". En caso de que utilice en su aplicacin una base de datos llamada "phpunit", asegrese de indicar a MongoDB un nuevo directorio de datos antes de ejecutar los test. Asegrese de que se encuentra en el directorio principal del cdigo fuente del driver que descarg de Github. Ejecute:
$ phpunit tests/MongoSuite.php
Tests C
Los test en C comprueban sobre todo funciones internas que no estn expuertas a PHP. Si deseara ejecutar estos test, deber compilar PHP con la bandera --enable-embed. Despus, acceda al directorio tests y ejecute make. Se crear un binario llamado unit. Llame a unit para ejecutar los test. Estos test no necesitan ninguna base de datos para funcionar. Cuando se pase un test, se imprimir un ".". Si un test falla, se informar y se dentrn las pruebas. Por favor, notifique cualquier error. Si make no pudiera localizar su biblioteca empotrada PHP (libphp5.so) o los ficheros de cabeceras, deber especificar un valor en la variable PHP_PATH. Ejecute make clean todos los objetos usados para los tests. Si ejecuta estos test con valgrind, no debera obtener ningn error de acceso no vlido a memoria, ni tampoco el mensaje de "no leaks are possible" que se muestra al final.
Notificando Errores
Por favor, notifique cualquier fallo o error en el bugtracker. Podra haber test que se omitan. Esto es normal, por lo que puede ignorarlo. Los nuevos test siempre son bienvenidos! Por favor, no dude en contribuir con nuevos test de cualquier tipo que pongan a prueba cualquier funcionalidad.
29
30
La clase Mongo
Introduccin
Conexin entre PHP y MongoDB. Esta clase se utiliza para crear y administrar conexiones. Un uso tpico es:
<?php $m = new Mongo(); // conectar $db = $m->foo; // obtener la base de datos con nombre "foo" ?>
Consulte Mongo::__construct() y la seccin connecting para ms informacin sobre cmo establecer conexiones.
Clases sinopsis
Mongo
Mongo { /* Constantes */ const string Mongo::VERSION; const string Mongo::DEFAULT_HOST = "localhost"; const int Mongo::DEFAULT_PORT = 27017; /* Fields */ public boolean connected = FALSE; public string status = NULL; protected string server = NULL; protected boolean persistent = NULL; /* Mtodos */
31
public bool Mongo::close ( void ) public bool Mongo::connect ( void ) protected bool Mongo::connectUtil ( void ) Mongo::__construct ( [ string $server = "mongodb://localhost:27017" [, array $ options = array("connect" => TRUE ) ] ] ) public array Mongo::dropDB ( mixed $db ) public MongoDB Mongo::__get ( string $dbname ) public array Mongo::getHosts ( void ) public static int Mongo::getPoolSize ( void ) public string Mongo::getSlave ( void ) public bool Mongo::getSlaveOkay ( void ) public array Mongo::listDBs ( void ) public array Mongo::poolDebug ( void ) public MongoCollection Mongo::selectCollection ( string $db, string $collection ) public MongoDB Mongo::selectDB ( string $name ) public static bool Mongo::setPoolSize ( int $size ) public bool Mongo::setSlaveOkay ( [ bool $ok = true ] ) public string Mongo::switchSlave ( void ) public string Mongo::__toString ( void ) }
32
Fields
status Si se trata de una conexin persistente, si la conexin se ha creado para este objeto, o si est siendo reutilizada. Si no se trata de una conexin persistente, este campo debe estar a NULL.
Ver tambin
Documentacin de MongoDB sobre conexiones.
33
Mongo::close
Mongo::close -- Cierra la conexin
Descripcin
public bool Mongo::close ( void ) Salvo en circunstancias excepcionales, no es necesario invocar a este mtodo. Cuando la instancia de Mongo quede fuera de mbito, el driver cerrar la conexin con la base de datos automticamente. En caso de que los objetos no salgan de mbito entre las peticiones, quizs se deee invocar a este mtodo al final de la ejecucin para eliminar todas las conexiones residuales. Sin embargo, es probable que sea ms eficiente utilizar una conexin persistente, que crear automticamente una conexin cuando sea necesaria y la utilizara para tntas peticiones como fuera posible. Si se est conectado a un conjunto de rplicas, close() slo cerrar la conexin a la primaria.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Indica si la conexin se cerr o no con xito.
34
Mongo::connect
Mongo::connect -- Conecta a un servidor de bases de datos
Descripcin
public bool Mongo::connect ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Indica si la conexin tuvo xito.
Errores/Excepciones
Lanza MongoConnectionException si falla la conexin a la base de datos.
35
Mongo::connectUtil
Mongo::connectUtil -- Conecta con un servidor de bases de datos
Descripcin
protected bool Mongo::connectUtil ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Indica si la conexin tuvo xito.
Errores/Excepciones
Emite MongoConnectionException si falla la conexin a la base de datos.
36
Mongo::__construct
Mongo::__construct -- Crear un nuevo objeto de conexin a base de datos
Descripcin
Mongo::__construct ( [ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE ) ] ] ) Si no se pasa ningn parmetro, conecta a "localhost:27017" (o lo que se indicara en php.ini en mongo.default_host y en mongo.default_port ).
server debe tener la forma: mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
La cadena de conexin siempre comienza con mongodb://, para indicar que es una cadena de conexin de esta forma. Si se especifica username y password, el constructor autenticar la conexin con la base de datos antes de devolver el control. Son parmetros opcionales, y si se especifican, deben estar seguidos por una @. Al menos debe proporcionarse un host (el puerto es opcional, por omisin es 27017) y se puede conectar a tantos como se desee. Los nombres de host se separan por comas, y el constructor notificar xito si al menos se conecta a uno de ellos. Si no se pudo conectar a ninguno, emitir una excepcin MongoConnectionException. Finalmente, si se especific usuario y contrasea, se puede especificar tambin la base de datos contra la que se autentica. Si db no se especifica, se utilizar "admin".
Parmetros
server
Array con las opciones de conexin. Las opciones disponibles actualmente son: "connect" Si el constructor debe o no conectar antes de devolver el control. Por omisin, TRUE. "timeout" Tiempo mximo que esperar el driver para conectar a la base de datos (en milisegundos). "replicaSet" Nombre del conjunto de rplicas al que conectar. Si se indicara, se averiguar al maestro usando el comando de base de datos ismaster en cada semilla, de manera que el driver pudiera finalizar conectando a un servidor que ni siquiera estaba en la lista. Para ms detalles, revise el ejemplo de abajo sobre Driver nativo MongoDB 37
rplicas. "username" En lugar de incluirlo en la lista de host, se puede especificar aqu el nombre de usuario. Es til en caso de que un nombre de usuario incluya un ":". Esto reemplaza un nombre de usuario situado en la lista de host. "password" En lugar de incluirlo en la lista de host, se puede especificar aqu la contrasea. Es til en caso de que una contrasea incluya una "@". Esto reemplaza una contrasea establecida en la lista de hosts. "db" La base de datos para autenticarse se puede especificar aqu, en lugar de incluirlo en la lista de hosts. Esto reemplaza una base de datos dada en la lista de hosts.
Valores devueltos
Devuelve un nuevo objeto de conexin a base de datos.
Errores/Excepciones
Emite MongoConnectionException si intentara conectar a la base de datos en todos hosts proporcionados, y fallara. Tambin emitir MongoConnnectionException si el nombre de usuario o contrasea fueran invlidos. Revise la documentacin de MongoConnectionException para conocer las excepciones y sus causas.
Historial de cambios
Versin 1.2.0
Descripcin
Eliminada la opcin de persistencia, ya que ahora todas las conexiones lo son. Se puede seguir usando, pero no tendr ningn efecto.
"persist"
Si la conexin debe o no ser presistente. Si se habilita, la conexin lo ser. Su representacin en forma de string se usa como id de la conexin, de modo que dos instancias de Mongo que se inicialicen con array("persist" => "foobar") compartirn la misma conexin, mientras que una instancia inicializada con array("persist" => "barbaz") usar una conexin a base de datos diferente.
38
Ahora el parmetro "replicaSet" espera un strings, y no un booleano (aunque todava se aceptara un booleano).
1.0.2
Cambiado el constructor para que acepte un array de opciones. Antes de 1.0.2, el constructor tena los siguientes parmetros:
server
Nombre de servidor.
connect
Parmetro booleano opcional para especificar si el constructor debe o no conectar a la base de datos antes de devolver el control. Por omisin, TRUE.
persistent
1.0.9 1.2.0
Ejemplos
Ejemplo #1 - Ejemplo de conjunto de rplicas con Mongo::__construct() Este ejemplo muestra cmo conectar el driver a un conjunto de rplicas. Asume que hay un conjunto de tres servidores: sf1.example.com, sf2.example.com, y ny1.example.com. El maestro puede ser cualquiera de ellos.
<?php // lista de nombes de servidores separadas por comas $m1 = new Mongo("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet")); // slo es necesaria una semilla, y el driver obtendr la lista completa y encontrar // al maestro de esta semilla $m2 = new Mongo("mongodb://ny1.example.com", array("replicaSet" => "myReplSet")); ?>
39
Si el maestro falla, el driver averiguar qu servidor secundario se convierte en el nuevo maestro y comenzar a usar automticamente la conexin. La recuperacin automtica no funcionar correctametne si no se especificara replicaSet. Al menos debe haber una semilla funcionando de la lista de semillas para que el driver se conecte al conjunto de rplicas. Si se incluyen semillas de dos juegos de replicas separados, el comporamiento ser inesperado. Para ms informacin, revise la documentation sobre conjuntos de rplicas.
Ejemplo #2 - Conectando a un socket de dominio En la versin 1.0.9 o superior, se puede usar un socket de dominio UNIX para conectar a una instancia de MongoDB local. Es ligeramente ms rpido que una conexin de red. En la versin 1.5.0, el servidor MongoDB abre automticamente un socket en /tmp/mongodb-<port>.sock. Puede coenctarse a l especificando la ruta en la cadena de conexin:
<?php // Servidor MongoDB funcionando en local en el puerto 20000 $m = new Mongo("mongodb:///tmp/mongodb-20000.sock"); ?>
Ejemplo #3 - Ejemplo de autenticacin con Mongo::__construct() El usuario debe existir en la base de datos admin antes de intentar autenticarlo. Puede crearse uno con la consola de Mongo ejecutando:
> use admin switched to db admin > db.addUser("testUser", "testPass"); { "_id" : ObjectId("4b21272fd9ab21611d19095c"), "user" : "testUser", "pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59" }
40
>
Tras crear un usuario con, en este caso, el nombre "testUser" y la contrasea "testPass", puede crearse una conexin autenticada:
<?php $m = new Mongo("mongodb://testUser:testPass@localhost"); ?>
41
Mongo::dropDB
Mongo::dropDB -- Drops a database [deprecated]
Descripcin
public array Mongo::dropDB ( mixed $db )
Parmetros
db
The database to drop. Can be a MongoDB object or the name of the database.
Valores devueltos
Returns the database response.
42
Mongo::__get
Mongo::__get -- Gets a database
Descripcin
public MongoDB Mongo::__get ( string $dbname ) This is the cleanest way of getting a database. If the database name has any special characters, Mongo::selectDB() will need to be used. However, in most cases, this should be sufficient.
<?php $mongo = new Mongo(); // the following two lines are equivalent $db = $mongo->selectDB("foo"); $db = $mongo->foo; ?>
Parmetros
dbname
Valores devueltos
Returns a new db object.
Errores/Excepciones
Throws a generic exception if the database name is invalid.
43
Mongo::getHosts
Mongo::getHosts -- Updates status for all hosts associated with this
Descripcin
public array Mongo::getHosts ( void ) This method can only be used with a connection to a replica set. It returns the status of all of the hosts in the set. See the query section of this manual for information on distributing reads to slaves.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns an array of information about the hosts in the set. Includes each host's hostname, its health (1 is healthy), its state (1 is primary, 2 is secondary, 0 is anything else), the amount of time it took to ping the server, and when the last ping occurred. For example, on a three-member replica set, it might look something like:
array(2) { ["A:27017"]=> array(4) { ["health"]=> int(1) ["state"]=> int(2) ["ping"]=> int(369) ["lastPing"]=> int(1309470644) } ["B:27017"]=> array(4) { ["health"]=> int(1) ["state"]=> int(1) ["ping"]=> int(139) ["lastPing"]=> int(1309470644) } ["C:27017"]=> array(4) { ["health"]=> int(1) ["state"]=> int(2)
44
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.
45
Mongo::getPoolSize
Mongo::getPoolSize -- Get pool size for connection pools
Descripcin
public static int Mongo::getPoolSize ( void )
Advertencia This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::getSize() instead.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns the current pool size.
Ejemplos
Ejemplo #1 - Changing pool size This returns the default pool size, sets a new pool size, then prints the new pool size and the pool debugging information. Note that changing the pool size only affects new connection pools, it does not change old ones.
<?php $connection = new Mongo("host1"); // pool size is -1 echo "pool size is: ".Mongo::getPoolSize()."\n"; echo "setting pool size to 200\n"; Mongo::setPoolSize(200); // pool size is 200 echo "pool size is: ".Mongo::getPoolSize()."\n"; $conn2 = new Mongo("host2"); // remaining for host1 is -2 // remaining for host2 is 199 var_dump(Mongo::poolDebug());
46
?>
Ver tambin
47
Mongo::getSlave
Mongo::getSlave -- Returns the address being used by this for slaveOkay reads
Descripcin
public string Mongo::getSlave ( void ) This finds the address of the slave currently being used for reads. It is a read-only method: it does not change anything about the internal state of the object. When you create a connection to the database, the driver will not immediately decide on a slave to use. Thus, after you connect, this function will return NULL even if there are slaves available. When you first do a query with slaveOkay set, at that point the driver will choose a slave for this connection. At that point, this function will return the chosen slave. See the query section of this manual for information on distributing reads to slaves.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
The address of the slave this connection is using for reads. This returns NULL if this is not connected to a replica set or not yet initialized.
48
Mongo::getSlaveOkay
Mongo::getSlaveOkay -- Consultar el valor slaveOkay de esta conexin
Descripcin
public bool Mongo::getSlaveOkay ( void ) Revise la seccin de consultas de este manual para saber cmo distribuir lecturas a esclavos.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el valor de slaveOkay de esta instancia.
49
Mongo::listDBs
Enumera todas las bases de datos disponibles
Descripcin
public array Mongo::listDBs ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve un array asociativo de tres campos. El primero es databases, que a su vez contiene otro array. Cada elemento del array es un array asociativo que se corresponde con una base de datos, ofreciendo el nombre de la base de datos, tamao y si est o no vaca. Los otros dos campos son totalSize (tamao total en bytes) y ok, que ser 1 cuando este mtodo se ejecute con xito.
Ejemplos
Ejemplo #1 - Ejemplo de Mongo::listDBs Ejemplo que muestra cmo usar listDB y la estructura de datos devuelta.
<?php $mongo = new Mongo(); $dbs = $mongo->listDBs(); print_r($dbs); ?>
50
Mongo::poolDebug
Mongo::poolDebug -- Returns information about all connection pools.
Descripcin
public array Mongo::poolDebug ( void )
Advertencia This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::info() instead.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Each connection pool has an identifier, which starts with the host. For each pool, this function shows the following fields:
in use
The number of connections 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.
51
Descripcin
public MongoCollection Mongo::selectCollection ( string $db, string $collection )
Parmetros
db
Nombre de la coleccin.
Valores devueltos
Devuelve un nuevo objeto de coleccin.
Errores/Excepciones
Emite InvalidArgumentException si el nombre de la base de datos o de la coleccin fuera invlido.
Ejemplos
Ejemplo #1 - Ejemplo de Mongo::selectCollection()
<?php $m = new Mongo(); $c1 = $m->selectCollection("foo", "bar.baz"); // lo cual es equivalente a $c2 = $m->selectDB("foo")->selectCollection("bar.baz"); // $c1 y $c2 representan la misma conexin ?>
52
Mongo::selectDB
Mongo::selectDB -- Obtener una base de datos
Descripcin
public MongoDB Mongo::selectDB ( string $name )
Parmetros
name
Valores devueltos
Devuelve un nuevo objeto de base de datos.
Errores/Excepciones
Emite InvalidArgumentException si el nombre de la base de datos no es vlido.
53
Mongo::setPoolSize
Mongo::setPoolSize -- Set the size for future connection pools.
Descripcin
public static bool Mongo::setPoolSize ( int $size )
Advertencia This feature has been DEPRECATED as of version 1.2.3. Relying on this feature is highly discouraged. Please use MongoPool::setSize() instead.
Sets the max number of connections new pools will be able to create.
Parmetros
size
The max number of connections future pools will be able to create. Negative numbers mean that the pool will spawn an infinite number of connections.
Valores devueltos
Returns the former value of pool size.
Ejemplos
Ejemplo #1 - Mongo::setPoolSize() example If you set the pool size to n and then create n connections, attempting to create an n+1 st connection will throw a MongoConnectionException.
<?php // only allow one connection to a server Mongo::setPoolSize(1); // creates one connection to localhost:27017 $m1 = new Mongo(); // attempt to create a second connection to localhost:27017 // only one connection is allowed, so this will throw an exception $m2 = new Mongo();
54
?>
Ver tambin
55
Mongo::setSlaveOkay
Mongo::setSlaveOkay -- Cambia el ajuste de slaveOkay de esta conexin
Descripcin
public bool Mongo::setSlaveOkay ( [ bool $ok = true ] ) Revise la seccin de consultas de este manual para conocer cmo distribuir lecturas entre esclavos.
Parmetros
ok
Indica si las lecturas deben o no enviarse a los miembros secundarios del conjunto de rplicas, para todas aquellas consultas que se realicen con esta instancia de Mongo.
Valores devueltos
Devuelve el valor anterior de slaveOkay que tena esta instancia.
56
Mongo::switchSlave
Mongo::switchSlave -- Elije un nuevo esclavo para lecturas slaveOkay
Descripcin
public string Mongo::switchSlave ( void ) Elije un esclavo aleatoriamente para crear una conexin de lectura. Se invoca automticamente por el driver por lo que no se debe necesitar hacerlo a mano. Realiza una llamada a Mongo::getHosts() (para recargar el estado de los hosts) y a Mongo::getSlave() (para obtener el valor devuelto). Revise la seccin de consultas de este manual para obtener ms informacin sobre lescturas distribuidas en esclavos.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
La direccin del esclavo que est usando esta conexi para realizar lecturas. Podra ser la misma que la anterior, ya que se eligen aleatoriamente. Si slo hubiera un secundario (o slo el primario) nicamente se devolvera una direccin. Por ejemplo, si tuviramos un conjunto de rplicas de tres miembros, con un primario, secundario, y un rbitro, este mtodo siempre devolvera la direccin del secundario. Si ste no estvuiera disponible, este mtodo devolvera la direccin del primario. Si ste tampoco estuviera disponible, se emitira una excepcin, ya que un rbitro no puede realizar operaciones de lectura.
Errores/Excepciones
Si se le llama desde una conexin sin conjuntos de rplicas, emite MongoException (cdigo de error 15). Tambin emite MongoException si no pudiera encontrar ningn elemento (primario o secundario) del que leer (cdigo de error 16).
57
Mongo::__toString
Mongo::__toString -- Representacin en forma de texto de esta conexin
Descripcin
public string Mongo::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nombre de host y el puerto de esta conexin.
58
Clase MongoDB
Introduccin
Las instancias de esta clase se utilizan para interactuar con la base de datos. Para seleccionar una base de datos:
<?php $m = new Mongo(); // conectar $db = $m->selectDB("ejemplo"); ?>
Los nombres de bases de datos pueden utilizar prcticamente cualquier carcter del rango ASCII. Sin embargo no pueden contener ni " ", "." ni un texto vaco. El nombre "system" tambin est reservado. Hay algunos nombres poco usuales de bases de datos que s son vlidos: "null", "[x,y]", "3", "\"", "/". A diferencia de los nombres de colecciones, los nombres bases de datos pueden contener "$".
Clases sinopsis
MongoDB
MongoDB { /* Constantes */ const int MongoDB::PROFILING_OFF = 0; const int MongoDB::PROFILING_SLOW = 1; const int MongoDB::PROFILING_ON = 2; /* Campos */ public integer w = 1; public integer wtimeout = 10000; /* Mtodos */
59
public array MongoDB::authenticate ( string $username, string $password ) public array MongoDB::command ( array $command ) MongoDB::__construct ( Mongo $conn, string $name ) public MongoCollection MongoDB::createCollection ( string $name [, bool $capped = FALSE [, int $size = 0 [, int $max = 0 ] ] ] ) public array MongoDB::createDBRef ( string $collection, mixed $a ) public array MongoDB::drop ( void ) public array MongoDB::dropCollection ( mixed $coll ) public array MongoDB::execute ( mixed $code [, array $args = array() ] ) public bool MongoDB::forceError ( void ) public MongoCollection MongoDB::__get ( string $name ) public array MongoDB::getDBRef ( array $ref ) public MongoGridFS MongoDB::getGridFS ( [ string $prefix = "fs" ] ) public int MongoDB::getProfilingLevel ( void ) public bool MongoDB::getSlaveOkay ( void ) public array MongoDB::lastError ( void ) public array MongoDB::listCollections ( void ) public array MongoDB::prevError ( void ) public array MongoDB::repair ( [ bool $preserve_cloned_files = FALSE [, bool $ backup_original_files = FALSE ] ] ) public array MongoDB::resetError ( void ) public MongoCollection MongoDB::selectCollection ( string $name ) public int MongoDB::setProfilingLevel ( int $level ) public bool MongoDB::setSlaveOkay ( [ bool $ok = true ] ) public string MongoDB::__toString ( void ) }
Constantes predefinidas
Driver nativo MongoDB 60
Campos
w1 Nmero de servidores en los que replicar los cambios antes de retornar xito. Se hereda por las instancias de MongoCollection que deriven de este objeto. w slo est disponible en versiones 1.5.1+ del servidor MongoDB y 1.0.8+ del driver. w se usa cada vez que se realiza una operacin "segura" ( MongoCollection::insert(), MongoCollection::update(), MongoCollection::remove(), MongoCollection::save(), y MongoCollection::ensureIndex() soportan la opcin segura). Con el valor por omisin (1), una operacin segura devolver el control cuando el servidor de bases de datos obtenga la operacin. Si el servidor se cayera antes de que la operacin se replicara a un esclavo, podra perderse la operacin de forma permanente. De esta forma, se puede especificar en w un valor superior a 1 para garantizar que al menos un esclavo ha recibido la operacin antes de que se considere que ha habido xito. Por ejemplo, si w fuera 2, tanto el servidor principal como un esclavo tendrn un registro de la operacin. Si no, el driver emitir una excepcin MongoCursorException. Puede ser tentador establecer en w el total de esclavos + maestro, pero entonces, si un esclavo se cayera, la operacin fallara y se emitira una excepcin, por lo que suele ser ms seguro establecer w=2 (maestro + 1 esclavo). wtimeout 10000 Nmero de milisegundos a esperar a que las rplicas de MongoDB::$w tengan lugar. Se hereda por las instancias de MongoCollection que deriven de este objeto. w slo est disponible en las versiones 1.5.1+ del servidor MongoDB y en las 1.0.8+ del driver. A no ser que se establezca un valor en wtimeout, el servidor esperar eternamente a que se replique a w servidores para finalizar. Por omisin el driver esperar 10 segundos. Puede modificarse este valor para alterar este comportamiento.
Ver tambin
Documentacin de MongoDB de bases de datos.
61
MongoDB::authenticate
MongoDB::authenticate -- Iniciar sesin en esta base de datos
Descripcin
public array MongoDB::authenticate ( string $username, string $password ) Este mtodo hace que esta conexin sea autenticada. Si el servidor de bases de datos tiene la autenticacin habilitada (de forma predeterminada, no lo est), deber iniciar sesin antes de poder hacer cualquier cosa. En general, deber se recomienda utilizar la autenticacin que incorpora Mongo::__construct() antes que este mtodo. Si se autentica sobre la conexin, y la conexin se cae y se reconecta durante la sesin, automticamente ser re-autenticado. Si se autentica manualmente usando este mtodo, y la conexin se cae, deber llamar a este mtodo de nuevo cuando la conexin vuelva. Este mtodo es equivalente a ejecutar:
<?php $salted = "${username}:mongo:${password}"; $hash = md5($salted); $nonce = $db->command(array("getnonce" => 1)); $saltedHash = md5($nonce["nonce"]."${username}${hash}"); $result = $db->command(array("authenticate" => 1, "user" => $username, "nonce" => $nonce["nonce"], "key" => $saltedHash )); ?>
Una vez que una conexin ha sido autenticada, slo puede ser des-autenticada mediante el comando de base de datos "logout":
<?php $db->command(array("logout" => 1)); ?>
Parmetros
username
Nombre de usuario.
62
password
Valores devueltos
Devuelve la respuesta de la base de datos. Si el inicio de sesin tuvo xito, devolver:
<?php array("ok" => 1); ?>
("auth fails" puede ser otro mensaje, dependiendo de la versin de la base de datos y de qu fuera mal).
Ver tambin
Documentacin de MongoDB sobre autenticacin.
63
MongoDB::command
MongoDB::command -- Ejecuta un comando de base de datos
Descripcin
public array MongoDB::command ( array $command ) Prcticamente todo lo que no son operaciones CRUD se puede realizar con un comando de base de datos. Necesita conocer la versin de la base de datos? Hay un comando para ello. Necesita hacer una agregacin? Hay un comando para ello. Necesia habilitar registros de mensajes? Se puede hacer una idea. Este mtodo es equivalente a:
<?php public function command($data) { return $this->selectCollection('$cmd')->findOne($data); } ?>
Parmetros
command
Historial de cambios
Versin 1.2.0
Valores devueltos
Devuelve la respuesta de la base de datos.
Ejemplos
64
Ejemplo #1 - Ejemplo de MongoDB::command() con "distinct" Localizando todos los valores distintos de una clave.
<?php $gente = $db->gente; $gente->insert(array("nombre" $gente->insert(array("nombre" $gente->insert(array("nombre" $gente->insert(array("nombre" => => => => "Joe", "edad" => 4)); "Sally", "edad" => 22)); "Dave", "edad" => 22)); "Molly", "edad" => 87));
$edades = $db->command(array("distinct" => "gente", "key" => "edad")); foreach ($edades['values'] as $edad) { echo "$edad\n"; } ?>
Ejemplo #2 - Ejemplo de MongoDB::command() con MapReduce Obtener todos los usuarios con al menos un evento "sale" (venta), y cuntas veces han tenido ventas cada uno de esos usuarios.
<?php // documento de eventos de ejemplo $events->insert(array("user_id" => $id, "type" => $type, "time" => new MongoDate(), "desc" => $description)); // construccin del mapa y funcin reductora $map = new MongoCode("function() { emit(this.user_id,1); }"); $reduce = new MongoCode("function(k, vals) { ". "var sum = 0;". "for (var i in vals) {". "sum += vals[i];". "}". "return sum; }"); $sales = $db->command(array( "mapreduce" => "events", "map" => $map, "reduce" => $reduce,
65
"query" => array("type" => "sale"), "out" => array("merge" => "eventCounts"))); $users = $db->selectCollection($sales['result'])->find(); foreach ($users as $user) { echo "Usuario {$user['_id']} tuvo {$user['value']} venta(s).\n"; } ?>
Nota Usando MongoCode Este ejemplo utiliza MongoCode, que puede utilizar tambin un argumento de mbito. Sin embargo, por el momento, MongoDB no soporta el uso de mbitos en MapReduce. Si deseara utilizar variables en el lado de cliente con las funciones MapReduce, puede aairlas al mbito global usando el campo opcional de mbito con el comando de la base de datos. Consulte la documentacin de MapReduce para ms informacin.
Nota El argumento out Antes de 1.8.0, el argumento out era opcional. Si no se iba a usar, los resultados de MapReduce se escriban a una coleccin temporal, que se eliminaba cuando se cerrara la conexin. A partir de la versin 1.8.0, el argumento out es obligatorio. Consulte la documentacin de MapReduce para ms informacin.
Si va a usar MapReduce, Prajwal Tuldhar ha creado una API para usuarios de Mongo PHP que ofrece una interfaz ms elegante que el comando 'al desnudo'. Puede descarlo desde Github y hay un art-culo de blog sobre cmo usarlo.
Ver tambin
Documentacin de MongoDB sobre comandos de base de datos y comando individuales: findAndModify, getLastError, y repair (existen muchos ms, stos son slo unos pocos ejemplos).
66
MongoDB::__construct
MongoDB::__construct -- Crea una nueva base de datos
Descripcin
MongoDB::__construct ( Mongo $conn, string $name ) Este mtodo no est hecho para ser llamado directamente. La forma recomendada de crear una instancia de MongoDB es mediante Mongo::__get() o mediante Mongo::selectDB(). Si va a ignorar el prrafo anterior y desea llamar directamente al constructor, puede hacerlo as:
<?php $m = new Mongo(); $db = new MongoDB($m, 'mydbname'); ?>
Parmetros
Mongo conn Conexin a la base de datos.
name
Valores devueltos
Devuelve la base de datos.
Errores/Excepciones
67
68
MongoDB::createCollection
MongoDB::createCollection -- Crea una coleccin
Descripcin
public MongoCollection MongoDB::createCollection ( string $name [, bool $capped = FALSE [, int $size = 0 [, int $max = 0 ] ] ] ) Este mtodo se usa para crear colecciones "capped" (de tamao fijo) y otras colecciones que requieren opciones especiales. Es idntico a ejecutar:
<?php $collection = $db->command(array("create" => $name, "size" => $size, "capped" => $capped, "max" => $max)); ?>
Parmetros
name
Nombre de la coleccin.
capped
Si la coleccin fuera de tamao fijo, aqu establecemos el nmero mximo de elementos que podr almacenar.
Valores devueltos
Devuelve un objeto de coleccin que representa la nueva coleccin.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::createCollection() para coleccin de tamao fijo Una coleccin "capped" es un tipo especial de coleccin que tiene un tamao fijo o un nmero fijo de elementos. Una vez que la coleccin est "llena", los elementos ms viejos se eliminan cada vez que aadimos nuevos. Estas colecciones pueden ser muy
69
tiles para usos como registro de mensajes, donde quizs se desee mantener una determinada cantidad de espacio para mensajes sin preocuparse por si crece demasiado. Este ejemplo crea una coleccin de mensajes de error muy pequea, que mantendr hasta 10 documentos.
<?php $log = $db->createCollection("logger", true, 10*1024, 10); for ($i = 0; $i < 100; $i++) { $log->insert(array("level" => WARN, "msg" => "mensaje de error #$i", "ts" => new MongoDate())); } $msgs = $log->find(); foreach ($msgs as $msg) { echo $msg['msg']."\n"; } ?>
70
MongoDB::createDBRef
MongoDB::createDBRef -- Crea una referencia a base de datos
Descripcin
public array MongoDB::createDBRef ( string $collection, mixed $a ) Este mtodo es una interfaz flexible que permite crear referencias a bases de datos (vea MongoDBRef ).
Parmetros
collection
Objeto o _id al que crear la referencia. Si se pasara un objeto o un array asociativo, se crear una referencia usando su campo _id.
Valores devueltos
Devuelve un array de referencia a base de datos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::createDBRef() Ejemplo que muestra cmo crear una referencia a base de datos a partir de un documento.
<?php $articulos = $db->articulos; $articulo = array( 'titulo' => 'Articulo de prueba', 'descripcion' => 'Descripcion de articulo de prueba' ); $articulos->insert($articulo); $ref = $db->createDBRef('articulos', $articulo); print_r($articulo); print_r($ref); ?>
Array ( [title] => Articulo de prueba [description] => Descripcion de articulo de prueba [_id] => MongoId Object ( ) ) Array ( [$ref] => articulos [$id] => MongoId Object ( ) )
Ahora, $ref puede ser almacenado en otro documento, y consultado ms adelante con MongoDB::getDBRef o con MongoCollection::getDBRef.
Ejemplo #2 - Ejemplo de MongoDB::createDBRef() Ejemplo que muestra cmo crear una referencia a base de datos a partir de un id.
<?php $id = new MongoId('47cc67093475061e3d9536d2'); $ref = $db->createDBRef('articulos', $id); ?>
72
MongoDB::drop
MongoDB::drop -- Borra esta base de datos
Descripcin
public array MongoDB::drop ( void ) Borra la base de datos que est en uso. Es equivalente a ejecutar:
<?php public function drop() { $this->command(array("dropDatabase" => 1)); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la respuesta de la base de datos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::drop() Este ejemplo muestra cmo borrar una base de datos mongo.
<?php $db = $mongo->foo; $response = $db->drop(); print_r($response); ?>
73
MongoDB::dropCollection
MongoDB::dropCollection -- Borra una coleccin [obsoleto]
Descripcin
public array MongoDB::dropCollection ( mixed $coll )
Advertencia Obsoleto Utilice en su lugar MongoCollection::drop(). Esta funcin tiene fugas de memoria en versiones 1.0.7 y anteriores!
Parmetros
coll
Valores devueltos
Devuelve la respuesta de la base de datos.
74
MongoDB::execute
MongoDB::execute -- Ejecuta cdigo JavaScript en el servidor de bases de datos
Descripcin
public array MongoDB::execute ( mixed $code [, array $args = array() ] ) El servidor de bases de datos de Mongo contiene un motor JavaScript. Este mtodo permite ejecutar cualquier cdigo JavaScript en la base de datos. Puede resultar til si se desea trabajar ligeramente sobre algunas colecciones, o procesar algunos resultados en el lado del servidor para reducir la cantidad de datos que se enviar al cliente. Al ejecutar JavaScript en la base de datos se hace un bloqueo de escrituras, lo cual significa que se bloquean otras operaciones. Asegrese de que tiene esto en consideracin antes de ejecutar scripts costosos. Este mtodo es una envoltura de un comando de base de datos. Bsicamente, sera:
<?php public function execute($code, $args) { return $this->command(array('$eval' => $code, args => $args)); } ?>
Si se tuviera una nica sentencia en una nica lnea, MongoDB devuelve un valor. Esto puede provocar comportamientos inesperados. Por ejemplo, el siguiente cdigo devuelvo "foo":
<?php $db->execute('"foo";'); ?>
Para evitar estos comportamientos, lo mejor es no dejar que MongoDB decida qu devolver, usando en su lugar una sentencia "return" explcita. Podramos cambiar los ejemplos superiores por lo siguiente:
<?php
75
Ahora, la primera sentencia devolver "foo" y la segunda devolver un contador de la coleccin "foo".
Parmetros
code
Valores devueltos
Devuelve el resultado de la evaluacin.
Ejemplos
Ejemplo #1 - Ejemplo sencillo de MongoDB::execute()
<?php $response = $db->execute("function() { return 'Hola, mundo!'; }"); echo $response['retval']; ?>
Ejemplo #2 - Ejemplo de parmetros en MongoDB::execute() Pasaremos a la funcin JavaScript valores del array del parmetro opcional.
<?php $response = $db->execute("function(despedida, nombre) { return despedida+', '+nombre+'!'; }", array("Hasta pronto", "Juan")); echo $response['retval'];
76
?>
Ejemplo #3 - Ejemplo de mbito Si en lugar de un string, usramos un MongoCode en el primer parmetro, podr pasarse un mbito en el cual se ejecutar JavaScript.
<?php $func = "function(despedida, nombre) { ". "return despedida+', '+nombre+', dice '+despedidor;". "}"; $scope = array("despedidor" => "Fran"); $code = new MongoCode($func, $scope); $response = $db->execute($code, array("Hasta pronto", "Juan")); echo $response['retval']; ?>
77
Descripcin
public bool MongoDB::forceError ( void ) Este mtodo no es muy til para el uso normal de MongoDB. Obliga a que se produzca un error de base de datos. Esto quiere decir que MongoDB::lastError() devolver un error de base de datos genrico despus de ejecutar este comando. Este comando es idntico a la ejecucin de:
<?php public function forceError() { return $this->command(array('forceerror' => 1)); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la respuesta de base de datos.
78
MongoDB::__get
MongoDB::__get -- Obtiene una coleccin
Descripcin
public MongoCollection MongoDB::__get ( string $name ) sta es la forma ms fcil de obtener uan coleccin a partir de un objeto de base de datos. Si el nombre de la coleccin contiene caracteres extraos, se usar en su lugar MongoDB::selectCollection().
<?php $mongo = new Mongo(); // las dos siguientes lneas son equivalentes $collection = $mongo->selectDB("foo")->selectCollection("bar"); $collection = $mongo->foo->bar; ?>
Parmetros
name
Nombre de la coleccin.
Valores devueltos
Devuelve la coleccin.
79
MongoDB::getDBRef
MongoDB::getDBRef -- Captura el documento que est siendo apuntado por una referencia de base de datos
Descripcin
public array MongoDB::getDBRef ( array $ref )
Parmetros
ref
Valores devueltos
Devuelve el documento apuntado por la referencia.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::getDBRef() Ejemplo que demuestra cmo obtener una referencia a una base de datos y cules son los datos de entrada esperados.
<?php $ref = array( '$ref' => 'profiles', '$id' => '47cc67093475061e3d9536d2' ); $profile = $db->getDBRef($ref); ?>
Revise MongoDB::createDBRef() para ms informacin sobre cmo crear referencias a bases de datos.
80
MongoDB::getGridFS
MongoDB::getGridFS -- Obtiene un objeto para trabajar con ficheros almacenados en esta base de datos
Descripcin
public MongoGridFS MongoDB::getGridFS ( [ string $prefix = "fs" ] )
Parmetros
prefix
Valores devueltos
Devuelve un nuevo objeto gridfs para esta base de datos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::getGridFS() Este ejemplo muestra cmo obtener una instancia de MongoGridFS.
<?php $db = $mongo->my_db; $prefix = 'files'; $collection = $db->getGridFS($prefix); ?>
Lea ms sobre MongoGridFS para aprender cmo almacenar ficheros con MongoDB.
81
MongoDB::getProfilingLevel
MongoDB::getProfilingLevel -- Obtiene el nivel de perfilado (profiling) de la base de datos
Descripcin
public int MongoDB::getProfilingLevel ( void ) Devuelve el nivel de perfilado actual de la base de datos. El perfilador de la base de datos rastrea el tiempo de ejecucin de consultas. Si se habilita (digamos, usando MongoDB::setProfilingLevel() o por consola), puede consultar cunta consultas tardan ms que un determinado nmero de milisegundos, o el tiempo que tardan toda las consultas. Tenga presente que el perfilado ralentiza las consultas. Por eso, es mejor utilizarlo en entornos de desarrollo o de pruebas antes que en aplicaciones donde el tiempo sea crucial. Esta funcin es equivalente a:
<?php public function getProfilingLevel() { return $this->command(array('profile' => -1)); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nivel de perfilado.
Ver tambin
Documentacin de MongoDB sobre profiling y MongoDB::setProfilingLevel().
82
MongoDB::getSlaveOkay
MongoDB::getSlaveOkay -- Devuelve el valor de slaveOkay de esta base de datos
Descripcin
public bool MongoDB::getSlaveOkay ( void ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el valor de slaveOkay para esta instancia.
83
MongoDB::lastError
MongoDB::lastError -- Comprueba si hubo un error en la ltima operacin de base de datos llevada a cabo
Descripcin
public array MongoDB::lastError ( void ) Este mtodo es equivalente a:
<?php public function lastError() { return $this->command(array('getlasterror' => 1)); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el error, si lo hubo.
Ejemplos
Ejemplo #1 - Ejemplo de error NULL de MongoDB::lastError()
<?php $db->resetError(); var_dump($db->lastError()); ?>
84
dup key: { : 1
85
MongoDB::listCollections
MongoDB::listCollections -- Devuelve la lista de colecciones de esta base de datos
Descripcin
public array MongoDB::listCollections ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve una lista de MongoCollections.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDB::listCollections() El siguiente ejemplo muestra cmo borrar cada una de las colecciones de la base de datos.
<?php $m = new Mongo(); $db = $m->selectDB("sample"); $list = $db->listCollections(); foreach ($list as $collection) { echo "borrando $collection... "; $collection->drop(); echo "se fue\n"; } ?>
86
MongoDB::prevError
MongoDB::prevError -- Comprueba el ltimo error emitido durante una operacin de base de datos
Descripcin
public array MongoDB::prevError ( void ) En general, se recomienda utilizar MongoDB::lastError() en lugar de este mtodo. Este mtodo devuelve el ltimo error de base de datos que tuvo lugar, y hace cuntas operaciones sucedi. Ha quedado prcticamente obsoleto.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el error y hace cuntas operaciones sucedi.
87
MongoDB::repair
MongoDB::repair -- Repara y compacta esta base de datos
Descripcin
public array MongoDB::repair ( [ bool $preserve_cloned_files = FALSE [, bool $ backup_original_files = FALSE ] ] ) Crea una nueva copia de todos los datos de la base de datos. Eliminar cualquier dato corrupto y la compactar y aumentar los trampos vacos que encuentre. Esta operacin es muy lenta en bases de datos extensas. Generalmente se ejecuta desde la consola o desde la lnea de comandos, y no por el driver. Es equivalente a la funcin:
<?php public function repair() { return $this->command(array('repairDatabase' => 1)); } ?>
Parmetros
preserve_cloned_files
Valores devueltos
Devuelve la respuesta de la base de datos.
Ver tambin
Documentacin de MongoDB sobre reparacin.
Ejemplos
88
Ejemplo #1 - Ejemplo de MongoDB::repair() Este ejemplo muestra cmo reparar y compactar una base de datos.
<?php $db = $mongo->foo; $response = $db->repair(); print_r($response); ?>
89
MongoDB::resetError
MongoDB::resetError -- Limpia cualquier error de la base de datos que se haya apuntado
Descripcin
public array MongoDB::resetError ( void ) Generalmente, este mtodo no se utiliza. Reinicia el seguimiento de errores de la base de datos (que puede ser incrementado con MongoDB::forceError(), que tampoco se utiliza normalmente). Es equivalente a ejecutar:
<?php public function resetError() { return $this->command(array('reseterror' => 1)); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la respuesta de la base de datos.
90
MongoDB::selectCollection
MongoDB::selectCollection -- Obtiene una coleccin
Descripcin
public MongoCollection MongoDB::selectCollection ( string $name )
Parmetros
name
Nombre de la coleccin.
Valores devueltos
Devuelve la coleccin.
91
MongoDB::setProfilingLevel
MongoDB::setProfilingLevel -- Establece el nivel de perfilado (profiling) de la base de datos
Descripcin
public int MongoDB::setProfilingLevel ( int $level ) Modifica el nivel actual de profiling de la base de datos. Esta funcin es equivalente a:
<?php public function setProfilingLevel($level) { return $this->command(array('profile' => $level)); } ?>
Las opciones de niveles son 0 (deshabilitado), 1 (consultas de ms de 100ms), y 2 (todas las consultas). Si se deseara perfilar tan slo las consultas que llevan ms que otro periodo de tiempo, utilice el comando de base de datos con un segundo parmetro: el nmero de milisegundos. Por ejemplo, para perfil todas las consultas que llevan ms de on segundo, ejecute:
<?php $result = $this->command(array('profile' => 1, 'slowms' => 1000)); ?>
Parmetros
level
Nivel de perfilado.
Valores devueltos
Devuelve el valor anterior del nivel de perfilado.
92
MongoDB::setSlaveOkay
MongoDB::setSlaveOkay -- Cambiar el valor de slaveOkay de esta base de datos
Descripcin
public bool MongoDB::setSlaveOkay ( [ bool $ok = true ] ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.
Parmetros
ok
Indica si las lecturas deben enviarse a miembros secundarios de un conjunto de rplicas para todas las posibles consultas que se realicen con esta instancia de MongoDB.
Valores devueltos
Devuelve el valor anterior de slaveOkay de esta instancia.
93
MongoDB::__toString
MongoDB::__toString -- Nombre de esta base de datos
Descripcin
public string MongoDB::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nombre de esta base de datos.
94
Clase MongoCollection
Introduccin
Representa una coleccin de base de datos. Los nombres de colecciones pueden usar cualquier carcter del cdigo ASCII. Algunos ejemplos de nombres vlidos de colecciones son "", "...", "mi coleccion", y "*&#@". Los nombres de colecciones definidos por usuario no pueden contener el smbolo $. Existen colecciones del sistema que utilizan $ en sus nombres (p.ej., local.oplog.$main), pero es un carcter reservado. Si se intentara crear y usar una coleccin que incluya $ en su nombre, MongoDB lo notificar.
Clases sinopsis
MongoCollection
MongoCollection { /* Constantes */ const int MongoCollection::ASCENDING = 1; const int MongoCollection::DESCENDING = -1; /* Campos */ public MongoDB db = NULL; public integer w; public integer wtimeout; /* Mtodos */ public mixed MongoCollection::batchInsert ( array $a [, array $options = array() ] ) public MongoCollection::__construct ( MongoDB $db, string $name ) public int MongoCollection::count ( [ array $query = array() [, int $limit = 0 [, int $ skip = 0 ] ] ] )
95
public array MongoCollection::createDBRef ( array $a ) public array MongoCollection::deleteIndex ( string|array $keys ) public array MongoCollection::deleteIndexes ( void ) public array MongoCollection::drop ( void ) public bool MongoCollection::ensureIndex ( array $keys [, array $options = array() ]) public MongoCursor MongoCollection::find ( [ array $query = array() [, array $ fields = array() ] ] ) public array MongoCollection::findOne ( [ array $query = array() [, array $fields = array() ] ] ) public MongoCollection MongoCollection::__get ( string $name ) public array MongoCollection::getDBRef ( array $ref ) public array MongoCollection::getIndexInfo ( void ) public string MongoCollection::getName ( void ) public bool MongoCollection::getSlaveOkay ( void ) public array MongoCollection::group ( mixed $keys, array $initial, MongoCode $ reduce [, array $options = array() ] ) public mixed MongoCollection::insert ( array $a [, array $options = array() ] ) public mixed MongoCollection::remove ( [ array $criteria = array() [, array $ options = array() ] ] ) public mixed MongoCollection::save ( array $a [, array $options = array() ] ) public bool MongoCollection::setSlaveOkay ( [ bool $ok = true ] ) public string MongoCollection::__toString ( void ) public bool MongoCollection::update ( array $criteria, array $newobj [, array $ options = array() ] ) public array MongoCollection::validate ( [ bool $scan_data = FALSE ] ) }
Constantes predefinidas
MongoCollection::ASCENDING 1 Sentido ascendente en ordenaciones y creaciones de ndices. Driver nativo MongoDB 96
Campos
db La base de datos "padre" de esta coleccin. w Nmero de servidores a los que replicar un cambio antes de confirmar xito. Este valor se hereda de la base de datos padre. La clase MongoDB indica de forma ms detallada cmo funciona w. wtimeout Nmero de milisegundos a esperar a que las operaciones se realicen en las $this->w rplicas. Este valor se hereda de la base de datos padre. La clase MongoDB indica de forma ms detallada cmo funciona wtimeout.
Ver tambin
Documentacin principal de MongoDB sobre collections.
97
MongoCollection::batchInsert
MongoCollection::batchInsert -- Inerta mltiples documentos en esta coleccin
Descripcin
public mixed MongoCollection::batchInsert ( array $a [, array $options = array() ] )
Parmetros
a
Array de arrays.
options
Opciones de insercin. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos, y en caso de que la insercin no tenga xito, emitir una excepcin de tipo MongoCursorException. Si safe fuera un entero, replicar la insercin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espra; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la insercin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una insercin segura (safe) y sobrescribir el ajuste safe a FALSE.
Valores devueltos
Si "safe" est habilitado, devuelve un array asociativo con el estado de las inserciones ("ok") y con cualquier error que pudiera haber sucedido ("err"). En cualquier otro caso, devuelve TRUE si la operacin por lotes se envi con xito, o FALSE en caso contrario.
Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" estuviera habilitada y la insercin fallara. Lanza MongoCursorTimeoutException si la opcin "safe" tuviera un valor mayor que uno, y la base de datos no pudiera replicar la operacin en MongoCollection::$wtimeout milisegundos.
Historial de cambios
98
Descripcin Aadido el parmetro "options". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync".
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::batchInsert() Las inserciones por lotes son una forma rpida de aadir muchos elementos a la base de datos
<?php $users = array(); for ($i = 0; $i<100; $i++) { $users[] = array('username' => 'user'.$i, 'i' => $i); } $mongo = new Mongo(); $collection = $mongo->my_db->users; $collection->drop(); $collection->batchInsert($users); foreach ($users as $user) { echo $user['_id']."\n"; // completado con instanceof MongoId } $users = $collection->find()->sort(array('i' => 1)); foreach ($users as $user) { var_dump($user['username']); } ?>
99
MongoCollection::__construct
MongoCollection::__construct -- Crea una nueva coleccin
Descripcin
public MongoCollection::__construct ( MongoDB $db, string $name )
Parmetros
MongoDB db Base de datos padre.
name
Valores devueltos
Devuelve un nuevo objeto de tipo coleccin.
Errores/Excepciones
Si el nombre no fuera vlido, emite una excepcin por defecto.
100
MongoCollection::count
MongoCollection::count -- Cuenta el nmero de documentos de esta coleccin
Descripcin
public int MongoCollection::count ( [ array $query = array() [, int $limit = 0 [, int $skip = 0]]])
Parmetros
query
Valores devueltos
Devuelve el nmero de documentos que coinciden con la consulta.
Historial de cambios
Versin 1.0.7
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)));
101
?>
102
MongoCollection::createDBRef
MongoCollection::createDBRef -- Crea una referencia a una base de datos
Descripcin
public array MongoCollection::createDBRef ( array $a )
Parmetros
a
Valores devueltos
Devuelve un array de referencia a base de datos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::createDBRef
<?php $canciones = $db->canciones; $listasDeReproduccion = $db->listasdereproduccion; // crea una referencia a una cancin $manamana = $songs->findOne(array('titulo' => 'Ma na ma na')); $refACancioin = $songs->createDBRef($manamana); // aade la referencia a mi lista de reproduccin $listasDeReproduccion->update(array('usuario' => 'yo'), array('$push' => array('listadecanciones' => $refToSong))); ?>
Ver tambin
MongoCollection::getDBRef
103
MongoCollection::deleteIndex
MongoCollection::deleteIndex -- Elimina un ndice de esta coleccin
Descripcin
public array MongoCollection::deleteIndex ( string|array $keys ) Este mtodo es identico a:
<?php public function deleteIndexes($keys) { // toIndexString es un mtodo 'protected' que convierte los strings, arrays, y objetos // en nombres de ndices $index = $this->toIndexString($keys); return $this->db->command(array("deleteIndexes" => $this->getName(), "index" => $index); } ?>
Cuando se crea un ndice, se le asigna un nombre nico. Generalmente, ser establecido por el usuario (con la opcin "name" de MongoCollection::ensureIndex() ) o generado por el driver a partir de una combinacin de nombres de clave y de direcciones. Usaremos despus este nombre con MongoCollection::deleteIndex() para eliminar el ndice. Desafortunadamente, el mtodo MongoCollection::ensureIndex() genera nombres ligeramente diferentes a los que crea la shell y, por motivos de retro-compatibilidad, MongoCollection::deleteIndex() no puede eliminar ndices con nombres creados a medida. Por esa reazn, la mejor forma de eliminar ndices creados por la shell o con nombres a medida, es llamar directamente al comando de la base de datos deleteIndexes. De esta forma, si se quisiera eliminar un ndice al que llamamos "superfast query", lo haramos as:
<?php $db->command(array("deleteIndexes" => $collection->getName(), "index" => "superfast query"); ?>
Para averiguar cmo se llama un ndice, puede consultar coleccin system.indexes de una base de datos y analizar el campo name (nombre).
Parmetros
keys
104
Valores devueltos
Devuelve la respuesta de la base de datos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::deleteIndex() Este ejemplo ilustra cmo pasar tanto un stringo como un array a la funcin.
<?php $m = new Mongo(); $c = $m->example->indices; // crea un ndice $c->ensureIndex(array("i"=>1)); // elimina un ndice $c->deleteIndex("i");
// crea un ndice multi-clave $c->ensureIndex(array("j" => 1, "k" => 1)); // elimina un ndice multi-clave $c->deleteIndex(array("j" => 1, "k" => 1)); ?>
105
MongoCollection::deleteIndexes
MongoCollection::deleteIndexes -- Elimina todos los ndices de esta coleccin
Descripcin
public array MongoCollection::deleteIndexes ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la respuesta de la base de datos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::deleteIndexes() Este ejemplo demuestra cmo eliminar todos los ndices de una coleccin, y muestra tambin la respuesta esperada.
<?php $collection = $mongo->my_db->articles; $response = $collection->deleteIndexes(); print_r($response); ?>
106
MongoCollection::drop
MongoCollection::drop -- Borra esta coleccin
Descripcin
public array MongoCollection::drop ( void ) Borra esta coleccin y elimina sus ndices.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la respuesta de la base de datos.
Ejemplos
Ejemplo #1 - MongoCollection::drop() example Este ejemplo demuestra cmo borrar una coleccin, y muestra tambin la respuesta esperada.
<?php $collection = $mongo->my_db->articles; $response = $collection->drop(); print_r($response); ?>
107
MongoCollection::ensureIndex
MongoCollection::ensureIndex -- Crea un ndice en el campo o cmapos dados, o si el ndice ya existe, no realiza nada.
Descripcin
public bool MongoCollection::ensureIndex ( array $keys [, array $options = array() ] ) No se puede crear un ndice nico sobre un campo si varios documentos ya existentes no contienen a este campo. En estos documentos el campo sera NULL y, por tanto, no sera nico.
Parmetros
keys
Este parmetro es un array asociativo de la forma array("nombredeopcion" => <boolean>, ...). Las opciones soportadas actualmente son: "unique" Crea un ndice nico. "dropDups" Si se estuviera creando un ndice nico, y existieran valores duplicados, borrar todos excepto uno de ellos. "background" Si se estuviera usando MongoDB versin 1.3.2 o superior, se podrn crear ndices de fondo mientras se realiza otras operaciones. Por omisin, la creacin de ndices sucede de forma sncrona. Si se especifica TRUE en esta opcin, la creacin de ndices ser asncrona. "safe" Desde la versin 1.0.4 del driver, se puede indicar mediante un booleano si se comprobar si ha habido o no xito creando el ndice. Si fallara la creacin del ndice, el driver emitira una excepcin de tipo MongoCursorException. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. "name" Desde la versin 1.0.4 del driver (SIN incluir 1.0.4) se puede especificar un nombre de ndice. Puede ser til cuando se indexan muchas claves y Mongo se queja de que los nombres de ndices son demasiado largos. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo
108
Valores devueltos
Devuelve TRUE.
Historial de cambios
Descripcin Aadida la opcin timeout. "safe" emitir fallos del maestro, cuando proceda. Se lanza MongoException si el nombre de ndice (generado o asignado) es superior a 128 bytes. Cambiado el parmetro "options" de booleano a array. Antes de 1.0.2, el segundo parmetro era un valor booleano opcional que especificaba un ndice nico.
1.0.11
1.0.2
Errores/Excepciones
Lanza MongoException si el nombre de ndice es superior a 128 bytes. (Versin 1.0.11+) Lanza MongoCursorException si la opcin "safe" est habilitada y falla la creacin del ndice. Lanza MongoCursorTimeoutException si la opcin "safe" est habilitada y la operacin lleva ms de MongoCursor::$timeout milisegundos para ser completada. Esto no paraliza la operacin en el servidor, es slo un lmite de tiempo en el lado del cliente.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::ensureIndex()
<?php $c = new MongoCollection($db, 'foo'); // crea un ndice en 'x' ascendente
109
$c->ensureIndex(array('x' => 1)); // crea un ndice en 'z' ascendente y en 'zz' descendente $c->ensureIndex(array('z' => 1, 'zz' => -1)); // crea un ndice nico en 'x' $c->ensureIndex(array('x' => 1), array("unique" => true)); ?>
Ejemplo #3 - Indexacin Geoespacial Mongo soporta ndices geoespaciales, que permiten buscar documentos cercanos a una determinada localizacin o que estn dentro de una determinada forma. Por ejemplo, para crear un ndice geoespacial en el campo "loc":
<?php $collection->ensureIndex(array("loc" => "2d")); ?>
Ver tambin
Driver nativo MongoDB 110
111
MongoCollection::find
MongoCollection::find -- Realiza una consulta a la coleccin
Descripcin
public MongoCursor MongoCollection::find ( [ array $query = array() [, array $fields = array() ] ] )
Parmetros
query
Valores devueltos
Devuelve un cursor para el resultado de la bsqueda.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::find() Este ejemplo muestra como buscar en un rango.
<?php // buscar documentos donde 5 < x < 20 $rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 )); $cursor = $collection->find($rangeQuery); ?>
Ejemplo #2 - Ejemplo de MongoCollection::find() usando $where Este ejemplo demuestra cmo buscar en una coleccin usando cdigo javascript para reducir el conjunto de resultados.
<?php
112
$coleccion = $db->mi_bd->articulos; $js = "function() { return this.type == 'paginadeinicio' || this.destacado == true; }"; $articulos = $coleccion->find(array('$where' => $js)); ?>
Ejemplo #3 - Ejemplo de MongoCollection::find() usando $in Este ejemplo demuestra cmo buscar una coleccin usando el operador $in.
<?php $coleccion = $db->mi_bd->articulos; $articulos = $coleccion->find(array( 'tipo' => array('$in' => array('paginadeinicio', 'editorial')) )); ?>
Ejemplo #4 - Obteniendo resultados en forma de array Devuelve un MongoCursor. A menudo, la gente que empiza, se siente ms cmoda usando arrays. Para convertir un cursor en un array, utilice la funcin iterator_to_array().
<?php $cursor = $coleccion->find(); $array = iterator_to_array($cursor); ?>
Al usar iterator_to_array() se fuerza a que el driver cargue todos los resultados en memoria. No lo use cuando el resultado supere el tamao mximo de memoria! Adems, algunas colecciones del sistema no tienen un campo _id. Si se est trabajando con colecciones que pudieran tener documentos sin _id s, establezca FALSE en el segundo argumento de iterator_to_array() (as, no tratar de usar como clave el valor del campo _id inexistente).
Ver tambin
Documentacin de MongoDB sobre find.
113
MongoCollection::findOne
MongoCollection::findOne -- Realiza una consulta a esta coleccin, devolviendo slo un elemento
Descripcin
public array MongoCollection::findOne ( [ array $query = array() [, array $fields = array() ] ] )
Parmetros
query
Valores devueltos
Devuelve el registro que coincide con la bsqueda, o NULL.
Errores/Excepciones
Si no se pudiera acceder a la base de datos, lanzara una excepcin de tipo MongoConnectionException.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::findOne buscando por id. Este ejemplo muestra cmo buscar un documento en una coleccin a partir de su id.
<?php $articulos = $mongo->mi_bd->articulos; $articulo = $articulos->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2'))); ?>
114
Ejemplo #2 - Ejemplo de MongoCollection::findOne a partir de una condicin. Este ejemplo muestra como buscar un documento en una coleccin a partir de una condicin, limitando los campos devueltos.
<?php $usuarios = $mongo->mi_bd->usuarios; $usuario = $usuarios->findOne(array('nombreusuario' => 'jwage'), array('password')); print_r($usuario); ?>
Fjese que, incluso si el documento no contiene un campo nombreusuario, hemos limitado los resultados para que nicamente contengan el campo password.
115
MongoCollection::__get
MongoCollection::__get -- Obtiene una coleccin
Descripcin
public MongoCollection MongoCollection::__get ( string $name ) Forma concisa de obtener una coleccin con un nombre separado por el carcter punto. Si el nombre de coleccin contuviera caracteres extraos, se debera utilizar en su lugar MongoDB::selectCollection().
<?php $mongo = new Mongo(); // las dos siguientes sentencias son equivalentes $collection = $mongo->selectDB("foo")->selectCollection("bar.baz"); $collection = $mongo->foo->bar->baz; ?>
Parmetros
name
Valores devueltos
Devuelve la coleccin.
116
MongoCollection::getDBRef
MongoCollection::getDBRef -- Captura el documento al que apunta una referencia de base de datos
Descripcin
public array MongoCollection::getDBRef ( array $ref )
Parmetros
ref
Valores devueltos
Devuelve el documente de base de datos al que apunta esta referencia.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::getDBRef
<?php $listasdereproduccion = $db->listasdereproduccion; $miLista = $listasdereproduccion->findOne(array('usuario' => 'yo')); // capturar cada cancin de la lista de reproduccin foreach ($miLista['listacancion'] as $refCancion) { $cancion = $listasdereproduccion->getDBRef($refCancion); echo $cancion['titulo'] . "\n"; } ?>
En el ejemplo anterior cada $refCancion ser similar a lo siguiente: Array ( [$ref] => canciones [$id] => 49902cde5162504500b45c2c )
117
Ver tambin
MongoCollection::createDBRef
118
MongoCollection::getIndexInfo
MongoCollection::getIndexInfo -- Devuelve un array con los nombres de ndices de esta coleccin
Descripcin
public array MongoCollection::getIndexInfo ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve una lista de nombres de ndices.
119
MongoCollection::getName
MongoCollection::getName -- Devuelve el nombre de esta coleccin
Descripcin
public string MongoCollection::getName ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nombre de esta coleccin.
Ejemplos
120
MongoCollection::getSlaveOkay
MongoCollection::getSlaveOkay -- Consulta el valor de slaveOkay de esta coleccin
Descripcin
public bool MongoCollection::getSlaveOkay ( void ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el valor de slaveOkay para esta instancia.
121
MongoCollection::group
MongoCollection::group -- Lleva a cabo una operacin similar al comando GROUP BY de SQL
Descripcin
public array MongoCollection::group ( mixed $keys, array $initial, MongoCode $ reduce [, array $options = array() ] )
Parmetros
keys
Campos a agrupar. Si se pasa un array o un objeto que no es de cdigo, ser la clave usada para agrupar resultados. 1.0.4+: Si keys es una instancia de MongoCode, keys ser tratado como una funcin que devuelve la clave con la que agrupar (revise el ejemplo de abajo sobre "Pasando una funcin a keys ").
initial
Una funcin que toma dos argumentos (el documento actual y la agregacin en este punto) y realiza la agregacin.
options
Parmetros opcionales para el comando group. Las opciones vlidas incluyen: "condition" Condicin para incluir un documento a la agregacin. "finalize" Funcin que se invoca por cada clave nica que toma la salida de la funcin reduce.
Valores devueltos
Devuelve un array que contiene el resultado.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::group() Agrupa los documentos por categora y crea una lista de los nombres que hay dentro de la categora.
<?php
122
$collection->insert(array("categoria" $collection->insert(array("categoria" $collection->insert(array("categoria" $collection->insert(array("categoria" $collection->insert(array("categoria" $keys = array("categoria" => 1); $initial = array("items" => array());
"fruta", "nombre" => "manzana")); "fruta", "nombre" => "melocoton")); "fruta", "nombre" => "platano")); "verdura", "nombre" => "maiz")); "verdura", "nombre" => "brocoli"));
$reduce = "function (obj, prev) { prev.items.push(obj.nombre); }"; $g = $collection->group($keys, $initial, $reduce); echo json_encode($g['retval']); ?>
Ejemplo #2 - Ejemplo de MongoCollection::group() Este ejemplo no utiliza ninguna clave, por lo que cada documento ser su propio grupo. Adems, usa una condicin: slo los documentos que la cumplan, sern procesados por la funcin de agrupacin.
<?php $collection->save(array("a" => 2)); $collection->save(array("b" => 5)); $collection->save(array("a" => 1)); // usar todos los campos $claves = array(); // establecer valores iniciales $inicial = array("count" => 0); // funcin JavaScript a realizar $reduce = "function (obj, prev) { prev.count++; }"; // usar slo los documentos donde el campo "a" es mayor que 1 $condicion = array("a" => array( '$gt' => 1)); $g = $collection->group($claves, $inicial, $reduce, $condicion); var_dump($g); ?>
123
array(4) { ["retval"]=> array(1) { [0]=> array(1) { ["count"]=> float(1) } } ["count"]=> float(1) ["claves"]=> int(1) ["ok"]=> float(1) }
Ejemplo #3 - Pasando una funcin a keys Si se desea agrupar por algo distinto a un nombre de campo, se puede pasar una funcin como primer parmetro de MongoCollection::group() y se ejecutar con cada documento. Se usar el valor devuelto de la funcin como valor de agrupacin. Este ejemplo demuestra cmo agrupar por el campo num mdulo 4 (num % 4).
<?php $c->group(new MongoCode('function(doc) { return {mod : doc.num % 4}; }'), array("count" => 0), new MongoCode('function(current, total) { total.count++; }')); ?>
124
MongoCollection::insert
MongoCollection::insert -- Inserta un array en la coleccin
Descripcin
public mixed MongoCollection::insert ( array $a [, array $options = array() ] ) Todas las cadenas de texto que se enven a la base de datos deben estar en UTF-8. Si un string no estuviera en UTF-8, se lanzara una excepcin MongoException. Para insertar (o para consultar) un texto que no sea UTF-8, utilice MongoBinData.
Parmetros
a
Un array.
options
Opciones de insercin. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos, y en caso de que la insercin no tenga xito, emitir una excepcin de tipo MongoCursorException. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la insercin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la insercin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una insercin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.
Valores devueltos
125
Si safe est habilitado, devuelve un array con el estado de la insercin. En cualquier otro caso, devuelve un booleano indicando si el array no estaba vaco (un array vaco no se insertar).
Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" estuviera habilitada y fallara la insercin. (Versin 1.0.1+) Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y la operacin llevara ms de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.
Historial de cambios
Versin 1.0.5
Descripcin Cambiado el segundo parmetro a un array de opciones. Antes de 1.0.5, el segundo parmetro era un booleano indicando la opcin "safe". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".
1.0.9
1.0.11
1.2.0
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::insert() con _id Al insertar un objeto se le aadir un campo _id, a no ser que se pase por referencia.
<?php $a = array('x' => 1); $collection->insert($a); var_dump($a); $b = array('x' => 1); $ref = &$b; $collection->insert($ref); var_dump($ref);
126
?>
Ejemplo #2 - Ejemplo de MongoCollection::insert() safe Este ejemplo muestra cmo al insertar dos elementos con el mismo _id, se provoca que se lance una excepcin MongoCursorException, ya que safe est habilitado.
<?php $persona = array("nombre" => "Joe", "edad" => 20); $coleccion->insert($persona, true); // ahora $person tiene un campo _id, as que si intentamos guardarlo // de nuevo, obtendremos una excepcin try { $colecction->insert($persona, true); } catch(MongoCursorException $e) { echo "No se puede guardar dos veces la misma persona!\n"; } ?>
Ver tambin
Documentacin de MongoDB sobre insert.
127
MongoCollection::remove
MongoCollection::remove -- Eliminar registros de esta coleccin
Descripcin
public mixed MongoCollection::remove ( [ array $criteria = array() [, array $options = array() ] ] )
Parmetros
criteria
Opciones de eliminacin. "justOne" Eliminar solamente uno de los registros que cumplan las condiciones. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos y emitira una excepcion MongoCursorException si la eliminacin no tuviera xito. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la eliminacin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la eliminacin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una eliminacin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.
Valores devueltos
Si "safe" est habilitado, devuelve un array asociativo con el estado de la eliminacin ("ok"), el nmero de elementos eliminados ("n"), y cualquier error que pudiera haber Driver nativo MongoDB 128
ocurrido ("err"). En cualquier otro caso, si la eliminacin se hubiera realizado con xito devuelve TRUE, o FALSE en caso contrario.
Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" est habilitada y la eliminacin falla. Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y la operacin llevara ms de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.
Historial de cambios
Versin 1.0.9
Descripcin Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Cambiado el segundo parmetro a un array de opciones. Antes de 1.0.5, el segundo parmetro era un booleano indicando la opcin "justOne" y no haba opcin "safe". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".
1.0.5
1.0.11
1.2.0
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::remove() con justOne
<?php $radioactivo = $db->radioactivo; // contar cunto plution queda $restante = $radioactivo->count(array('type' => 94)); $vidamedia = $restante/2; // eliminar la mitad while ($vidamedia > 0) { $radioactivo->remove(array('type' => 94), array("justOne" => true)); $vidamedia--; }
129
?>
Ver tambin
Documentacin de MongoDB sobre remove.
130
MongoCollection::save
MongoCollection::save -- Guarda un objeto en esta coleccin
Descripcin
public mixed MongoCollection::save ( array $a [, array $options = array() ] ) Si el objeto fuera de la base de datos, se actualizara. En caso contrario, se insertara.
Parmetros
a
Array a guardar.
options
Opciones de guardado. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos y emitira una excepcion MongoCursorException si la insercin no tuviera xito. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la insercin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la insercin se sincronice en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una insercin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.
Valores devueltos
Si safe estuviera habilitado, devolvera un array que contiene el estado de la escritura. En cualquier otro caso, devuelve un booleano que representa si el array no estaba vaco (un Driver nativo MongoDB 131
Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" est habilitada y fallara al guardar. Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y a la operacin llevara ms de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.
Historial de cambios
Descripcin Aadido el parmetro "options". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".
1.0.11
1.2.0
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::save()
<?php $obj = array('x' => 1); // insertar $obj en la base de datos $collection->save($obj); // aadir otro campo $obj['foo'] = 'bar'; // $obj no puede insertarse de nuevo; provoca un error de _id duplicado $collection->insert($obj); // la funcin save actualiza $obj con el nuevo campo $collection->save($obj); ?>
132
MongoCollection::setSlaveOkay
MongoCollection::setSlaveOkay -- Cambia el valor de slaveOkay de esta coleccin
Descripcin
public bool MongoCollection::setSlaveOkay ( [ bool $ok = true ] ) Revise la seccin de consultas de este manual para ms informacin sobre distribucin de lecturas a esclavos.
Parmetros
ok
Indica si las lecturas deben enviarse a miembros secundarios del conjunto de rplicas para todas las posibles consultas que utilicen esta instancia de MongoCollection.
Valores devueltos
Devuelve el valor anterior de slaveOkay de esta instancia.
133
MongoCollection::__toString
MongoCollection::__toString -- Representacin en forma de string de esta coleccin
Descripcin
public string MongoCollection::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nombre completo de esta coleccin.
Ejemplos
134
MongoCollection::update
MongoCollection::update -- Actualizar registros basndose en los criterios proporcionados
Descripcin
public bool MongoCollection::update ( array $criteria, array $newobj [, array $options = array() ] )
Parmetros
criteria
El objeto con el que actualizar los registros que cumplan las condiciones.
options
Este parmetro es un array asociativo de la forma array("optionname" => <boolean>, ...). Las opciones soportadas actualmente son: "upsert" Si ningn documento cumplira las condiciones de $criteria, se creara un nuevo documento a partir de $criteria y $newobj (revise ms abajo el ejemplo de upsert). "multiple" Todos los documentos que cumplan las condiciones de $criteria se actualizarn. MongoCollection::update() tiene exactamente el comportamiento contrario que MongoCollection::remove(): de forma predeterminada, actualiza slo un documento, no todos los que cumplan las condiciones. Se recomienda especificar siempre se si deben actualizar mltiples documentos o un nico documento, ya que el comportamiento predeterminado de la base de datos podra cambiar en el futuro. "safe" Puede ser un booleano o un entero, por omisin FALSE. Si FALSE, el programa continua su ejecucin sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperar la respuesta de la base de datos y emitira una excepcion MongoCursorException si la insercin no tuviera xito. Si se estuvieran utilizando rplicas, y el maestro cambiara, al usar "safe" se provocara que el driver desconectara del maestro, emitira una excepcin, y en la siguiente operacin se tratra de encontrar un nuevo maestro (su aplicacin debe decidir si reintentar realizar de nuevo la operacin sobre un nuevo maestro). Si no utiliza "safe" con conjuntos de rplicas y el maestro cambia, no habr forma de que el driver conozca el cambio. En este caso, continuar la ejecucin y la escritura, silenciosamente, fallar. Si safe fuera un entero, replicar la actualizacin a ese nmero de mquinas antes de notificar un xito (o lanzara una excepcin si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la coleccin. "fsync" Booleano, por omisin FALSE. Obliga a que la actualizacin se sincronice
135
en disco antes de notificar xito. Si TRUE, se realiza de manera implcita una actuaizacin segura (safe) y sobrescribir el ajuste safe a FALSE. "timeout" Entero, por omisin MongoCursor::$timeout. Si "safe" est habilitado, este valor indica por cunto tiempo (en milisegundos) esperar el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzara una excepcin de tipo MongoCursorTimeoutException.
Valores devueltos
Devuelve un booleano indicando si la actualizacin se envi o no con xito a la base de datos.
Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" estuviera habilitada y la actualizacin fallara. Lanza MongoCursorTimeoutException si la opcin "safe" estuviera habilitada y a la operacin llevara ms de MongoCursor::$timeout milisegundos completarse. No detiene el proceso en el servidor; es slo un tiempo de espera en el lado del cliente.
Historial de cambios
Versin 1.0.1
Descripcin Cambiado el parmetro "opciones" de un booleano a un array. Antes de 1.0.1, el segundo parmetro era un booleano opcional cuyo valor indicaba si era o no upsert. Aadida la opcin "safe". Aadido soporte para pasar enteros a la opcin "safe" (antes slo aceptaba booleanos) y aadida la opcin "fsync". Si "safe" est habilitado y hay un error que no sea en el maestro, se desconecta. Aadida la opcin "timeout".
1.0.5 1.0.9
1.0.11
1.2.0
Ejemplos
Driver nativo MongoDB 136
Ejemplo #2 - Ejemplo de MongoCollection::update() con upsert Los upserts pueden simplificar el cdigo, ya que con una sla lnea podemos crear el objeto si ste no existiera, o actualizarlo si existiera.
<?php $c->drop(); $c->update(array("uri" => "/fotos_verano"), array('$inc' => array("accesos" => 1)), array("upsert" => true)); var_dump($c->findOne()); ?>
Si newobj no contuviera operadores $, upsert podra crear a partir de l un nuevo Driver nativo MongoDB 137
documento. Esto coincide con el comportamiento normal de una actualizacin: si no se usaran operadores $, se sobrescribira todo el documento.
<?php $c->update(array("nombre" => "juan"), array("usuario" => "juan12", "fechaAlta" => new MongoDate()), array("upsert" => true)); ?>
Ejemplo #3 - Ejemplo de mltiples MongoCollection::update() De forma predeterminada, MongoCollection::update() slo actualizar el primer documento que encuentre que cumpla las condiciones de $criteria. Si fuera necesario, mediante la opcin "multiple" podremos sobrescribir este comportamiento. Este ejemplo aade un campo "regalo" a cada persona cuyo cumpleaos sea el prximo da.
<?php $hoy = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day"))); $gente->update(array("cumpleaos" => $hoy), array('$set' => array('regalo' => $surprise)), array("multiple" => true)); ?>
Ver tambin
La documentacin de PHP sobre actualizaciones y la documentacion en MongoDB.
138
MongoCollection::validate
MongoCollection::validate -- Valida esta coleccin
Descripcin
public array MongoCollection::validate ( [ bool $scan_data = FALSE ] )
Parmetros
scan_data
Valores devueltos
Devuelve la evaluacin de la base de datos de este objeto.
139
Clase MongoCursor
Introduccin
Un cursor se utiliza parar recorrer el resultado de una consulta a la base de datos. Por ejemplo, para consultar la base de datos y revisar los resultados, se podra:
<?php $cursor = $collection->find(); var_dump(iterator_to_array($cursor)); ?>
Por norma general los cursores no se crean utilizando el constructor MongoCursor, ya que se obtienen al invicar a MongoCollection::find() (como en el ejemplo superior). Supngase que, en el ejemplo superior, $collection fuera una coleccin de 50GB. No quisiramos tener que alojar en memoria todo de una vez, y esto es lo que solucionan los cursores: permiten al cliente acceder a la coleccin gota a gota. Si tuviramos un resultado extenso, podramos recorrerlo cargando unos pocos megabytes a memoria cada vez. Por ejemplo:
<?php $cursor = $collection->find(); foreach ($cursor as $doc) { // hacer algo a cada documento } ?>
Esto recorrer cada documento de la coleccin, cargando y eliminando de memoria cada documento segn se necesite. Debe tenerse en cuenta que esto significa que un cursor no "contiene" el resultado de la base de datos, sino que slo lo gestiona. Por tanto, si se imprimiera un cursor (con, digamos, var_dump() o print_r() ), slo se obtendra el propio objeto cursor, sin los documentos. Para obtener los documentos en s, debe utilizarse alguno de los mtodos vistos arriba.
Estados de un Cursor
Un MongoCursor tiene dos estados: pre y post consulta. Al crear un cursor, ste no se conecta a la base de datos, por lo que est en estado pre-consulta. En este estado, el cliente puede indicar qu quiere consultar, definiendo lmites, saltos, ordenaciones y ms opciones avanzadas.
140
Cuando el cliente solicita el resultado (invocando MongoCursor::next(), directa o indirectamente), el cursor avanza al estado post-consulta. En este punto, la consulta ya se ha ejecutado por la base de datos y ya no se puede modificar.
<?php $cursor = $collection->find()->limit(10); // todava no se ha consultado la base de datos, de modo que se pueden aadir ms opciones $cursor = $cursor->sort(array("a" => 1)); var_dump($cursor->getNext()); // ya se ha consultado la base de datos, y no se pueden aadir ms opciones // por lo que esto lanzara una excepcin: $cursor->skip(4); ?>
Clases sinopsis
MongoCursor
implements Iterator { /* Campos Estticos */ static boolean slaveOkay = FALSE; static integer timeout = 20000; /* Mtodos */ public MongoCursor MongoCursor::addOption ( string $key, mixed $value ) public MongoCursor MongoCursor::batchSize ( int $num ) MongoCursor::__construct ( Mongo $connection, string $ns [, array $query = array() [, array $fields = array() ] ] ) public int MongoCursor::count ( [ bool $foundOnly = FALSE ] ) public array MongoCursor::current ( void ) public bool MongoCursor::dead ( void ) protected void MongoCursor::doQuery ( void )
141
public array MongoCursor::explain ( void ) public MongoCursor MongoCursor::fields ( array $f ) public array MongoCursor::getNext ( void ) public bool MongoCursor::hasNext ( void ) public MongoCursor MongoCursor::hint ( array $key_pattern ) public MongoCursor MongoCursor::immortal ( [ bool $liveForever = true ] ) public array MongoCursor::info ( void ) public string MongoCursor::key ( void ) public MongoCursor MongoCursor::limit ( int $num ) public void MongoCursor::next ( void ) public MongoCursor MongoCursor::partial ( [ bool $okay = true ] ) public void MongoCursor::reset ( void ) public void MongoCursor::rewind ( void ) public MongoCursor MongoCursor::skip ( int $num ) public MongoCursor MongoCursor::slaveOkay ( [ bool $okay = true ] ) public MongoCursor MongoCursor::snapshot ( void ) public MongoCursor MongoCursor::sort ( array $fields ) public MongoCursor MongoCursor::tailable ( [ bool $tail = true ] ) public MongoCursor MongoCursor::timeout ( int $ms ) public bool MongoCursor::valid ( void ) }
Variables Estticas
MongoCursor::slaveOkay Si la consulta debe o no tener asignada la bandera "slaveOkay", la cual permite leer en un esclavo (por omisin, los esclavos son para hacer copias de seguridad). Puede sobrescribirse con MongoCursor::slaveOkay(). MongoCursor::timeout Establecer el tiempo de espera en milisegundos para las respuestas de todas las
142
bases de datos. Para esperar eternamente, use -1. Se puede sobcrescribir con MongoCursor::timeout(). Esto no hace que el servidor MongoDB cancele la operacin; slo hace que el driver deje de esperar, y emite una excepcin MongoCursorTimeoutException.
Ver tambin
Documentacin de MongoDB sobre cursores.
143
MongoCursor::addOption
MongoCursor::addOption -- Adds a top-level key/value pair to a query
Descripcin
public MongoCursor MongoCursor::addOption ( string $key, mixed $value ) This is an advanced function and should not be used unless you know what you're doing. A query can optionally be nested in a "query" field if other options, such as a sort or hint, are given. For instance, adding a sort causes the query to become a subfield of a bigger query object, like:
<?php $query = array("query" => $query, "orderby" => $sort); ?>
This method is for adding a top-level field to a query. It makes the query a subobject (if it isn't already) and adds the key/value pair of your chosing to the top level.
Advertencia It cannot be used to add extra criteria to a query on the fly. For instance, this will not work:
<?php // NOT CORRECT $cursor = $users->find()->addOption("name", "joe")->addOption("age", 20); ?>
This does not query for a user named "joe" with an age of 20.
Parmetros
key
Fieldname to add.
value
Value to add.
Valores devueltos
Returns this cursor.
144
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
Ejemplos
Ejemplo #1 - MongoCursor::addOption() example Using MongoCursor::skip() to skip over millions of results can become slow. One way around this is to use $min or $max options for the query. These can be handy, but they require an index on exactly the fields being searched for. This is an example of how to use $min as an alternative to MongoCursor::skip().
<?php // make sure we have an index $c->ensureIndex(array("ts" => 1)); // you may have to modify this to run in a reasonable amount of time on slow // machines (should take about 30 seconds on a good machine) for ($i = 0; $i < 30000000; $i++) { $c->insert(array("ts" => new MongoDate(), "i" => $i)); } $now = strtotime("now"); // find documents inserted in the last 2 seconds $cursor = $c->find()->addOption('$min', array("ts" => $now-2)); ?>
145
MongoCursor::batchSize
MongoCursor::batchSize -- Sets the number of results returned per result set
Descripcin
public MongoCursor MongoCursor::batchSize ( int $num ) This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results). To ensure consistent behavior, the rules of batchSize and limit behavior a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. Some examples:
<?php // one batch, at most 20 items $cursor->limit(-20)->batchSize(10); // one batch, at most 10 items $cursor->limit(20)->batchSize(-10); // first batch: at most 10 items $cursor->limit(10); // first batch: at most 10 items $cursor->limit(10)->batchSize(20); // first batch: at most 10 items $cursor->limit(20)->batchSize(10);
$cursor->limit(30)->batchSize(7) // if we iterate through 28 items, the next call to getNext() will contact the // database and request a batch of 2 documents ?>
Parmetros
num
Valores devueltos
Returns this cursor.
Errores/Excepciones
Driver nativo MongoDB 146
Throws MongoCursorException if this cursor has started iterating. This will change in 1.0.12, as this should be able to be called at any time.
147
MongoCursor::__construct
MongoCursor::__construct -- Create a new cursor
Descripcin
MongoCursor::__construct ( Mongo $connection, string $ns [, array $query = array() [, array $fields = array() ] ] )
Parmetros
connection
Database connection.
ns
Database query.
fields
Fields to return.
Valores devueltos
Returns the new cursor.
148
MongoCursor::count
MongoCursor::count -- Counts the number of results for this query
Descripcin
public int MongoCursor::count ( [ bool $foundOnly = FALSE ] ) This method does not affect the state of the cursor: if you haven't queried yet, you can still apply limits, skips, etc. If you have started iterating through results, it will not move the current position of the cursor. If you have exhasted the cursor, it will not reset it.
Parmetros
foundOnly
Send cursor limit and skip information to the count function, if applicable.
Valores devueltos
The number of documents returned by this cursor's query.
Ejemplos
Ejemplo #1 - MongoCursor::count() example
<?php $collection->insert(array('x'=>1)); $collection->insert(array('x'=>2)); $collection->insert(array('x'=>3)); $cursor = $collection->find(); var_dump($cursor->count()); var_dump($cursor->count(true)); $cursor->limit(2); var_dump($cursor->count()); var_dump($cursor->count(true)); ?>
149
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.
150
MongoCursor::current
MongoCursor::current -- Returns the current element
Descripcin
public array MongoCursor::current ( void ) This returns NULL until MongoCursor::next() is called.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
The current result as an associative array.
151
MongoCursor::dead
MongoCursor::dead -- Checks if there are documents that have not been sent yet from the database for this cursor
Descripcin
public bool MongoCursor::dead ( void ) The database sends responses in batches of documents, up to 4Mb of documents per response. This method checks if the database has more batches or if the result set has been exhausted. A cursor being "dead" does not mean that MongoCursor::hasNext() will return FALSE, it only means that the database is done sending results to the client. The client should continue iterating through results until MongoCursor::hasNext() is FALSE.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns if there are more results that have not been sent to the client, yet.
152
MongoCursor::doQuery
MongoCursor::doQuery -- Execute the query.
Descripcin
protected void MongoCursor::doQuery ( void ) This function actually queries the database. All queries and commands go through this function. Thus, this function can be overridden to provide custom query handling. This handles serializing your query, sending it to the database, receiving a response, and deserializing it. Thus, if you are planning to override this, your code should probably call out to the original to use the existing functionality (see the example below).
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
NULL.
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.
Ejemplos
Ejemplo #1 - MongoCursor::doQuery() example You could override this function to attempt a query on a slave and, if that fails, try it again on the master.
<?php class MyCursor extends MongoCursor { protected function doQuery() { $this->slaveOkay(); try { MongoCursor::doQuery(); } catch(MongoCursorException $e) { $this->slaveOkay(false); MongoCursor::doQuery();
153
} } } ?>
154
MongoCursor::explain
MongoCursor::explain -- Return an explanation of the query, often useful for optimization and debugging
Descripcin
public array MongoCursor::explain ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns an explanation of the query.
Ejemplos
Ejemplo #1 - MongoCursor::explain() example
<?php $cursor = $collection->find(array("x"=>1), array("y")); $cursor->sort(array("z" => 1))->limit(4)->skip(5); var_dump($cursor->explain()); ?>
155
int(3) ["allPlans"]=> array(2) { [0]=> array(3) { ["cursor"]=> string(15) "BtreeCursor x_1" ["startKey"]=> array(1) { ["x"]=> int(1) } ["endKey"]=> array(1) { ["x"]=> int(1) } } [1]=> array(3) { ["cursor"]=> string(11) "BasicCursor" ["startKey"]=> array(0) { } ["endKey"]=> array(0) { } } } }
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database.
Ver tambin
MongoDB core docs on explain.
156
MongoCursor::fields
MongoCursor::fields -- Sets the fields for a query
Descripcin
public MongoCursor MongoCursor::fields ( array $f ) Fields are specified by "fieldname" : bool. TRUE indicates that a field should be returned, FALSE indicates that it should not be returned. You can also use 1 and 0 instead of TRUE and FALSE. Thus, to return only the "summary" field, one could say:
<?php $cursor->fields(array("summary" => true)); ?>
Parmetros
f
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating or a scalar argument is given.
157
MongoCursor::getNext
MongoCursor::getNext -- Return the next object to which this cursor points, and advance the cursor
Descripcin
public array MongoCursor::getNext ( void ) This is identical to the function:
<?php public function getNext() { $this->next(); return $this->current(); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns the next object.
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
158
MongoCursor::hasNext
MongoCursor::hasNext -- Checks if there are any more elements in this cursor
Descripcin
public bool MongoCursor::hasNext ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns if there is another element.
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
159
MongoCursor::hint
MongoCursor::hint -- Gives the database a hint about the query
Descripcin
public MongoCursor MongoCursor::hint ( array $key_pattern )
Parmetros
key_pattern
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
160
MongoCursor::immortal
MongoCursor::immortal -- Sets whether this cursor will timeout
Descripcin
public MongoCursor MongoCursor::immortal ( [ bool $liveForever = true ] ) After remaining idle for some amount of time, cursor, by default, "die." This is generally the behavior one wants. The database cleans up a cursor once all of its results have been sent to the client, but if the client doesn't request all of the results, the cursor will languish there, taking up resources. Thus, after a few minutes, the cursor "times out" and the database assumes the client has gotten everything it needs and cleans up its the cursor's resources. If, for some reason, you need a cursor to hang around for a long time, you can prevent the database from cleaning it up by using this method. However, if you make a cursor immortal, you need to iterate through all of its results (or at least until Cursor::dead() returns TRUE ) or the cursor will hang around the database forever, taking up resources.
Parmetros
liveForever
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
161
MongoCursor::info
MongoCursor::info -- Gets the query, fields, limit, and skip for this cursor
Descripcin
public array MongoCursor::info ( void ) This can be called before or after the query.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns the namespace, limit, skip, query, and fields for this cursor.
Historial de cambios
Versin 1.0.10
Descripcin Added started_iterating field, a boolean indicating if cursor is pre- or post-query. Added a number of other fields, including id (the cursor id), at (the driver's counter of which document is current), numReturned (the number returned by the server in the current batch), and server (which server the query was sent to?useful in conjunction with MongoCursor::slaveOkay() ).
1.1.0
Ejemplos
Ejemplo #1 - MongoCursor::info() example
<?php $m = new Mongo(); $cursor = $m->foo->bar->find(array("x" => 4), array("y" => false)); var_dump($cursor->info()); ?>
162
163
MongoCursor::key
MongoCursor::key -- Returns the current result's _id
Descripcin
public string MongoCursor::key ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
The current result's _id as a string.
164
MongoCursor::limit
MongoCursor::limit -- Limits the number of results returned
Descripcin
public MongoCursor MongoCursor::limit ( int $num )
Parmetros
num
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
Ver tambin
MongoDB core docs on limit.
165
MongoCursor::next
MongoCursor::next -- Advances the cursor to the next result
Descripcin
public void MongoCursor::next ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
NULL.
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
166
MongoCursor::partial
MongoCursor::partial -- If this query should fetch partial results from mongos if a shard is down
Descripcin
public MongoCursor MongoCursor::partial ( [ bool $okay = true ] ) This option allows mongos to send partial query results if a shard is unreachable. This is only applicable when running a sharded MongoDB cluster and connecting to a mongos. If a shard goes down and a query needs to be sent to that shard, mongos will return the results (if any) from shards it already contacted, then an error message that it could not reach the shard (a MongoCursorException in PHP). If you would like to get whatever results mongos can provide and no exception, you can use this method. Note that this means that you won't have an indication that a shard is down in your query response. This has no effect on the query if all shards are reachable. This flag was implemented in MongoDB version 1.7.5, so will only work with that version and higher.
Parmetros
okay
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
167
MongoCursor::reset
MongoCursor::reset -- Clears the cursor
Descripcin
public void MongoCursor::reset ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
NULL.
168
MongoCursor::rewind
MongoCursor::rewind -- Returns the cursor to the beginning of the result set
Descripcin
public void MongoCursor::rewind ( void ) This is identical to the function:
<?php public function rewind() { $this->reset(); $this->next(); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
NULL.
Errores/Excepciones
Throws MongoConnectionException if it cannot reach the database and MongoCursorTimeoutException if the timeout is exceeded.
169
MongoCursor::skip
MongoCursor::skip -- Skips a number of results
Descripcin
public MongoCursor MongoCursor::skip ( int $num )
Parmetros
num
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
170
MongoCursor::slaveOkay
MongoCursor::slaveOkay -- Sets whether this query can be done on a slave
Descripcin
public MongoCursor MongoCursor::slaveOkay ( [ bool $okay = true ] ) Calling this will make the driver route reads to slaves if: You are using a replica set and You created a Mongo instance using the option "replicaSet" => true and There is a healthy slave that can be reached by the driver. You can check which server was used for this query by calling MongoCursor::info() after running the query. It's server field will show which server the query was sent to. Note that you should use this function even if you do not use the automatic routing to slaves. If you connect directly to a secondary in a replica set, you still need to call this function, which basically tells the database that you are aware that you might be getting older data and you're okay with that. If you do not call this, you'll get "not master" errors when you try to query. This method will override the static class variable MongoCursor::slaveOkay. It will also override Mongo::setSlaveOkay(), MongoDB::setSlaveOkay() and MongoCollection::setSlaveOkay().
Parmetros
okay
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
Ejemplos
Ejemplo #1 - MongoCursor::slaveOkay() example
<?php
171
MongoCursor::$slaveOkay = false; // cannot query slave $cursor = $collection->find(); // can query slave $cursor = $collection->find()->slaveOkay(); MongoCursor::$slaveOkay = true; // can query slave $cursor = $collection->find(); // cannot query slave $cursor = $collection->find()->slaveOkay(false); ?>
172
MongoCursor::snapshot
MongoCursor::snapshot -- Use snapshot mode for the query
Descripcin
public MongoCursor MongoCursor::snapshot ( void ) Use snapshot mode for the query. Snapshot mode assures no duplicates are returned, or objects missed, which were present at both the start and end of the query's execution (if an object is new during the query, or deleted during the query, it may or may not be returned, even with snapshot mode). Note that short query responses (less than 1MB) are always effectively snapshotted. Currently, snapshot mode may not be used with sorting or explicit hints.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Returns this cursor.
Errores/Excepciones
Throws MongoCursorException if this cursor has started iterating.
173
MongoCursor::sort
MongoCursor::sort -- Sorts the results by given fields
Descripcin
public MongoCursor MongoCursor::sort ( array $fields )
Parmetros
fields
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)); ?>
174
MongoCursor::tailable
MongoCursor::tailable -- Sets whether this cursor will be left open after fetching the last results
Descripcin
public MongoCursor MongoCursor::tailable ( [ bool $tail = true ] ) Mongo has a feature known as tailable cursors which are similar to the Unix "tail -f" command. Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final object's position. you can resume using the cursor later, from where it was located, if more data were received. Like any "latent cursor", the cursor may become invalid at some point -- for example if that final object it references were deleted. Thus, you should be prepared to requery if the cursor is MongoCursor::dead().
Parmetros
tail
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()) {
175
break; } // read all results so far, wait for more sleep(10); } else { $results[] = $cursor->getNext(); } } ?>
176
MongoCursor::timeout
MongoCursor::timeout -- Sets a client-side timeout for this query
Descripcin
public MongoCursor MongoCursor::timeout ( int $ms ) A timeout can be set at any time and will affect subsequent queries on the cursor, including fetching more results from the database. For example, to wait forever for an initial response but timeout after 100 ms for subsequent results, one could say:
<?php $cursor = $collection->find(); // $cursor->hasNext() executes the query. No timeout has been set, so the // program will wait as long as necessary for a response. while ($cursor->hasNext()) { $cursor->timeout(100); // now the timeout has been set, so if the cursor needs to get more results // from the database, it will only wait 100 ms for the database's reply try { print_r($cursor->getNext()); } catch(MongoCursorTimeoutException $e) { echo "query took too long!"; } } ?>
A timeout of 0 (or a negative number) will wait forever so it can be used to reset the cursor if a timeout is no longer needed.
Parmetros
ms
The number of milliseconds for the cursor to wait for a response. By default, the cursor will wait forever.
Valores devueltos
This cursor.
Ejemplos
177
Ejemplo #1 - MongoCursor::timeout() example A query where the cursor waits for one second for a response.
<?php $cursor = $collection->find()->timeout(1000); try { foreach ($cursor as $value) { print_r($value); } } catch(MongoCursorTimeoutException $e) { echo "query took too long!"; } ?>
Errores/Excepciones
Causes methods that fetch results to throw MongoCursorTimeoutException s if the query takes longer than the number of milliseconds specified.
178
MongoCursor::valid
MongoCursor::valid -- Checks if the cursor is reading a valid result.
Descripcin
public bool MongoCursor::valid ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
If the current result is not null.
179
Tipos
MongoDB permite a los programadores guardar y consultar datos expresados tanto en los tipos bsicos de PHP, los tipos compuestos (arrays, arrays asociativos, y objetos), y en media docena de clases que proporciona el driver MongoDB de PHP (para expresiones regulares, fechas, y otras aplicaciones especializadas).
Booleanos y NULL
TRUE, FALSE, y NULL pueden usarse tal cual.
Nmeros
En MongoDB los nmeros son distintos de los strings: "123" no es lo mismo que 123. Por tanto, si se desea asegurar de que los nmeros se ordenan y comparan correctamente, debe asegurarse de que realmente se almacenan como nmeros.
<?php $doc = array("a" => 123, "b" => "123"); $collection->insert($doc); $doc->find(array("a" $doc->find(array("a" $doc->find(array("a" $doc->find(array("b" $doc->find(array("b" ?> => => => => => 123)); "123")); 123.0)); 123)); "123")); // // // // // coincide no coincide coincide no coincide coincide
Como vemos, los nmeros en coma flotante se comparan y coinciden con los nmeros enteros tal como cabra esperar.
Nmeros Largos
Por omisin, en sistemas de 32 bits, los nmeros se envan a la base de datos como enteros de 32 bit. En sistemas 64 bits, se envan como enteros de 64 bit. Para guardar la compatibilidad, todos los sistemas deserializan los enteros de 64 bit como nmeros en coma flotante. Los nmeros en coma flotante no son exactos. Si fuera necesario usar valores exactos, habra que hacerlo ajsutando el fichero php.ini. En sistemas de 32 bits, si mongo.long_as_object est habilitado, los enteros de 64 bit se devolvern como objetos MongoInt64. El entero se almacenar en el campo value con una precisin perfecta (como un string). MongoInt64 puede usarse tambin para guardar enteros de 64 bit en mquinas de 32 bits.
180
En sistemas de 64 bits, puede o bien habilitarse mongo.long_as_object o mongo.native_long. mongo.native_long devolver enteros de 64 bit y enteros "normales" de PHP. MongoInt32 puede usarse para almacenar enteros de 32 bit en mquinas de 64 bits. Debe establecerse un valor en mongo.long_as_object y en mongo.native_long de acuerdo al comportamiento que se espere, incluso en el caso de que coincida con los valores por omisin (para prevenir futuros cambios de estos valores). Vea tambin: Opciones de php.ini, MongoInt32, MongoInt64.
Strings
Los strings deben ser UTF-8. Si no, o bien se convierten a UTF-8 antes de enviarse a la base de datos, o bien se almacenan como datos binarios. Pueden usarse expresiones regulares para consultar strings, y se expresan usando la clase MongoRegex.
Datos Binarios
Tanto los textos que no son UTF-8, como las imgenes, o cualuier otro dato binario, debe enviarse a la base de datos usando el tipo MongoBinData.
Fechas
Pueden crearse fechas usando la clase MongoDate. Se almacenan como milisegundos a partir de la fecha de referencia. MongoTimestamp no es para almacenar fechas ni timestamps, sino que se usa internamente por MongoDB. A no ser que se est creando una herramienta que interacte con los entresijos de rplicas o sharding, se deber usar MongoDate, y no MongoTimestamp.
Ids nicos
El driver crear automticamente un campo _id antes de insertar un documento (a no ser que el usuario haya especificado uno). Este campo es una instancia de MongoId (en otros lenguajes habitualmente se le llama "ObjectId"). Estos ids se componen de 12 bytes: 4 bytes de timestamp Dos registros no pueden tener el mismo id si se han insertado en momentos diferentes. 3 bytes de id de mquina Dos registros no pueden tener el mismo id si se han insertado en mquinas diferentes. Driver nativo MongoDB 181
2 bytes de id de hebra Dos registros no pueden tener el mismo id si se han insertado por diferentes hebras en la misma mquina. 3 bytes de valor incremental Cada vez que se crea un id, un contador global se incrementa, y se usa para el incremento del siguiente id. Por tanto, dos registros no pueden tener el mismo id, a no ser que un nico proceso en una misma mquina trate de insertar 256^3 (ms de 16 millones) de documentos en un segundo, desbordando el campo de incremento.
JavaScript
MongoDB incorpora un motor JavaScript, de modo que se pueden incluir cdigo JavaScript en las consultas (usando la clasula $where), enviarlo directamente a la base de datos para ejecutarlo, y usarlo para llevar a cabo agregaciones. Por seguridad, en MongoCode utilice el campo scope cuando vaya a usar variables PHP en JavaScript. Cuando el cdigo no requiera de valores externos, se puede o bien usar MongoCode o smplemente un string. Revise la seccin de seguridad para ms informacin sobre cmo enviar cdigo JavaScript a la base de datos.
Arrays y Objetos
Tambin pueden guardarse arrays y objetos en la base de datos. Los arrays con clave numrica incremental se almacenarn como arrays. En cualquier otro caso, se almacenarn como objetos.
<?php // $puntuaciones se almacenar como array $puntuaciones = array(98, 100, 73, 85); $collection->insert(array("puntuaciones" => $puntuaciones)); // $puntuaciones se almacenar como un objeto $puntuaciones = array("pregunta1" => 98, "examen" => 100, "pregunta2" => 73, "final" => 85); $collection->insert(array("puntuaciones" => $puntuaciones)); ?>
Si consultamos estos objetos en la consola de la base de dato, obtendremos algo similar a esto:
> db.students.find() { "_id" : ObjectId("4b06beada9ad6390dab17c43"), "puntuaciones" : [ 98, 100, 73, 85 ] } { "_id" : ObjectId("4b06bebea9ad6390dab17c44"), "puntuaciones" : { "pregunta1" : 98, "examen" : 100, "pregunta2" : 73, "final" : 85 } }
La base de datos puede almacenar tambin objetos PHP arbitrarios (pese a que se devolvern como arrays asociativos). Los campos se usan para pares clave/valor. Por ejemplo, la entrada de un blog podra ser as:
<?php
182
// clase de la entrada de un blog class Entrada { var var var var $autor; $contenido; $comentarios = array(); $fecha;
public function __construct($autor, $contenido) { $this->autor = $autor; $this->contenido = $contenido; $this->fecha = new MongoDate(); } public function establecerTitulo($titulo) { $this->titulo = $titulo; } } // crear una entrada de blog sencilla e insertarla en base de datos $entrada1 = new Entrada("Adam", "Esto es una entrada de un blog"); $blog->insert($entrada1);
// no hay niguna restriccin del tipo usado en el campo "autor", de manera que podemos // usarlo como un objeto anidado $autor = array("nombre" => "Fred", "karma" => 42); $entrada2 = new Entrada($autor, "sta es otra entrada de blog."); // creamos un campo ms para el ttulo $entrada2->establecerTitulo("Segunda Entrada"); $blog->insert($entrada2); ?>
El driver no detecta referencias cclicas en arrays ni en objetos. Por ejemplo, esto emitira un error fatal:
<?php $collection->insert($GLOBALS); ?> Fatal error: Nesting level too deep - recursive dependency?
183
Si se necesitara insertar documentos que pudieran tener dependencias cclicas, deber comprobarse a mano antes de pasarlo al driver.
184
Clase MongoId
Introduccin
Identificador nico creado para objetos de bases de datos. Se se inserta un objeto sin un campo _id en una base de datos , ste se aadir con una instancia de MongoId. Si los datos tuvieran un campo nico natural (como p.ej., un nombre de usuario o una fecha) no habra problema en usarlo como _id, y en este caso no se reemplazara por un MongoId. Las instancias de MongoId cumplen la funcin de los campos autoincrementales de las base de datos relacionales: ofrecen una clave nica cuando los datos no tienen una clave natural. Los autoincrementales no funcionan correctamente en bases de datos compartidas, ya que es imposible averiguar rpidamente cul ser el siguiente nmero. Esta clase establece las limitaciones necesarias para generar rpidamente un valor nico entre servidores compartidos. Cada MongoId contiene 12 bytes (componiendo un string de 24 caracteres hexadecimales). Los cuatro primeros bytes son un timestamp, los tres siguientes son un hash del nombre de mquina del cliente, los dos siguiente son los bytes menos significativos del id del proceso en ejecucin del script, y los ltimos tres corresponden a un valor incremental. MongoId es serializable y deserializable. Su forma serializada es similar a su forma en string:
C:7:"MongoId":24:{4af9f23d8ead0e1d32000000}
Clases sinopsis
MongoId
MongoId { public string $id = NULL; /* Mtodos */ MongoId::__construct ( [ string $id = NULL ] ) public static string MongoId::getHostname ( void ) public int MongoId::getInc ( void )
185
public int MongoId::getPID ( void ) public int MongoId::getTimestamp ( void ) public static MongoId MongoId::__set_state ( array $props ) public string MongoId::__toString ( void ) }
Campos
$id Este campo contiene la respresentacin string de este objeto.
Ver tambin
Documentacin de MongoDB sobre ids.
186
MongoId::__construct
MongoId::__construct -- Crea un nuevo id
Descripcin
MongoId::__construct ( [ string $id = NULL ] )
Parmetros
id
Texto a usar como identificador. Debe estar formado por 24 caracteres hexadecimales. Si se pasara un valor invlido a este constructor, lo ignorara y creara un nuevo valor para id.
Valores devueltos
Devuelve un nuevo id.
Ejemplos
Ejemplo #1 - MongoId::__construct() example Este ejemplo muestra cmo crear un nuevo id. Rara vez neceasrio usar esto, ya que el driver aade automticamente un id a los arrays antes de que los almacene en base de datos.
<?php $id1 = new MongoId(); echo "$id1\n"; $id2 = new MongoId(); echo "$id2\n"; ?>
Ejemplo #2 - Ejemplo con parmetros Este ejemplo muestra cmo usar el parmetro para inicializar un MongoId con el valor Driver nativo MongoDB 187
proporcionado.
<?php $id1 = new MongoId(); // crea un nuevo id a partir de $id1 $id2 = new MongoId("$id1"); // muestra que $id1 e $id2 tienen el mismo valor hexadecimal var_dump($id1 == $id2); ?>
Ver tambin
MongoId::__toString
188
MongoId::getHostname
MongoId::getHostname -- Obtiene el nombre de host que se usa para el id de esta mquina
Descripcin
public static string MongoId::getHostname ( void ) Devuelve el nombre de host que usa MongoId para generar identificadores nicos. Es el mismo valor que devuelve gethostname(). Es idntico a esta funcin:
<?php public static function getHostname() { return gethostname(); } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nombre de host.
189
MongoId::getInc
MongoId::getInc -- Obtiene el valor incremental usado para crear este id
Descripcin
public int MongoId::getInc ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el valor incremental usado para crear este MongoId.
190
MongoId::getPID
MongoId::getPID -- Devuelve el id del proceso usado para crear este id
Descripcin
public int MongoId::getPID ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el PID usado para crear este MongoId.
191
MongoId::getTimestamp
MongoId::getTimestamp -- Devuelve el nmero de segundos desde la fecha de referencia con el que se cre este id
Descripcin
public int MongoId::getTimestamp ( void ) Devuelve lo mismo que cuando se ejecuta time() al crear el id.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nmero de segundos desde la fecha de referencias con el que se cre este id. Tan slo hay cuatro bytes para almacenar el timestamp, por lo que MongoDate es una opcin mejor si se desea almacenar fechas exacta de alto alcance.
192
MongoId::__set_state
MongoId::__set_state -- Crea un MongoId vaco
Descripcin
public static MongoId MongoId::__set_state ( array $props ) Esta funcin slo se usa internamente por PHP, por lo que no debera necesitar ser nunca invocada por el usuario. Es idntica a esta funcin:
<?php public static function __set_state($props) { return new MongoId("000000000000000000000000"); } ?>
Parmetros
props
Supuestamente, un array de propiedades que se usa para crear el nuevo id. Sin embargo, ya que las instancias de MongoId no tienen propiedades, este parmetro no se usa.
Valores devueltos
Un nuevo id con el valor "000000000000000000000000".
193
MongoId::__toString
MongoId::__toString -- Devuelve la representacin hexadecimal de este id
Descripcin
public string MongoId::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Este id.
Ejemplos
Ejemplo #1 - Ejemplo de MongoId::__toString()
<?php $m = new Mongo(); $collection = $m->selectDB("foo")->selectCollection("bar"); $collection->insert(array( "x" => "y" )); $collection->insert(array( "x" => "y" )); $cursor = $collection->find(); $r1 = $cursor->next(); $r2 = $cursor->next(); echo $r1["_id"] . "\n"; echo $r2["_id"] . "\n"; ?>
194
Clase MongoCode
Introduccin
Representa cdigo JavaScript para la base de datos. Los objetos MongoCode se componen de dos partes: el texto del cdigo y un mbito opcional. El texto del cdigo debe ser JavaScript vlido. El mbito es un array asociativo de pares nombre/valor.
Clases sinopsis
MongoCode
MongoCode { /* Mtodos */ MongoCode::__construct ( string $code [, array $scope = array() ] ) public string MongoCode::__toString ( void ) }
195
MongoCode::__construct
MongoCode::__construct -- Crea un nuevo objeto de cdigo
Descripcin
MongoCode::__construct ( string $code [, array $scope = array() ] )
Parmetros
code
Valores devueltos
Devuelve un nuevo objeto de cdigo.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCode::__construct()
<?php $code = new MongoCode('function() { '. 'for(i=0;i<10;i++) {'. 'db.foo.update({z : i}, {z : x});'. '}'. 'return x-1;'. '}', array("x" => 4)); var_dump($code); ?>
196
Ejemplo #2 - Usando MongoCode() con $where Este ejemplo consulta la coleccin de elementos cuyos campos 'x' valgan menos que $y. Tenga en cuenta que se pasan objetos PHP al mbito de JavaScript y que la funcin JavaScript devuelve un booleano.
<?php $cursor = $collection->find(array('$where' => new MongoCode('function() { return this.x < y; }', array('y'=>$y)))); ?>
197
MongoCode::__toString
MongoCode::__toString -- Devuelve este cdigo en forma de texto
Descripcin
public string MongoCode::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Este cdigo. No se devuelve el mbito.
Ejemplos
Ejemplo #1 - Ejemplo de MongoCode::__toString()
<?php $code = new MongoCode('return x;', array("x"=>"hi")); echo "$code\n"; $code = new MongoCode('function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }'); echo "$code\n"; ?>
198
Clase MongoDate
Introduccin
Representa objetos de tipo fecha para la base de datos. Esta clase debe usarse para almacenar fechas en la base de datos y para consultarlas. Por ejemplo:
<?php // guardar una fecha en base de datos $collection->save(array("ts" => new MongoDate())); $start = new MongoDate(strtotime("2010-01-15 00:00:00")); $end = new MongoDate(strtotime("2010-01-30 00:00:00")); // encontrar fechas entre 1/15/2010 y 1/30/2010 $collection->find(array("ts" => array('$gt' => $start, '$lte' => $end))); ?>
MongoDB almacena fechas en milisegundos tras la fecha de referencia. Esto significa que las fechas no contienen informacin de zonas horarias. Si fuera necesario, la zona horaria deber ser almacenada en otro campo. Adems, esto significa que cualquier nivel de precisin ms all de milisegundos se perder al leer o escribir en la base de datos.
Clases sinopsis
MongoDate
MongoDate { /* Campos */ public int sec; public int usec; /* Mtodos */ MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] ) public string MongoDate::__toString ( void ) }
199
MongoDate::__construct
MongoDate::__construct -- Crea un nuevo objeto fecha
Descripcin
MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] ) Crea una nueva fecha. Si no se rellena ningn parmetro, se utilizar la hora actual.
Parmetros
sec
Microsegundos.
Valores devueltos
Devuelve esta nueva fecha.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDate::__construct() Este ejemplo muestra cmo crear una nueva fecha con la hora actual y una nueva fecha con la hora proporcionada.
<?php $d = echo $d = echo $d = echo ?> new MongoDate(); "$d\n"; new MongoDate(1234567890); "$d\n"; new MongoDate(strtotime("2009-05-01 00:00:01")); "$d\n";
200
Ver tambin
MongoDate::__toString
201
MongoDate::__toString
MongoDate::__toString -- Devuelve una representacin en forma de texto de esta fecha
Descripcin
public string MongoDate::__toString ( void ) Devuelve una representacin en forma de texto de esta fecha, similar a la representacin que devuelve microtime().
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Esta fecha.
202
Clase MongoRegex
Introduccin
Esta clase se puede usar para crear expresiones regulares. Normalmente, estas expresiones se usarn para consultar la base de datos y localizar textos que coincidan. Con menos frecuencia, se almacenarn en la base de datos para su posterior consulta. Mongo reconoce seis banderas de expresiones regulares:
i Insensible a maysculas m Multilnea x Puede contener comentarios l local s "." coincidir con todo, incluyendo cambios de lnea u unicode
Clases sinopsis
MongoRegex
MongoRegex { /* Campos */ public string regex; public string flags; /* Mtodos */ MongoRegex::__construct ( string $regex ) public string MongoRegex::__toString ( void ) }
203
MongoRegex::__construct
MongoRegex::__construct -- Crea una nueva expresin regular
Descripcin
MongoRegex::__construct ( string $regex ) Crea una nueva expresin regular.
Parmetros
regex
Valores devueltos
Devuelve una nueva expresin regular.
Ejemplos
Ejemplo #1 - Ejemplo de MongoRegex::__construct() Este ejemplo usa una expresin regular para seleccionar todos los documentos con el campo usuario que cumpla las condiciones.
<?php $buscar_jose = new MongoRegex("/j[o0]se/i"); $cursor = $collection->find(array("usuario" => $buscar_jose)); ?>
Ver tambin
MongoRegex::__toString
204
MongoRegex::__toString
MongoRegex::__toString -- Representacin en forma de texto de esta expresin regular
Descripcin
public string MongoRegex::__toString ( void ) Devuelve la representacin en forma de texto de esta expresin regular.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Esta expresin regular en la forma "/expresin/banderas".
Ejemplos
205
Clase MongoBinData
Introduccin
Objeto para almacenar y consultar datos binarios de la base de datos. El tamao mximo de un objeto que puede insertarse en la base de datos es 4Mb. Para datos superiores (pelculas, msica, autobiografa de Henry Kissinger), utilice MongoGridFS. Para datos inferiores a 4Mb, lo ms probable es que lo ms sencillo sea empotrarlo al documento utilizando MongoBinData. Por ejemplo, para empotrar una imagen a un documento, se podra escribir:
<?php $profile = array("username" => "foobity", "pic" => new MongoBinData(file_get_contents("gravatar.jpg")) ); $users->save($profile); ?>
Esta clase contiene el campo type, que actualmente no proporciona ninguna funcionalidad al driver de la base de datos. Hay 5 tipos predefinidos (las contantes de clase definidas abajo), y los usuarios puede definir los suyos propios (se corre el riesgo de que colisione con la especificacin BSON). Por omisin, el driver de PHP siempre utiliza el tipo 2: un array de bytes.
Clases sinopsis
MongoBinData
MongoBinData { /* Constantes */ const int MongoBinData::FUNC = 1; const int MongoBinData::BYTE_ARRAY = 2; const int MongoBinData::UUID = 3; const int MongoBinData::MD5 = 5;
206
const int MongoBinData::CUSTOM = 128; /* Fields */ public string bin; public int type = 2; /* Mtodos */ public MongoBinData::__construct ( string $data [, int $type = 2 ] ) public string MongoBinData::__toString ( void ) }
207
MongoBinData::__construct
MongoBinData::__construct -- Crea un nuevo objeto de datos binarios
Descripcin
public MongoBinData::__construct ( string $data [, int $type = 2 ] ) Crea un nuevo objeto de datos binarios Hay cinco tipos reconocidos de datos binarios segn la especificacin BSON: funcin (0x01), matriz de bytes (0x02), UUID (0x03), MD5 (0x05), y definido por el usuario (0x80). El tipo por omisin es matriz de bytes (0x02). No hay ninguna diferencia en particilar sobre cmo interpreta el driver cada tipo, There is no particular difference in how the driver or server interpret different types, por tanto es por ahora irrelevante. Se puede usar cualquier nmero (entre 0 y 255) como tipo, siempre y cuando el usuario asuma el riesgo de que la base de datos pueda eventualmente llevar a cabo alguna funcin con datos binarios de este tipo.
Parmetros
data
Datos binarios.
type
Tipo de datos.
Valores devueltos
Devuelve un nuevo objeto de datos binarios.
208
MongoBinData::__toString
MongoBinData::__toString -- Representacin en forma de string de este objeto de datos binarios
Descripcin
public string MongoBinData::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el string "<Mongo Binary Data>". Para acceder al contenido de un MongoBinData, utilice el campo bin.
209
Clase MongoInt32
Introduccin
Esta clase se puede usar para guardar enteros de 32 bits en bases de datos de sistemas a 64 bits.
Clases sinopsis
MongoInt32
MongoInt32 { /* Campos */ public string value; /* Mtodos */ public MongoInt32::__construct ( string $value ) public string MongoInt32::__toString ( void ) }
Campos
value Este es el valor en forma de texto del nmero de 64 bits. Por ejemplo, el valor de 123 sera "123".
210
MongoInt32::__construct
MongoInt32::__construct -- Crea un nuevo entero de 32 bits
Descripcin
public MongoInt32::__construct ( string $value ) Crea un nuevo nmero de 32 bits con el valor proporcionado.
Parmetros
value
Un nmero.
Valores devueltos
Devuelve un nuevo entero.
211
MongoInt32::__toString
MongoInt32::__toString -- Devuelve al representacin en forma de texto de este entero de 32 bits
Descripcin
public string MongoInt32::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la representacin en forma de texto de este entero.
212
Clase MongoInt64
Introduccin
Esta clase se puede usar para guardar enteros de 64 bits en bases de datos en sistemas de 32 bits.
Clases sinopsis
MongoInt64
MongoInt64 { /* Campos */ public string value; /* Mtodos */ public MongoInt64::__construct ( string $value ) public string MongoInt64::__toString ( void ) }
Campos
value Este es el valor en forma de texto del nmero de 64 bits. Por ejemplo, el valor de 123 sera "123".
213
MongoInt64::__construct
MongoInt64::__construct -- Crea un nuevo entero de 64 bits
Descripcin
public MongoInt64::__construct ( string $value ) Crea un nuevo nmero de 64 bits con el valor proporcionado.
Parmetros
value
Un nmero.
Valores devueltos
Devuelve un nuevo entero.
214
MongoInt64::__toString
MongoInt64::__toString -- Devuelve la representacin en forma de texto de este entero de 64 bits
Descripcin
public string MongoInt64::__toString ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve la representacin en forma de texto de este entero.
215
Clase MongoDBRef
Introduccin
Esta clase puede usarse para crear enlaces ligeros entre objetos de diferencias colecciones. Motivacin: Supongamos que necesitamos referirnos a un documento en otra coleccin. La forma ms fcil es crear un nuevo campo en el documento actual. Por ejemplo, si tenemos una coleccin "personas" y una coleccin "direcciones", quizs queramos crear un enlace entre cada documento de persona y un documento de direccin:
<?php $personas = $db->personas; $direcciones = $db->direcciones; $miDireccion = array("linea 1" => "Calle Mayor, 123", "linea 2" => null, "ciudad" => "Springfield", "estado" => "Vermont", "pais" => "USA"); // guardamos la direccion $direcciones->insert($miDireccion); // guardar una persona con una referencia a la direccion $yo = array("nombre" => "Fred", "direccion" => $miDireccion['_id']); $personas->insert($yo); ?>
Posteriormente podremos encontrar la direccin de la persona consultando la coleccin "direcciones" con el MongoId que almacenamos en la coleccin "personas". Supongamos ahora que tenemos un caso ms general, donde no sabemos qu coleccin (o incluso qu base de datos) contiene el documento referenciado. MongoDBRef es una buena eleccin para estos casos, ya que es un formato comn que todos los drivers y bases de datos podrn interpretar. Si cada persona tuviera una lista de cosas que les gusta, y stas pudieran venir a partir de varias colecciones, como "hobbies", "deportes", "libros", etc., podramos usar MongoDBRef para seguir la pista de con qu coleccin se asocia cada gusto:
<?php $personas = $db->selectCollection("personas"); // modelismo ferroviario est en la coleccin "hobbies" $ferroRef = MongoDBRef::create("hobbies", $modelismoFerroviario['_id']); // ftbol est en la coleccin "deportes" $futbolRef = MongoDBRef::create("deportes", $futbol['_id']);
216
// ahora, cuando consultemos el documento, sabremos a qu coleccin // pertenecen cada tem de "gustos" $personas->insert(array("nombre" => "Fred", "gustos" => array($ferroRef, $futbolRef))); ?>
Las referencias a bases de datos se pueden concebir como hipervnculos: proporcionan una direccin nica a otro documento, pero no cargan ni redirigen automticamente al enlace/referencia. Una referencia a una base de datos es un array asociativo, no una instancia de MongoDBRef, de modo que esta clase es ligeramente diferente al resto de clases de tipos de datos. Esta clase contiene nicamente mtodos estticos para poder manipular las referencias a bases de datos.
Clases sinopsis
MongoDBRef
MongoDBRef { /* Mtodos */ public static array MongoDBRef::create ( string $collection, mixed $id [, string $ database ] ) public static array MongoDBRef::get ( MongoDB $db, array $ref ) public static bool MongoDBRef::isRef ( mixed $ref ) }
Ver tambin
Documentacin de MongoDB sobre referencias a bases de datos.
217
MongoDBRef::create
MongoDBRef::create -- Crea una nueva referencia de base de datos
Descripcin
public static array MongoDBRef::create ( string $collection, mixed $id [, string $ database ] ) Si no se especifica ninguna base de datos, se utiliza la actual.
Parmetros
collection
Valores devueltos
Devuelve la referencia.
Ejemplos
Ejemplo #1 - Ejemplo de MongoDBRef::create() Crea una referencia de base de datos a un documento en la coleccin addresses. La funcin MongoCollection::getName() devuelve el nombre de la coleccin (sin incluir el nombre de la base de datos).
<?php $addresses = $db->addresses; $people = $db->people; // guardar $address para que as tenga un _id $addresses->insert($address); // creamos una referencia $ref = MongoDBRef::create($addresses->getName(), $address['_id']); // asignamos el campo a $person $person['address'] = $ref; $people->save($person); ?>
218
Ver tambin
MongoDB::createDBRef MongoCollection::createDBRef
219
MongoDBRef::get
MongoDBRef::get -- Captura el objeto al que apunta la referencia
Descripcin
public static array MongoDBRef::get ( MongoDB $db, array $ref )
Parmetros
db
Referencia a capturar.
Valores devueltos
Devuelve el documento al que referencia o NULL si el documento no existe (la referencia est rota).
Ejemplos
Ejemplo #1 - Ejemplo de MongoCollection::createDBRef()
<?php // extraemos $person de la base de datos $persona = $gente->findOne(); // obtenemos la direccin $direccion = MongoDBRef::get($gente->db, $persona['direccion']); ?>
Ver tambin
MongoDB::getDBRef MongoCollection::getDBRef
220
MongoDBRef::isRef
MongoDBRef::isRef -- Comprueba si un array es una referencia en la base de datos
Descripcin
public static bool MongoDBRef::isRef ( mixed $ref ) Esta funcin no sigue las referencias, por lo que no sirve para determinar si una referencia est o no rota. Tan solo comprueba que ref est en el formato vlido de referencias de bases de datos (objeto o array con los campos $ref y $id).
Parmetros
ref
Valores devueltos
Devulve un indicador de si ref es o no una referencia.
221
Clase MongoMinKey
Introduccin
MongoMinKey es un tipo especial de la base de datos que se evala siempre como menor que cualquier otro tipo. As, si se ordena ascendemente una consulta por un determinado campo, cualquier documento que tenga MongoMinKey como valor, ser devuelto en primera posicin. MongoMinKey no tiene ni campos, ni mtodos, ni constantes asociados. Es simplemente el valor "ms bajo" que se puede insertar en la base de datos.
Clases sinopsis
MongoMinKey
MongoMinKey { }
El cursor contendr el documento de almorzar, y despus el documento de reunin de personal. El documento de almorzar siempre ser el primero, independientemente de lo que aadamos a la coleccin (a no ser que se aadan otros documentos con MongoMinKey en el campo "hacer el").
222
Clase MongoMaxKey
Introduccin
MongoMaxKey es un tipo especial de la base de datos que se evala siempre como mayor que cualquier otro tipo. As, si se ordena ascendemente una consulta por un determinado campo, cualquier documento que tenga MongoMaxKey como valor, ser devuelto al final. MongoMaxKey no tiene ni campos, ni mtodos, ni constantes asociados. Es simplemente el valor "ms alto" que se puede insertar en la base de datos.
Clases sinopsis
MongoMaxKey
MongoMaxKey { }
El cursor contendr el documento de la reunin de personal, y despus el documento de fregar platos. El documento de fregar platos siempre ser el ltimo, independientemente de lo que aadamos a la coleccin (a no ser que se aadan otros documentos con MongoMaxKey en el campo "hacer el").
223
Clase MongoTimestamp
Introduccin
MongoTimestamp se usa para sharding (particionamiento horizontal de BD). Si no se van a usar herramientas de sharding, se recomienda usar MongoDate. MongoTimestamp es un timestamp de 4 bytes (segundos a partir de la fecha de referencia) y 4 bytes de incremento. Esta clase no es para medir tiempo, creando un timestamp en un documento o aadiendo/actualizando el timestamp de un documento. A no ser que se est usando algo que interacte con sharding, detngase, y vaya directamente a MongoDate, no est aqu de paso. sta no es la clase que est buscando. Si est escribiendo herramientas de sharding, contine.
Clases sinopsis
MongoTimestamp
MongoTimestamp { /* Campos */ public int sec = 0; public int inc = 0; /* Mtodos */ MongoTimestamp::__construct ( [ int $sec = time() [, int $inc ] ] ) public string MongoTimestamp::__toString ( void ) }
224
MongoTimestamp::__construct
MongoTimestamp::__construct -- Crea un nuevo timestamp
Descripcin
MongoTimestamp::__construct ( [ int $sec = time() [, int $inc ] ] ) Crea un nuevo timestamp. Si no se rellenan los parmetros, se usa la hora actual con incremento automtico. El incremento se establece a 0 cuando se carga el mdulo, y se incrementa cada vez que se invoca a este constructor (cuando no se rellene el parmetro $inc).
Parmetros
sec
Incremento.
Valores devueltos
Devuelve el nuevo timestamp.
Ver tambin
MongoTimestamp::__toString
225
MongoTimestamp::__toString
MongoTimestamp::__toString -- Devuelve la representacin en forma de texto de este timestamp
Descripcin
public string MongoTimestamp::__toString ( void ) Devuelve el campo "sec" del timestamp.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Los segundos desde la fecha de referencia que rerpesenta este timestamp.
226
Clases de GridFS
227
Clase MongoGridFS
Introduccin
Utilidad para almacenar y extraer ficheros de la base de datos. GridFS es una especificacin de almacenamiento que implementan todos los drivers soportados. En resumen, define dos colecciones: files, para los metadatos del fichero, y chunks, para el contenido del fichero. Si el fichero fuera de gran tamao, automticamente se dividira en porciones menores, y cada bloque se guardar como un documento en la coleccin de bloques. Cada documento de la coleccin de ficheros contiene el nombre de fichero, fecha de subida, y un cdigo hash md5. Tambin contiene un campo nico _id, que se puede utilizar para consultar el contenido del fichero en la coleccin de bloques. Cada documento de la coleccin de bloques contiene un bloque de datos binarios, un campo files_id que se corresponde con el _id de su fichero, y la posicin de este bloque respecto a los dems. Por ejemplo, el documento de ficheros podra ser algo tal que as:
<?php array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12); ?>
Por supuesto, el tamao por omisin de los bloques es en realidad de miles de bytes.
228
La Familia MongoGridFS
MongoGridFS representa los ficheros y las colecciones de bloques. MongoGridFS hereda MongoCollection. Las instancias de MongoGridFS tienen acceso a todos los mtodos de MongoCollection, que actan sobre las colecciones de ficheros:
<?php $grid = $db->getGridFS(); $grid->update(array("filename" => "foo"), $newObj); // actualizacin en la coleccin de ficheros ?>
Se puede tambin acceder a los bloques de una coleccin a partir de una instancia de MongoGridFS:
<?php $chunks = $grid->chunks; // $chunks es un MongoCollection normal $chunks->insert(array("x" => 4)); ?>
Hay algunos mtodos de MongoGridFS que comparten nombres con mtodos de MongoCollection, pero que se comportan de un modo ligeramente diferente. Por ejemplo, Driver nativo MongoDB 229
MongoGridFS::remove() eliminar cualquier objeto, junto con su contenido en la coleccin de bloques, cuando se cumplan los criterios de la coleccin de ficheros. Para almacenar cualquier otra cosa en GridFS, hay varias opciones. Si se tuviera un nombre de fichero, se podra hacer:
<?php $grid->storeFile($filename, array("cualquier" => "metadato", "que" => "desee")); ?>
Si se tuviera un string de bytes que no fuera un fichero, se podr tambien almacenar usando MongoGridFS::storeBytes():
<?php $grid->storeBytes($bytes, array("cualquier" => "metadato", "que" => "desee")); ?>
Al consultar a una coleccin MongoGridFS, se devolver un MongoGridFSCursor, que se comporta como un MongoCursor convencional, excepto que devuelve un MongoGridFSFiles en lugar de una matriz asociativa. MongoGridFSFiles puede volver a escribirse en disco usando MongoGridFSFile::write(), o en memoria usando MongoGridFSFile::getBytes(). Actualmente no existe ningn mtodo que cree automticamente un flujo de bloques, pero resulta muy sencillo hacer escrituras realizando consultas a la coleccin $grid->chunks. El objeto MongoGridFSFile contiene un campo file (fichero) que contiene cualquier metadato del fichero.
Clases sinopsis
MongoGridFS
extends MongoCollection { /* Campos */ public MongoCollection chunks = NULL; protected string filesName = NULL;
230
protected string chunksName = NULL; /* Mtodos */ MongoGridFS::__construct ( MongoDB $db [, string $prefix = "fs" [, mixed $ chunks = "fs" ] ] ) public bool MongoGridFS::delete ( mixed $id ) public array MongoGridFS::drop ( void ) public MongoGridFSCursor MongoGridFS::find ( [ array $query = array() [, array $ fields = array() ] ] ) public MongoGridFSFile MongoGridFS::findOne ( [ mixed $query = array() [, mixed $fields = array() ] ] ) public MongoGridFSFile MongoGridFS::get ( mixed $id ) public mixed MongoGridFS::put ( string $filename [, array $extra = array() ] ) public bool MongoGridFS::remove ( [ array $criteria = array() [, array $options = array() ] ] ) public mixed MongoGridFS::storeBytes ( string $bytes [, array $extra = array() [, array $options = array() ] ] ) public mixed MongoGridFS::storeFile ( string $filename [, array $extra = array() [, array $options = array() ] ] ) public mixed MongoGridFS::storeUpload ( string $name [, array $metadata ] ) }
Ver tambin
Documentacin principal de MongoDB de GridFS. Hay tambin una buena introduccin a cmo guardar datos subidos por usuarios y a cmo aadir metadatos en LightCubeSolutions.com.
231
MongoGridFS::__construct
MongoGridFS::__construct -- Crea una nueva coleccin de ficheros
Descripcin
MongoGridFS::__construct ( MongoDB $db [, string $prefix = "fs" [, mixed $chunks = "fs" ] ] ) Los ficheros se almacenan en dos colecciones. La primera contiene informacin descriptiva de los ficheros. La segunda contiene los bloques del contenido real del fichero. Por omisin, los nombres que se usan para las colecciones son fs.files y fs.chunks. Mediante un argumento puede especificar un prefijo distinto a "fs":$fs = new MongoGridFS($db, "misficheros"); esto utilizara las colecciones misficheros.files y misficheros.chunks.
Parmetros
db
Base de datos.
files
232
MongoGridFS::delete
MongoGridFS::delete -- Elimina un fichero de la base de datos
Descripcin
public bool MongoGridFS::delete ( mixed $id )
Parmetros
id
Valores devueltos
Devuelve un indicador de si la orden de eliminacin se envi o no con xito a la base de datos.
233
MongoGridFS::drop
MongoGridFS::drop -- Da de baja una coleccin de ficheros y de bloques
Descripcin
public array MongoGridFS::drop ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Respuesta de la base de datos.
234
MongoGridFS::find
MongoGridFS::find -- Selecciona ficheros
Descripcin
public MongoGridFSCursor MongoGridFS::find ( [ array $query = array() [, array $ fields = array() ] ] )
Parmetros
query
La consulta
fields
Valores devueltos
Un objeto de la clase MongoGridFSCursor.
235
MongoGridFS::findOne
MongoGridFS::findOne -- Devuelve el fichero que cumpla las condiciones
Descripcin
public MongoGridFSFile MongoGridFS::findOne ( [ mixed $query = array() [, mixed $ fields = array() ] ] )
Parmetros
query
Valores devueltos
Devuelve un MongoGridFSFile o NULL.
Ejemplos
Ejemplo #1 - Ejemplo de MongoGridFS::findOne Ejemplo que muestra cmo localizar un fichero de MongoGridFS.
<?php $descargas = $mongo->my_db->getGridFS('descargas'); $descargas->storeFile('nombredefichero.tgz'); $descarga = $downloads->findOne('nombredefichero.tgz'); // instancia de MongoGridFSFile print_r($descarga); ?>
Vea MongoGridFSFile para ms informacin sobre cmo trabajar con ficheros. El resultado del ejemplo sera algo similar a:
MongoGridFSFile Object ( [file] => Array ( [_id] => MongoId Object ( ) [filename] => nombredefichero.tgz
236
[uploadDate] => MongoDate Object ( [sec] => 1274288014 [usec] => 467000 ) [chunkSize] => 262144 [md5] => d41d8cd98f00b204e9800998ecf8427e ) [gridfs:protected] => MongoGridFS Object ( [chunks] => MongoCollection Object ( ) [filesName:protected] => descargas.files [chunksName:protected] => descargas.chunks ) )
237
MongoGridFS::get
MongoGridFS::get -- Obtiene un fichero de la base de datos
Descripcin
public MongoGridFSFile MongoGridFS::get ( mixed $id )
Parmetros
id
Valores devueltos
Devuelve el fichero si se le encuentra, o NULL.
238
MongoGridFS::put
MongoGridFS::put -- Almacena un fichero en la base de datos
Descripcin
public mixed MongoGridFS::put ( string $filename [, array $extra = array() ] )
Parmetros
filename
Valores devueltos
Devuelve el _id del objeto guardado.
239
MongoGridFS::remove
MongoGridFS::remove -- Elimina ficheros de las colecciones
Descripcin
public bool MongoGridFS::remove ( [ array $criteria = array() [, array $options = array() ] ] )
Parmetros
query
Opciones para la eliminacin. Las opciones vlidas son: "safe" Comprobar que la eliminacin ha tenido xito.
Valores devueltos
Devuelve un indicador sobre si la eliminacin se envi o no con xito a la base de datos.
240
MongoGridFS::storeBytes
MongoGridFS::storeBytes -- Fragmenta y almacena bytes en la base de datos
Descripcin
public mixed MongoGridFS::storeBytes ( string $bytes [, array $extra = array() [, array $options = array() ] ] )
Parmetros
bytes
Valores devueltos
El _id del objeto guardado.
Errores/Excepciones
Lanza MongoCursorException si se estableci la opcin "safe" y la insercin falla.
241
MongoGridFS::storeFile
MongoGridFS::storeFile -- Almacena un fichero en la base de datos
Descripcin
public mixed MongoGridFS::storeFile ( string $filename [, array $extra = array() [, array $options = array() ] ] )
Parmetros
filename
Valores devueltos
Devuelve el _id del objeto guardado.
Errores/Excepciones
Lanza MongoCursorException si la opcin "safe" est establecida y la insercin falla.
242
MongoGridFS::storeUpload
MongoGridFS::storeUpload -- Guarda en la base de datos un fichero subido
Descripcin
public mixed MongoGridFS::storeUpload ( string $name [, array $metadata ] ) Almacena los archivos directamente desde un POST a la base de datos. Por ejemplo, suponga que tiene el siguiente formulario HTML:
<form method="POST" enctype="multipart/form-data"> Por favor, sube una imagen de perfil: <input type="file" name="pic"/> <input type="submit"/> </form>
Tenga en cuenta que el campo "name" en HTML coincide con el parmetro name.
Parmetros
name
Valores devueltos
Devuelve el _id del archivo cargado.
Historial de cambios
Versin 1.2.5
Descripcin Cambiado el segundo parmetro a un array de metadatos. Antes de la versin 1.2.5, el segundo parmetro fue un string opcional reemplazando el nombre de archivo. 243
Clase MongoGridFSFile
Introduccin
Objeto fichero de una base de datos.
Clases sinopsis
MongoGridFSFile
MongoGridFSFile { /* Campos */ public array file = NULL; protected MongoGridFS gridfs = NULL; /* Mtodos */ MongoGridfsFile::__construct ( MongoGridFS $gridfs, array $file ) public string MongoGridFSFile::getBytes ( void ) public string MongoGridFSFile::getFilename ( void ) public int MongoGridFSFile::getSize ( void ) public int MongoGridFSFile::write ( [ string $filename = NULL ] ) }
244
MongoGridfsFile::__construct
MongoGridfsFile::__construct -- Crea un nuevo fichero GridFS
Descripcin
MongoGridfsFile::__construct ( MongoGridFS $gridfs, array $file )
Parmetros
gridfs
Valores devueltos
Devuelve un nuevo MongoGridFSFile.
245
MongoGridFSFile::getBytes
MongoGridFSFile::getBytes -- Devuelve el contenido de este fichero en forma de string de bytes
Descripcin
public string MongoGridFSFile::getBytes ( void ) Aviso: se cargar el fichero en memoria. Si el fichero es de mayor tamao que la memoria, provocar un problema.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve un string con los bytes del fichero.
Ejemplos
Ejemplo #1 - Ejemplo de MongoGridFSFile::getBytes
<?php $images = $db->my_db->getGridFS('images'); $image = $images->findOne('jwage.png'); header('Content-type: image/png;'); echo $image->getBytes(); ?>
246
MongoGridFSFile::getFilename
MongoGridFSFile::getFilename -- Devuelve el nombre de este fichero
Descripcin
public string MongoGridFSFile::getFilename ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nombre de fichero.
247
MongoGridFSFile::getSize
MongoGridFSFile::getSize -- Devuelve el tamao de este fichero
Descripcin
public int MongoGridFSFile::getSize ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el tamao de este fichero
248
MongoGridFSFile::write
MongoGridFSFile::write -- Escribe este fichero en disco
Descripcin
public int MongoGridFSFile::write ( [ string $filename = NULL ] )
Parmetros
filename
La ubicacin en la que se escribir el fichero. Si no se da ninguno, se usar el nombre del fichero almacenado.
Valores devueltos
Devuelve el nmero de bytes escritos.
Ejemplos
Ejemplo #1 - Ejemplo de MongoGridFSFile::write
<?php $images = $db->my_db->getGridFS('images'); $image = $images->findOne('jwage.png'); $image->write('/path/to/write/jwage.png'); ?>
249
Clase MongoGridFSCursor
Introduccin
Cursor para los resultados de ficheros de bases de datos.
Clases sinopsis
MongoGridFSCursor
extends MongoCursor { /* Campos */ protected MongoGridFS gridfs = NULL; /* Mtodos */ MongoGridFSCursor::__construct ( MongoGridFS $gridfs, resource $connection, string $ns, array $query, array $fields ) public MongoGridFSFile MongoGridFSCursor::current ( void ) public MongoGridFSFile MongoGridFSCursor::getNext ( void ) public string MongoGridFSCursor::key ( void ) }
250
MongoGridFSCursor::__construct
MongoGridFSCursor::__construct -- Crea un nuevo cursor
Descripcin
MongoGridFSCursor::__construct ( MongoGridFS $gridfs, resource $connection, string $ns, array $query, array $fields )
Parmetros
gridfs
Valores devueltos
Devuelve el nuevo cursor.
251
MongoGridFSCursor::current
MongoGridFSCursor::current -- Devuelve el fichero actual
Descripcin
public MongoGridFSFile MongoGridFSCursor::current ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Fichero actual.
252
MongoGridFSCursor::getNext
MongoGridFSCursor::getNext -- Devuelve el siguiente fichero al que apunta este cursor, y avanza el cursor
Descripcin
public MongoGridFSFile MongoGridFSCursor::getNext ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el siguiente fichero.
253
MongoGridFSCursor::key
MongoGridFSCursor::key -- Devuelve el nombre de fichero del resultado actual
Descripcin
public string MongoGridFSCursor::key ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Nombre de fichero del resultado actual.
254
Miscelnea
255
Clase MongoLog
Introduccin
Se puede utilizar para obtener informacin detallada sobre qu est realizando el driver. Con PHP-CLI, los informes se pueden redirigir a stderr. En un servidor de aplicaciones, los mensajes generalmente se imprimiran en un registro de errores. Por omisin, estos registros estn deshabilitados. Esta clase permite habilitar niveles especficos de informes para determinadas reas del driver. Algunos ejemplos:
<?php // muestra todos los mensajes posibles MongoLog::setLevel(MongoLog::ALL); // todos los niveles de registros MongoLog::setModule(MongoLog::ALL); // todas las partes del driver // muestra eventos significativos sobre fallos en conjuntos de rplicas MongoLog::setLevel(MongoLog::INFO); MongoLog::setModule(MongoLog::RS); // muestra registros de nivel de informacin y de seguimiento sobre conjuntos de rplicas y sobre agrupamientos de conexiones MongoLog::setLevel(MongoLog::INFO|MongoLog::TRACE); MongoLog::setModule(MongoLog::RS|MongoLog::POOL); ?>
Clases sinopsis
MongoLog
MongoLog { /* Constantes */ const int MongoLog::NONE; const int MongoLog::ALL; constantes de niveles { const int MongoLog::WARNING; const int MongoLog::INFO;
256
const int MongoLog::FINE; constantes de mdulos { const int MongoLog::RS; const int MongoLog::POOL; const int MongoLog::IO; /* Campos */ public int level; public int module; /* Mtodos */ MongoDate::__construct ( [ int $sec = time() [, int $usec = 0 ] ] ) public string MongoDate::__toString ( void ) }
Muestra la mayor parte de eventos que realiza el driver. Dependiendo del mdulo que se est analizando, este nivel podra ser demasiado ruidoso. Se usa principalmente para depuracin.
258
MongoLog::getLevel
MongoLog::getLevel -- Obtiene el nivel de registro
Descripcin
public static int MongoLog::getLevel ( void ) Esto puede ser usado para ver el nivel de registro. Utilice las constantes descritas en la seccin MongoLog con los operadores bit a bit para comprobar el nivel.
<?php if (MongoLog::getLevel() & MongoLog::FINE) { echo "un montn de logs\n"; } if (MongoLog::getLevel() ^ MongoLog::NONE) { echo "logging, al menos un poco\n"; } if (MongoLog::getLevel() == MongoLog::ALL) { echo "logging al ms alto nivel\n"; } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve el nivel actual.
259
MongoLog::getModule
MongoLog::getModule -- Devuelve los mdulos que estn actualmente se estn registrando
Descripcin
public static int MongoLog::getModule ( void ) Esta funcin se puede usar para conocer qu partes del driver se estn registrando. Utilice las constantes descritas en la seccin de MongoLog con operadores a nivel de bits para comprobar si algn mdulo especfico est siendo registrado.
<?php if (MongoLog::getModule() & MongoLog::RS) { echo "registrando conjuntos de rplicas\n"; } if (MongoLog::getModule() ^ MongoLog::NONE) { echo "registrando algo\n"; } if ((MongoLog::getModule() & MongoLog::IO) == 0) { echo "no se estn registrando entradas/salidas\n"; } ?>
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Devuelve los mdulos que actualmente se estn registrando.
260
MongoLog::setLevel
MongoLog::setLevel -- Establece el nivel de informe de mensajes
Descripcin
public static void MongoLog::setLevel ( int $level ) Esta funcin se puede usar para establecer el nivel de detalles que se mostrarn, as como el tipo de informacin que se registrar. Utilice las constantes descritas en la seccin MongoLog con operadores a nivel de bits para especificar estos niveles.
<?php // primero, habilitamos todos los mensajes para un mdulo MongoLog::setModule(MongoLog::POOL);
// registramos los mensajes de todos los niveles MongoLog::setLevel(MongoLog::ALL); // registramos mensaje de tipo 'aviso' e informativos MongoLog::setLevel(MongoLog::WARNING|MongoLog::INFO); // registramos todo, excepto actividades de grano fino MongoLog::setLevel(MongoLog::ALL & (~MongoLog::FINE)); ?>
Tenga presente que tambin puede llamar a MongoLog::setModule() para escoger qu partes del driver registrar.
Parmetros
level
261
MongoLog::setModule
MongoLog::setModule -- Establece de qu funcionalidades se deben notificar eventos
Descripcin
public static void MongoLog::setModule ( int $module ) Esta funcin puede usarse para establecer de qu partes del driver se deben registrar eventos. Para especificar los mdulos, utilice las constantes descritas en la seccin MongoLog con operadores a nivel de bits.
<?php // primero, habilitamos todos los niveles de registro MongoLog::setLevel(MongoLog::ALL);
// registramos las actividades de conjuntos de rplicas MongoLog::setModule(MongoLog::RS); // registramos las actividades de conjuntos de rplicas y de agrupamientos de conexiones MongoLog::setModule(MongoLog::RS|MongoLog::ALL); // registramos todo excepto actividades de E/S MongoLog::setModule(MongoLog::ALL & (~MongoLog::IO)); ?>
Tenga presente que tambin se puede invocar a MongoLog::setLevel() para habilitar el registro de mensajes.
Parmetros
module
262
Clase MongoPool
Introduccin
En la versin 1.2.0 del driver se incorporaron los agrupamiento (pools) de conexiones. Esta clase ofrece herramientras de control e informacin sobre agrupamientos.
Nota Originalmente, las funciones de esta clase eran miembros estticos de Mongo. Se recomienda encarecidamente utilizar esta clase en un futuro, ya que las funciones estticas de Mongo estn consideradas obsoletas.
Clases sinopsis
MongoPool
MongoPool { /* Mtodos */ public static int MongoPool::getSize ( void ) public array MongoPool::info ( void ) public static bool MongoPool::setSize ( int $size ) }
263
MongoPool::getSize
MongoPool::getSize -- Devuelve el tamao actual de un agrupamiento de conexiones
Descripcin
public static int MongoPool::getSize ( void )
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Retorna el tamao actual del agrupamiento.
Ejemplos
Ejemplo #1 - Cambiar el tamao de un agrupamiento Devuelve el tamao por omisin del agrupamiento, esatblece un nuevo tamao, y muestra el nuevo tamao junto con informacin de depuracin. Tenga presente que esta accin slo afecta a las nuevas conexiones; no modifica las anteriores.
<?php $connection = new Mongo("host1"); // tamao de agrupamiento: -1 echo "tamao de agrupamiento: ".MongoPool::getSize()."\n"; echo "establecemos un tamao de agrupamiento de 200\n"; MongoPool::setSize(200); // tamao de agrupamiento: 200 echo "tamao de agrupamiento: ".MongoPool::getSize()."\n"; $conn2 = new Mongo("host2"); // conexiones disponibles en host1: -2 // conexiones disponibles en host2: 199 var_dump(Mongo::poolDebug()); ?>
Ver tambin
Driver nativo MongoDB 264
265
MongoPool::info
MongoPool::info -- Devuelve informacin sobre todos los agrupamientos de conexiones
Descripcin
public array MongoPool::info ( void ) Devuelve un array con informacin sobre los agrupamientos de conexiones.
Parmetros
Esta funcin no tiene parmetros.
Valores devueltos
Cada agrupamiento de conexin tiene un identificador, que comienza con el nombre de host. Se muestra la siguiente informacin para cada agrupamiento:
in use
Nmero de conexiones que se pueden crear en este agrupamiento. Por ejemplo, supongamos que un agrupamiento tena 5 conexiones pendientes y 3 conexiones en agrupamiento. Podramos crear 8 nuevas instancias de Mongo antes de agotar este agrupamiento (asumiendo que ninguna instancia de Mongo qued fuera de mbito, devolviendo sus conexiones al agrupamiento). Un nmero negativo indica que este agrupamiento puede lanzar conexiones ilimitadas. Antes de crear un agrupamiento, se puede cambiar su nmero mximo de conexiones invocando a Mongo::setPoolSize(). Una vez que se ha llamado a esta funcin, no se podr modificar su tamao.
total
Nmero total de conexiones permitidas en este agrupamiento. Ser mayor o igual a la suma de "in use" + "in pool" (o -1).
timeout
Tiempo mximo de espera para las conexiones de este agrupamiento. Indica por cunto tiempo las conexiones intentarn conectar con un servidor antes de darse por vencidas.
waiting
Si se ha restringido el tamao del agrupamiento, los procesos que soliciten conexiones de este agrupamiento podrn quedarse bloqueados hasta que otros procesos devuelvan sus conexiones. Este campo indica por cuntos Driver nativo MongoDB 266
milisegundos quedarn bloqueados esperando a que se libere una conexin. Si este nmero creciera demasiado, quizs sea conveniente usar MongoPool::setSize() para aadir ms conexiones al agrupamiento.
267
MongoPool::setSize
MongoPool::setSize -- Establece el tamao de los nuevos agrupamientos de conexiones
Descripcin
public static bool MongoPool::setSize ( int $size ) Establece el nmero mximo de conexiones que podrn crear los nuevos agrupamientos.
Parmetros
size
Nmero mximo de conexiones que podrn crear los nuevos agrupamientos. Un nmero negativo indica que el agrupamiento podr lanzar un nmero infinito de conexiones.
Valores devueltos
Devuelve el valor anterior de tamao de agrupamiento.
Ejemplos
Ejemplo #1 - Ejemplo de Mongo::setPoolSize() Si se establece un tamao de agrupamiento de n y creamos n conexiones, al intentar crear la conexin n+1 se lanzar una excepcin de tipo MongoConnectionException.
<?php // slo permitimos una conexin al servidor MongoPool::setSize(1); // creamos una conexin a localhost:27017 $m1 = new Mongo(); // intentamos crear una segunda conexin a localhost:27017 // puesto que slo se permite una, se emitir una excepcin $m2 = new Mongo(); ?>
268
Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10 Stack trace: #0 /path/to/php/script.php(10): Mongo->__construct() #1 {main} thrown in /path/to/php/script.php on line 10
Ver tambin
269
Funciones
270
Funciones de Mongo
271
bson_decode
bson_decode -- Decodifica un objecto BSON a un array PHP
Descripcin
array bson_decode ( string $bson ) Esta funcin es muy beta todava y es intil para el 99% de usuarios. Solo es til en casos especiales, como cuando se necesita escribir tu propio driver encima del driver de PHP.
Parmetros
bson
Valores devueltos
Devuelve un objecto BSON decodificado.
272
bson_encode
bson_encode -- Serializa una variable PHP a un string BSON
Descripcin
string bson_encode ( mixed $anything ) Esta funcin es muy beta todava y es intil para el 99% de usuarios. Solo es til en casos especiales, como cuando se necesita escribir tu propio driver encima del driver de PHP.
Parmetros
anything
La variable ha serializar.
Valores devueltos
Devuelve un string serializado.
273
Excepciones
Peculiaridades en VMWare
Si se est ejecutando VMWare en Windows, y se usa CIFS, al pausar la mquina virtual se desincronizar CIFS causando errores inesperados al volver a ponerlo en funcionamiento ("El objeto Mongo no se ha inicializado correctamente por su constructor"). Si se monta de forma permanente los compartidos de Windows, se corregir este problema y ya se podr pausar y reiniciar. Para montar permanentemente los compartidos de Windows, ejecute:
$ sudo update-rc.d -f umountnfs.sh remove $ sudo update-rc.d umountnfs.sh stop 15 0 6 .
274
Clase MongoException
Introduccin
Excepcin Mongo predeterminada. Abarca un gran nmero de condiciones de error que, eventualmente, podrn moverse a excepciones ms especficas, pero que en cualquier caso siempre extendern MongoException.
The MongoSomething object has not been correctly initialized by its constructor Cdigo: 0 Probablemente tu objeto Mongo no est conectado al servidor de bases de datos. zero-length keys are not allowed, did you use $ with double quotes? Cdigo: 1 Se ha intentado guardar el valor "" como clave. En general, no se debe hacer esto. "" podra provocar errores al acceder a subobjetos, adems de que es usado internamente por MongoDB. Sin embargo, si realmente quiere, puede asignar en su fichero php.ini el valor true a mongo.allow_empty_keys para sobrescribir esta comprobacin. Si se sobrescribe, se recomienda encarecidamente establecer la comprobacin estricta de errores para evitar errores de interpolacin de textos. '.' not allowed in key: <key> Cdigo: 2 Se ha intentado escribir una clave que contiene un ".", lo cual est prohibido. insert too large: <size>, max: <max> Cdigo: 3 Se ha intentado enviar demasiada informacin de una vez a la base de datos: la base de datos slo acepta inserciones de hasta un determinado tamao (actualmente 16 MB). no elements in doc Cdigo: 4 Se ha intentado guardar un documento que no contiene ningn campo. size of BSON doc is <size> bytes, max <max>MB Cdigo: 5 Se ha intentado guardar un documento con un tamao superior al que MongoDB puede guardar. no documents given Cdigo: 6 Se ha intentado insertar por lotes un array vaco de documentos. MongoCollection::group takes an array, object, or MongoCode key Cdigo: 7 Se han enviado a MongoCollection::group() parmetros del tipo equivocado field names must be strings Cdigo: 8 Deben formatearse los selectores de la siguiente forma: array("field1" => 1, "field2" => 1, ..., "fieldN" => 1). invalid regex Cdigo: 8 La expresin regular pasada a MongoRegex no cumple la forma correcta. MongoDBRef::get: $ref field must be a string Cdigo: 10 MongoDBRef::get: $db field must be a string Cdigo: 11 Driver nativo MongoDB 275
non-utf8 string: <str> Cdigo: 12 Sucede cuando se intenta enviar un texto que no es utf8 a la base de datos. Todos los textos que se enven a la base de datos deben estar en UTF8. Revise las opciones de php.ini para conocer la opcin de transicin que evita esta excepcin. mutex error: <err> Cdigo: 13 En entornos multihebra, el driver utiliza mutex para sincronizar las peticiones y las respuestas. Este es un error crtico que no se puede trazar. Es poco usual y debe notificarse a los mantenedores junto con cualquier informacin del sistema y los pasos que se han seguido para reproducir el error. index name too long: <len>, max <max> characters Cdigo: 14 No se crearn ndices con nombres superiores a 128 caracteres. Si se obtuviera este error, se debera usar la opcin "name" de MongoCollection::ensureIndex() para crear un nombre ms corto para el ndice.
Clases sinopsis
MongoException
extends Exception { }
276
Introduccin
Caused by accessing a cursor incorrectly or a error receiving a reply. Note that this can be thrown by any database request that receives a reply, not just queries. Writes, commands, and any other operation that sends information to the database and waits for a response can throw a MongoCursorException. The only exception is new Mongo() (creating a new connection), which will only throw MongoConnectionException s. This returns a specific error message to help diagnose the problem and a numeric error code associated with the cause of the exception. For example, suppose you tried to insert two documents with the same _id:
<?php try { $collection->insert(array("_id" => 1), array("safe" => true)); $collection->insert(array("_id" => 1), array("safe" => true)); } catch (MongoCursorException $e) { echo "error message: ".$e->getMessage()."\n"; echo "error code: ".$e->getCode()."\n"; } ?>
Note that the MongoDB error code (11000) is used for the PHP error code. The PHP driver uses the "native" error code wherever possible. The following is a list of common errors, codes, and causes. Exact errors are in italics, errors where the message can vary are described in obliques.
cannot modify cursor after beginning iteration Code: 0 You are calling a method that sets up the query after executing the query. Reset the cursor and try again. An example:
<?php try { $cursor = $collection->find(); var_dump($cursor->getNext()); // getNext() queried the database, it's too late to set a limit $cursor->limit(1); } catch (MongoCursorException $e) {
277
echo "error message: ".$e->getMessage()."\n"; echo "error code: ".$e->getCode()."\n"; } // this will work, though: $cursor->getNext(); $cursor->reset(); $cursor->limit(1); ?>
Get next batch send errors Code: 1 Could not send the query to the database. Make sure the database is still up and the network is okay. cursor not found Code: 2 The driver was trying to fetch more results from the database, but the database did not have a record of the query. This usually means that the cursor timed out on the server side: after a few minutes of inactivity, the database will kill a cursor (see MongoCursor::immortal() for information on preventing this). An example:
<?php try { $cursor = $collection->find(); $cursor->getNext(); // sleep for 15 minutes sleep(60*15); while ($cursor->hasNext()) { $cursor->getNext(); } } catch (MongoCursorException $e) { echo "error message: ".$e->getMessage()."\n"; echo "error code: ".$e->getCode()."\n"; } ?>
cursor->buf.pos is null Code: 3 This may indicate you are out of RAM or some other extraordinary circumstance. couldn't get response header Code: 4 A common error if the database or network goes down. This means that the driver couldn't get a response from the connection. no db response Code: 5 This may not even be an error, for example, the database command "shutdown" returns no response. However, if you were expecting a response, this means the database didn't give one. bad response length: %d, did the db assert? Code: 6 This means that the database said that its response was less than 0. This error probably indicates a network error or database corruption. incomplete header Code: 7 Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem.
278
incomplete response Code: 8 Highly unusual. Occurs if the database response started out correctly, but broke off in the middle. Probably indicates a network problem. couldn't find a response Code: 9 If the response was cached and now cannot be located. error getting socket Code: 10 The socket was closed or encountered an error. The driver should automatically reconnect (if possible) on the next operation. couldn't find reply, please try again Code: 11 The driver saves any database responses it cannot immediately match with a request. This exception occurs if the driver has already passed your request's response and cannot find your response in its cache. error getting database response: errstr WSA error getting database response: errstr "errstr" is an io error reported directly from the C socket subsystem. On Windows, the error message is prefixed with "WSA". Timeout error Code: 13 If there was an error while waiting for a query to complete. couldn't send query: <various> Code: 14 C socket error on send. max number of retries exhausted, couldn't send query Code: 19 The driver will automatically retry "plain" queries (not commands) a couple of times if the first attempt failed for certain reasons. This is to cause fewer exceptions during replica set failover (although you will probably still have to deal with some) and gloss over transient network issues. This can also be caused by the driver not being able to reconnect at all to the database (if, for example, the database is unreachable). Version 1.2.2+.
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
279
MongoCursorException
extends MongoException { }
280
Clase MongoCursorTimeoutException
Introduccin
Lanzado cuando se excede el tiempo mximo de espera de una consulta. Puede establecer el tiempo de espera que se usar antes de lanzar esta excepcin, llamando a MongoCursor::timeout() en el cursor, o mediante MongoCursor::$timeout. Esta variable esttica resulta til para consultas tales como comandos de la base de datos o en MongoCollection::findOne(), las cuales utilizan implcitamente cursores.
Clases sinopsis
MongoCursorTimeoutException
extends MongoCursorException { }
281
Clase MongoConnectionException
Introduccin
Lanzado cuando falla el driver al conectar a la base de datos. Existen varios mensajes de error posibles para ayudar a diagnosticar el problema de conexin:
No server name given. Este error ocurre al pasar "" como nombre de servidor, probablemente por error tipogrfico con interpolacin de strings, p.ej., "$servr" en lugar de "$server". failed to get host [hostname] or port [portnum] from [server]. Indica que el nombre del servidor est malformado. "[hostname"] y "[portnum]" sern lo que el driver haya descifrado que sean. Operation in progress Superado el tiempo de espera de conexin a la base de datos. Transport endpoint is not connected Generalmente indica que la cadena de conexin no es correcta. De hecho, el driver no puede ni encontrar el servidor de bases de datos. couldn't determine master Ninguno de los servidores de la conexin parece ser el maestro. couldn't get host info for [server] Indica que el DNS no puede resolver la direccin de servidor proporcionada. Posiblemente se trate de un error tipogrfico, por ejemplo, "server" en lugar de "$server". Invalid Argument Puede provocarse al intentar conectar a una mquina que est funcionando pero la base de datos no est funcionando. Asegrese de que ha iniciado la base de datos antes de conectar. Permission denied Significa que el socket no pudo ser abierto debido a los permisos. En las variantes de Red hat, puede ser debido a que la configuracin por defecto no permite a Apache crear conexiones de red. Puede modificarse esto ejecutando:
$ /usr/sbin/setsebool -P httpd_can_network_connect 1
y reiniciando Apache. Si el mensaje de error no se encuentra en la lista de arriba, probablemente sea un error del socket C, y podr buscar en la web la causa del mismo.
Clases sinopsis
282
MongoConnectionException
extends MongoException { }
283
Clase MongoGridFSException
Introduccin
Lanzado cuando hay errores al leer o escribir ficheros a la base de datos.
Clases sinopsis
MongoGridFSException
extends MongoException { }
284