library.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: dc5163157c4287bb2dbcbb33b09b0f81d3ae41fd Maintainer: seros Status: ready -->
<!-- Reviewed: no -->

<section xml:id="mongodb.tutorial.library" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Empleo de la biblioteca de PHP para MongoDB (PHPLIB)</title>

 <para>
  Después de la configuración inicial del controlador, continuaremos explicando cómo empezar
  con el controlador de MongoDB y la correspondiente biblioteca de usuario para escribir
  nuestro primer proyecto.
 </para>

 <section>
  <title>Instalación de la Biblioteca de PHP con Composer</title>

  <para>
   Lo último que necesitamos instalar para empezar con la apliación
   en sí, es la biblioteca de PHP.
  </para>

  <para>
   La bibilioteca necesita ser instalada con
   <link xlink:href="&url.mongodb.composer;">Composer</link>, un gestor de paquetes
   para PHP. Las instrucciones para instalar Composer en varias plataformas se pueden
   encontrar en su sitio web.
  </para>

  <para>
   Instale la biblioteca ejecutando:
   <programlisting role="shell">
<![CDATA[
$ composer require "mongodb/mongodb=^1.0.0"
]]>
   </programlisting>
  </para>

  <para>
   Muestra algo parecido a esto:

   <programlisting role="text">
<![CDATA[
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing mongodb/mongodb (1.0.0)
    Downloading: 100%         

Writing lock file
Generating autoload files
]]>
   </programlisting>
  </para>

  <para>
   Composer creará varios ficheros: <code>composer.json</code>,
   <code>composer.lock</code>, y un directorio <code>vendor</code> que
   contendrá la biblioteca y cualquier otra dependencia que requiera el proyecto.
  </para>
 </section>

 <section>
  <title>Utilizar la Biblioteca de PHP</title>

  <para>
   Además de gestionar las dependencias, Composer también proporciona
   un autocargador (para las clases de las dependencias). Asegúrese que se
   incluye al inicio del script o en el código de arranque de la
   aplicación:
   <programlisting role="php">
<![CDATA[
<?php
// Esta ruta debe apuntar al autocargador de Composer
require 'vendor/autoload.php';
]]>
   </programlisting>
  </para>

  <para>
   Con esto hecho, ahora se puede emplear cualquier funcionalidad de la descrita en la
   <link xlink:href="&url.mongodb.library.docs;">documentación de la biblioteca</link>
   y en su <link xlink:href="&url.mongodb.library.apidocs;">API</link>.
  </para>

  <para>
   Si ha empleado anteriormente el controlador antiguo (esto es, la extensión
   <code>mongo</code>), la API de la biblioteca debería serle familiar. Contiene una clase
   <link xlink:href="&url.mongodb.library.apidocs;/class-MongoDB.Client.html">Client</link>
   para conectar a MongoDB, una clase
   <link xlink:href="&url.mongodb.library.apidocs;/class-MongoDB.Database.html">Database</link>
   para operaciones a nivel de la base de datos (p.ej. comandos , gestión de colecciones)
   y una clase
   <link xlink:href="&url.mongodb.library.apidocs;/class-MongoDB.Collection.html">Collection</link>
   para operaciones a nivel de colección (p.ej.
   métodos <link xlink:href="&url.mongodb.wiki.crud;">CRUD</link>, gestión de índices).
   Se han renombrado varios métodos de Collection para mayor claridad y para estar en
   concordancia con una nueva <link xlink:href="&url.mongodb.crud;">specification</link>
   independiente del lenguaje.
  </para>

  <para>
   Como ejemplo, así es como se inserta un documento en la
   colección <emphasis>beers</emphasis> de la base de datos
   <emphasis>demo</emphasis>:
   <programlisting role="php">
<![CDATA[
<?php
require 'vendor/autoload.php'; // incluir lo bueno de Composer

$cliente = new MongoDB\Client("mongodb://localhost:27017");
$colección = $cliente->demo->beers;

$resultado = $colección->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

echo "Inserted with Object ID '{$resultado->getInsertedId()}'";
?>
]]>
   </programlisting>
  </para>

  <para>
   En lugar de inyectar el campo <code>_id</code> generado en el documento de
   entrada (tal como se hacía en el antiguo controlador), ahora se pone a disposición
   mediante el objeto de resultados devuelto por el método <code>insertOne</code>.
  </para>

  <para>
   Por supuesto, después de la inserción también se pueden consultar los datos que se
   acaban de insertar. Para ello se utiliza el método <code>find</code>, el cual devuelve un
   cursor iterable:
   <programlisting role="php">
<![CDATA[
<?php
require 'vendor/autoload.php'; // include Composer goodies

$cliente = new MongoDB\DriverMongoDB\Client("mongodb://localhost:27017");\Client("mongodb://localhost:27017");
$colección = $cliente->demo->beers;

$resultado = $colección->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

foreach ($resultado as $entry) {
    echo $entry['_id'], ': ', $entry['name'], "\n";
}
?>
]]>
   </programlisting>
  </para>

  <para>
   Anuque pueda no ser evidente en los ejemplos, los documentos BSON y los arrays son
   deserializados como clases de tipo en la biblioteca de forma predeterminada. Estas clases aseguran
   que los valores preservan sus tipos cuando son serializados de nuevo a BSON, lo cual
   evita una advertencia del antiguo controlador cuando un array podía convertise a un documento,
   y viceversa. Además, las clases extienden
   <classname>ArrayObject</classname> para mejorar la usabilidad. Se puede encontrar más
   información sobre cómo el controlador y la biblioteca manejan la serialización y
   deserialización entre variablies de PHP y BSON leyendo la
   especificicación de <xref linkend="mongodb.persistence"/>.
  </para>
 </section>
</section>
<!-- 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
-->