mirror of
https://github.com/php/doc-es.git
synced 2026-03-25 16:02:13 +01:00
5addbf1f6c
git-svn-id: https://svn.php.net/repository/phpdoc/es/trunk@338156 c90b9560-bf6c-de11-be94-00142212c4b1
579 lines
17 KiB
XML
579 lines
17 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: b2357fc62a4d09fa67bb7f4f022ddb68091d61c0 Maintainer: seros Status: ready -->
|
|
<!-- Reviewed: no -->
|
|
|
|
<chapter xml:id="mongo.tutorial" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Tutorial</title>
|
|
<warning>
|
|
&mongo.deprecated.note;
|
|
</warning>
|
|
<para>
|
|
Este es el controlador oficial de MongoDB para PHP.
|
|
</para>
|
|
<para>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.
|
|
</para>
|
|
<example xml:id="mongo.tutorial.basics">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// conectar
|
|
$m = new MongoClient();
|
|
|
|
// seleccionar una base de datos
|
|
$bd = $m->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";
|
|
}
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Calvin and Hobbes
|
|
XKCD
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
|
|
<section xml:id="mongo.tutorial.connecting">
|
|
<title>Estableciendo una Conexión</title>
|
|
<para>
|
|
Para conectar al servidor de bases de datos, utilice alguna de las siguientes formas:
|
|
</para>
|
|
|
|
<example xml:id="mongo.tutorial.connecting-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient(); // conectar a localhost:27017
|
|
$conexión = new MongoClient( "mongodb://example.com" ); // conectar a un host remoto (puerto predeterminado: 27017)
|
|
$conexión = new MongoClient( "mongodb://example.com:65432" ); // concectar a un host remoto en un puerto dado
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
No es necesario desconectar explícitamente de la base de datos. El controlador usa
|
|
conexiones persistentes y reutilizará las conexiones ya establecidas.
|
|
</para>
|
|
<section xml:id="mongo.tutorial.connecting.seealso">
|
|
<title>Ver también</title>
|
|
<para>
|
|
El capítulo <link linkend="mongo.connecting">connecting</link>
|
|
cubre los distintos tipos de conexiones.
|
|
</para>
|
|
<para>
|
|
Tanto la documentación de la API de la clase <classname>MongoClient</classname> como
|
|
<function>MongoClient::__construct</function> proporcionan un exhaustivo repaso a todas
|
|
las opciones disponibles, y un gran número de ejemplos.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.selectdb">
|
|
<title>Obteniendo una Base de Datos</title>
|
|
<para>
|
|
Para seleccionar una base de datos, utilice.
|
|
</para>
|
|
<example xml:id="mongo.tutorial.selectdb-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$bd = $conexión->dbname;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
La base de datos no debe necesariamente haber sido ya creada, sino que
|
|
pueden crearse con sólo seleccionarlas.
|
|
</para>
|
|
<para>
|
|
¡Tenga cuidado con los errores tipográficos! Podría, por inadvertencia, crear una
|
|
nueva base de datos, provocando errores (aquí, <literal>name</literal> está mal escrito
|
|
como <literal>anme</literal> en la segunda selección:
|
|
|
|
<example xml:id="mongo.tutorial.selectdb.typo">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
|
|
$bd = $conexión->mybiglongdbname;
|
|
// hacemos algo
|
|
|
|
$bd = $conexión->mybiglongdbanme;
|
|
// ¡ahora estamos conectando a una nueva base de datos!
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<section xml:id="mongo.tutorial.selectdb.seealso">
|
|
<title>Ver También</title>
|
|
<para>
|
|
La documentación API de la clase <classname>MongoDB</classname> contiene más
|
|
información sobre los objetos de bases de datos.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.collection">
|
|
<title>Obteniendo Una Colección</title>
|
|
<para>
|
|
Para obtener una conexión se utiliza la misma sintaxis que para obtener una base de datos:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.collection-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$bd = $conexión->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;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Las colecciones son análogos a las tablas (para aquéllos que estén
|
|
familiarizados con bases de datos relacionales).
|
|
</para>
|
|
<section xml:id="mongo.tutorial.collection.seealso">
|
|
<title>Ver También</title>
|
|
<para>
|
|
La documentación API de la clase <classname>MongoCollection</classname> contiene más
|
|
información sobre objetos de colecciones.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.insert">
|
|
<title>Insertando un Documento</title>
|
|
<para>
|
|
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:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.insert-data-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$doc = array(
|
|
"name" => "MongoDB",
|
|
"type" => "database",
|
|
"count" => 1,
|
|
"info" => (object)array( "x" => 203, "y" => 102),
|
|
"versions" => array("0.9.7", "0.9.8", "0.9.9")
|
|
);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
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: <literal>0, 1, 4, 5</literal>).
|
|
</para>
|
|
<para>
|
|
Para insertar este documento, utilice <function>MongoCollection::insert</function>:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.insert-example-2">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
$colección->insert( $doc );
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<section xml:id="mongo.tutorial.insert.seealso">
|
|
<title>Ver También</title>
|
|
<para>
|
|
La documentación API de <function>MongoCollection::insert</function>
|
|
contiene más información sobre la inserción de datos.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.findone">
|
|
<title>
|
|
Localizando documentos usando <function>MongoCollection::findOne</function>
|
|
</title>
|
|
<para>
|
|
Para comprobar que el documento que insertamos en el paso anterior está almacenado en
|
|
la base de datos, podemos realizar una operación
|
|
<function>MongoCollection::findOne</function> 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.
|
|
</para>
|
|
<example xml:id="mongo.tutorial.findone-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
$documento = $colección->findOne();
|
|
var_dump( $documento );
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
array(6) {
|
|
["_id"]=>
|
|
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"
|
|
}
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<para>
|
|
Hay un campo <literal>_id</literal> que se ha añadido
|
|
automáticamente al documento. <literal>_id</literal> es el campo de la
|
|
"clave primaria". Si el documento no especifica una, el controlador la añadirá
|
|
automáticamente.
|
|
</para>
|
|
<para>
|
|
Si se ha especificado un campo <literal>_id</literal>, debe ser único en toda
|
|
la colección. Por ejemplo:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.findone-example-2">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$bd = $conexión->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));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
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
|
|
<literal>array("w" => 0)</literal> 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 <literal>_id</literal> duplicado.
|
|
</para>
|
|
<section xml:id="mongo.tutorial.findone.seealso">
|
|
<title>Ver También</title>
|
|
<para>
|
|
<function>MongoCollection::findOne</function>
|
|
contiene más información sobre cómo localizar datos.
|
|
</para>
|
|
<para>
|
|
<classname>MongoId</classname> ofrece más detalles de los identificadores únicos.
|
|
</para>
|
|
<para>
|
|
La sección <link linkend="mongo.writes">writes</link> trata
|
|
las escrituras en mayor profundidad, y el capítulo <xref linkend="mongo.writeconcerns" />
|
|
entra en detalles sobre las diferentes opciones de Write Concern.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.insert.multiple">
|
|
<title>Añadiendo Múltiples Documentos</title>
|
|
<para>
|
|
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
|
|
<literal>array( "i" => <replaceable>value</replaceable> );</literal> y podemos
|
|
hacerlo de un modo muy eficiente en un bucle:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.insert.multiple-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
for ( $i = 0; $i < 100; $i++ )
|
|
{
|
|
$colección->insert( array( 'i' => $i, "field{$i}" => $i * 2 ) );
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
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 <literal>i</literal>, aunque también un nombre de campo en la forma
|
|
<literal>field</literal> + <literal>$i</literal>.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.counting">
|
|
<title>Contando los Documentos de una Colección</title>
|
|
<para>
|
|
Ahora que hemos insertado 101 documentos (los 100 del bucle, junto con el
|
|
primero), podemos comprobar si los tenemos todos usando el método
|
|
<function>MongoCollection::count</function>.
|
|
<example xml:id="mongo.tutorial.counting-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
echo $colección->count();
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
y debería mostrar 101.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.cursor">
|
|
<title>Usando un Cursor para Obtener Todo de los Documentos</title>
|
|
<para>
|
|
Para obtener todos los documentos, usaremos
|
|
<function>MongoCollection::find</function>. El método find() devuelve un objeto
|
|
<classname>MongoCursor</classname> 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:
|
|
|
|
<example xml:id="mongo.tutorial.cursor-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
$cursor = $colección->find();
|
|
foreach ( $cursor as $id => $valor )
|
|
{
|
|
echo "$id: ";
|
|
var_dump( $valor );
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
|
|
y mostrará los 101 documentos de la colección.
|
|
<literal>$id</literal> es el campo <literal>_id</literal> del documento
|
|
(transformado a string) y <literal>$valor</literal> es el documento en sí.
|
|
</para>
|
|
<section xml:id="mongo.tutorial.cursor.seealso">
|
|
<title>Ver También</title>
|
|
<para>
|
|
La documentación API de <function>MongoCollection::find</function>
|
|
contiene más información sobre cómo localizar datos.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.criteria">
|
|
<title>Estableciendo el Criterio de la Consulta</title>
|
|
<para>
|
|
Podemos crear una consulta para pasar al método
|
|
<function>MongoCollection::find</function> y así obtener un subconjunto de documentos
|
|
de nuestra colección. Por ejemplo, si quisiéramos encontrar el documento cuyo valor en el
|
|
campo <literal>"i"</literal> es <literal>71</literal>,
|
|
haríamos lo siguiente:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.criteria-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
$consulta = array( 'i' => 71 );
|
|
$cursor = $colección->find( $consulta );
|
|
|
|
while ( $cursor->hasNext() )
|
|
{
|
|
var_dump( $cursor->getNext() );
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
array(2) {
|
|
["_id"]=>
|
|
object(MongoId)#6 (0) {
|
|
}
|
|
["i"]=>
|
|
int(71)
|
|
["_ns"]=>
|
|
"testCollection"
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.multi.query">
|
|
<title>Consultando un Conjunto de Documentos con una Consulta</title>
|
|
<para>
|
|
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 <literal>"i"</literal>
|
|
> <literal>50</literal>, podríamos poner:
|
|
</para>
|
|
<example xml:id="mongo.tutorial.multi.query-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->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() );
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
lo cual mostraría los documentos en que <literal>"i"</literal> >
|
|
<literal>50</literal>. Podemos también consultar un rango, digamos
|
|
<literal>20 < i <= 30</literal>:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->database->collectionName;
|
|
|
|
$consulta = array( 'i' => array( '$gt' => 20, "\$lte" => 30 ) );
|
|
$cursor = $colección->find( $consulta );
|
|
|
|
while ( $cursor->hasNext() )
|
|
{
|
|
var_dump( $cursor->getNext() );
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Recuerde escapar siempre el símbolo $ o utilizar comillas simples. Si no, PHP
|
|
lo interpretará como la variable <varname>$gt</varname>.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="mongo.tutorial.indexes">
|
|
<title>Creando un Índice</title>
|
|
<para>
|
|
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":
|
|
</para>
|
|
<example xml:id="mongo.tutorial.indexes-example">
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$conexión = new MongoClient();
|
|
$colección = $conexión->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
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
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
|
|
<function>MongoCollection::ensureIndex</function> y l a
|
|
<link xlink:href="&url.mongodb.dochub.indexes;">documentación de indexación de MongoDB</link>.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|