Tutorial
&mongo.deprecated.note;
Este es el controlador oficial de MongoDB para PHP.
Lo siguiente es una muestra de código que conecta, inserta documentos, consulta a
documentos, itera sobre resultados de consultas, y desconecta de MongoDB.
Hay más detalles de cada paso del tutorial más abajo.
comedy;
// seleccionar una colección (equivalente a una tabla en una base de datos relacional)
$colección = $bd->cartoons;
// añadir un registro
$documento = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );
$colección->insert($documento);
// añadir un nuevo registro, con un distinto "perfil"
$documento = array( "title" => "XKCD", "online" => true );
$colección->insert($documento);
// encontrar todo lo que haya en la colección
$cursor = $colección->find();
// recorrer el resultado
foreach ($cursor as $documento) {
echo $documento["title"] . "\n";
}
?>
]]>
&example.outputs;
Estableciendo una Conexión
Para conectar al servidor de bases de datos, utilice alguna de las siguientes formas:
]]>
No es necesario desconectar explícitamente de la base de datos. El controlador usa
conexiones persistentes y reutilizará las conexiones ya establecidas.
Ver también
El capítulo connecting
cubre los distintos tipos de conexiones.
Tanto la documentación de la API de la clase MongoClient como
MongoClient::__construct proporcionan un exhaustivo repaso a todas
las opciones disponibles, y un gran número de ejemplos.
Obteniendo una Base de Datos
Para seleccionar una base de datos, utilice.
dbname;
?>
]]>
La base de datos no debe necesariamente haber sido ya creada, sino que
pueden crearse con sólo seleccionarlas.
¡Tenga cuidado con los errores tipográficos! Podría, por inadvertencia, crear una
nueva base de datos, provocando errores (aquí, name está mal escrito
como anme en la segunda selección:
mybiglongdbname;
// hacemos algo
$bd = $conexión->mybiglongdbanme;
// ¡ahora estamos conectando a una nueva base de datos!
?>
]]>
Ver También
La documentación API de la clase MongoDB contiene más
información sobre los objetos de bases de datos.
Obteniendo Una Colección
Para obtener una conexión se utiliza la misma sintaxis que para obtener una base de datos:
baz;
// seleccionar una colección:
$colección = $bd->foobar;
// o, directamente una base de datos y una colección:
$colección = $conexión->baz->foobar;
?>
]]>
Las colecciones son análogos a las tablas (para aquéllos que estén
familiarizados con bases de datos relacionales).
Ver También
La documentación API de la clase MongoCollection contiene más
información sobre objetos de colecciones.
Insertando un Documento
Los objetos básicos para almacenar en una colección de una base de datos son los
arrays asociativos. Un "documento" cualquiera podría ser:
"MongoDB",
"type" => "database",
"count" => 1,
"info" => (object)array( "x" => 203, "y" => 102),
"versions" => array("0.9.7", "0.9.8", "0.9.9")
);
?>
]]>
Observe que se pueden tener arrays y objetos anidados. El controlador siempre
almacenará un array asociativo como un objeto en la base de datos. Un array
indexado numéricamente es almacenado como un array en caso de que las claves empiecen en
0 y no estén interrumpidas, y como un objeto si las claves del array no empiezan
en 0 o tienen huecos (esto es: 0, 1, 4, 5).
Para insertar este documento, utilice MongoCollection::insert:
database->collectionName;
$colección->insert( $doc );
?>
]]>
Ver También
La documentación API de MongoCollection::insert
contiene más información sobre la inserción de datos.
Localizando documentos usando <function>MongoCollection::findOne</function>
Para comprobar que el documento que insertamos en el paso anterior está almacenado en
la base de datos, podemos realizar una operación
MongoCollection::findOne para obtener un único
documento de la colección. Este método es útil cuando sólo hay un documento que
concuerde con la consulta, o cuando sólo se está interesado en un resultado.
database->collectionName;
$documento = $colección->findOne();
var_dump( $documento );
?>
]]>
&example.outputs;
object(MongoId)#8 (1) {
["$id"]=>
string(24) "4e2995576803fab768000000"
}
["name"]=>
string(7) "MongoDB"
["type"]=>
string(8) "database"
["count"]=>
int(1)
["info"]=>
array(2) {
["x"]=>
int(203)
["y"]=>
int(102)
}
["versions"]=>
array(3) {
[0]=>
string(5) "0.9.7"
[1]=>
string(5) "0.9.8"
[2]=>
string(5) "0.9.9"
}
}
]]>
Hay un campo _id que se ha añadido
automáticamente al documento. _id es el campo de la
"clave primaria". Si el documento no especifica una, el controlador la añadirá
automáticamente.
Si se ha especificado un campo _id, debe ser único en toda
la colección. Por ejemplo:
database;
$bd->foo->insert(array("_id" => 1));
// esto lanzará una excepción
$bd->foo->insert(array("_id" => 1));
// esto está bien, ya que es una colección diferente
$bd->bar->insert(array("_id" => 1));
?>
]]>
Por omisión, el controlador se asegurará de que el servidor ha aceptado la escritura
antes de devolver. Opcionalmente se puede desactivar este comportamiento pasando
array("w" => 0) como segundo argumento. Esto significa que
el controlador debería no esperar a que la base de datos acepte la escritura y
no lanzar la excepción de _id duplicado.
Ver TambiénMongoCollection::findOne
contiene más información sobre cómo localizar datos.
MongoId ofrece más detalles de los identificadores únicos.
La sección writes trata
las escrituras en mayor profundidad, y el capítulo
entra en detalles sobre las diferentes opciones de Write Concern.
Añadiendo Múltiples Documentos
Para hacer más interesante el tema de las consultas, vamos a añadir
varios documentos a la colección. Estos documentos serán simplemente de la forma
array( "i" => value ); y podemos
hacerlo de un modo muy eficiente en un bucle:
database->collectionName;
for ( $i = 0; $i < 100; $i++ )
{
$colección->insert( array( 'i' => $i, "field{$i}" => $i * 2 ) );
}
?>
]]>
Tenga en cuenta que podemos insertar en una misma colección arrays
con claves diferentes. A esta característica nos referimos cuando decimos que MongoDB
es independiente de esquemas. En el ejemplo de arriba cada documento tiene un
campo i, aunque también un nombre de campo en la forma
field + $i.
Contando los Documentos de una Colección
Ahora que hemos insertado 101 documentos (los 100 del bucle, junto con el
primero), podemos comprobar si los tenemos todos usando el método
MongoCollection::count.
database->collectionName;
echo $colección->count();
?>
]]>
y debería mostrar 101.
Usando un Cursor para Obtener Todo de los Documentos
Para obtener todos los documentos, usaremos
MongoCollection::find. El método find() devuelve un objeto
MongoCursor que nos permite recorrer el conjunto de documentos
que concuerdan con nuestra consulta. De ese modo, para consultar todos los documentos
y mostrarlos por pantalla:
database->collectionName;
$cursor = $colección->find();
foreach ( $cursor as $id => $valor )
{
echo "$id: ";
var_dump( $valor );
}
?>
]]>
y mostrará los 101 documentos de la colección.
$id es el campo _id del documento
(transformado a string) y $valor es el documento en sí.
Ver También
La documentación API de MongoCollection::find
contiene más información sobre cómo localizar datos.
Estableciendo el Criterio de la Consulta
Podemos crear una consulta para pasar al método
MongoCollection::find y así obtener un subconjunto de documentos
de nuestra colección. Por ejemplo, si quisiéramos encontrar el documento cuyo valor en el
campo "i" es 71,
haríamos lo siguiente:
database->collectionName;
$consulta = array( 'i' => 71 );
$cursor = $colección->find( $consulta );
while ( $cursor->hasNext() )
{
var_dump( $cursor->getNext() );
}
?>
]]>
&example.outputs;
object(MongoId)#6 (0) {
}
["i"]=>
int(71)
["_ns"]=>
"testCollection"
}
]]>
Consultando un Conjunto de Documentos con una Consulta
Podemos usar la consulta para obtener un conjunto de documentos de nuestra colección. Por ejemplo,
si quisiéramos obtener todos los documentos en los que "i"
> 50, podríamos poner:
database->collectionName;
$consulta = array( "i" => array( '$gt' => 50 ) ); // observar las comillas simples de '$gt'
$cursor = $colección->find( $consulta );
while ( $cursor->hasNext() )
{
var_dump( $cursor->getNext() );
}
?>
]]>
lo cual mostraría los documentos en que "i" >
50. Podemos también consultar un rango, digamos
20 < i <= 30:
database->collectionName;
$consulta = array( 'i' => array( '$gt' => 20, "\$lte" => 30 ) );
$cursor = $colección->find( $consulta );
while ( $cursor->hasNext() )
{
var_dump( $cursor->getNext() );
}
?>
]]>
Recuerde escapar siempre el símbolo $ o utilizar comillas simples. Si no, PHP
lo interpretará como la variable $gt.
Creando un Índice
MongoDB soporta índices, y es muy fácil añadirlos a una colección. Para
crear un Índice, debe indicar el nombre del campo y la dirección: ascendente (1) o
descendente (-1). A continuación, creamos un índice ascendente en el campo "i":
database->collectionName;
$colección->ensureIndex( array( "i" => 1 ) ); // crear un índice en "i"
$colección->ensureIndex( array( "i" => -1, "j" => 1 ) ); // índice de "i" descendente, "j" ascendente
?>
]]>
A medida que los datos crecen, la indexación se vuelve crítica para un buen rendimiento de lectura. Si no está
familiarizado con las indexaciones, revise la documentación de
MongoCollection::ensureIndex y l a
documentación de indexación de MongoDB.