archived-doc-es/reference/mongo/mongogridfs.xml

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

<phpdoc:classref xml:id="class.mongogridfs" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <title>Clase MongoGridFS</title>
 <titleabbrev>MongoGridFS</titleabbrev>
 
 <partintro>
  
  <!-- {{{ Mongogridfs intro -->
  <section xml:id="mongogridfs.intro">
   &reftitle.intro;
   <para>
    Utilidad para almacenar y extraer ficheros de la base de datos.
   </para>
   
   <para>
    GridFS es una especificación de almacenamiento que implementan todos los drivers soportados.
    En resumen, define dos colecciones: <literal>files</literal>, para los metadatos del
    fichero, y <literal>chunks</literal>, para el contenido del fichero. Si el fichero fuera de
    gran tamaño, automáticamente se dividiría en porciones menores, y cada bloque se
    guardará como un documento en la colección de bloques.
   </para>
   
   <para>
    Cada documento de la colección de ficheros contiene el nombre de fichero, fecha de subida,
    y un código hash md5. También contiene un campo único <literal>_id</literal>, que se puede
    utilizar para consultar el contenido del fichero en la colección de bloques. Cada documento
    de la colección de bloques contiene un bloque de datos binarios, un campo
    <literal>files_id</literal> que se corresponde con el
    <literal>_id</literal> de su fichero, y la posición de este bloque respecto a los demás.
   </para>
   
   <para>
    Por ejemplo, el documento de ficheros podría ser algo tal que así:
    <programlisting role="php">
<![CDATA[
<?php
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
?>
]]>
    </programlisting>
    mientras que los documentos de bloques:
    <programlisting role="php">
<![CDATA[
<?php
array("files_id" => 123456789, "n" => 0, "data" => new MongoBinData("abc"));
array("files_id" => 123456789, "n" => 1, "data" => new MongoBinData("def"));
array("files_id" => 123456789, "n" => 2, "data" => new MongoBinData("ghi"));
array("files_id" => 123456789, "n" => 3, "data" => new MongoBinData("jkl"));
?>
]]>
    </programlisting>
    Por supuesto, el tamaño por omisión de los bloques es de miles de bytes, pero eso lo haría un ejemplo impracticable.
   </para>
  </section>
  
  <section>
   <title>Compatibilidad Entre Lenguajes</title>
   <para>
    Se puede usar cualquier fichero creado con MongoGridFS con cualquier otro
    driver y viceversa. Sin embargo, algunos drivers esperan que todos los metadatos
    asociados con un fichero se encuentren en el campo "metadata". Si se preve
    que se utilizará con otros lenguajes, es una buena idea empaquetar en un campo
    "metadata" toda la información que se desee que vean. Por ejemplo, en lugar de:
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$grid->storeFile("algunfichero.txt", array("date" => new MongoDate()));

?>
]]>
   </programlisting>
   <para>
    utilice algo así:
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$grid->storeFile("algunfichero.txt", array("metadata" => array("date" => new MongoDate())));

?>
]]>
   </programlisting>
  </section>
  
  <section>
   <title>La Familia <classname>MongoGridFS</classname></title>
   
   <para>
    <classname>MongoGridFS</classname> representa los ficheros y las colecciones de
    bloques. <classname>MongoGridFS</classname> hereda MongoCollection. 
    Las instancias de <classname>MongoGridFS</classname> tienen acceso a todos los métodos de
    <classname>MongoCollection</classname>, que actúan sobre las colecciones
    de ficheros:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php

$grid = $db->getGridFS();
$grid->update(array("filename" => "foo"), $newObj); // actualización en la colección de ficheros

?>
]]>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Otro ejemplo de manipulación de metadatos:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php

// guardar un fichero
$id = $grid->storeFile("juego.tgz");
$juego = $grid->findOne();

// añadir un contador de descargas
$juego->file['descargas'] = 0;
$grid->save($juego->file);

// incrementar el contador
$grid->update(array("_id" => $id), array('$inc' => array("descargas" => 1)));

?>
]]>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Se puede también acceder a los bloques de una colección a partir de una instancia de
    <classname>MongoGridFS</classname>:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php

  $chunks = $grid->chunks; // $chunks es un MongoCollection normal
$chunks->insert(array("x" => 4));

?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Hay algunos métodos de <classname>MongoGridFS</classname> que comparten nombres con
    métodos de <classname>MongoCollection</classname>, pero que se comportan de un modo
    ligeramente diferente. Por ejemplo, <function>MongoGridFS::remove</function>
    eliminará cualquier objeto, junto con su contenido en la colección de bloques, cuando
    se cumplan los criterios de la colección de ficheros.
   </para>
   
   <para>
    Para almacenar cualquier otra cosa en GridFS, hay varias opciones. Si se tuviera un nombre
    de fichero, se podría hacer:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php

$grid->storeFile($filename, array("cualquier" => "metadato", "que" => "desee"));

?>
]]>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Si se tuviera un string de bytes que no fuera un fichero, se podrá tambien almacenar
    usando <function>MongoGridFS::storeBytes</function>:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php

$grid->storeBytes($bytes, array("cualquier" => "metadato", "que" => "desee"));

?>
]]>
     </programlisting>
    </informalexample>
   </para>
   
   <para>
    Al consultar a una colección <classname>MongoGridFS</classname>, se devolverá un
    <classname>MongoGridFSCursor</classname>, que se comporta como un
    <classname>MongoCursor</classname> convencional, excepto que devuelve un
    <classname>MongoGridFSFiles</classname> en lugar de una matriz asociativa.
   </para>
   
   <para>
    <classname>MongoGridFSFiles</classname> puede volver a escribirse en disco usando
    <function>MongoGridFSFile::write</function>, o en memoria usando
    <function>MongoGridFSFile::getBytes</function>. Actualmente no existe ningún método que cree
    automáticamente un flujo de bloques, pero resulta muy sencillo hacer
    escrituras realizando consultas a la colección <literal>$grid->chunks</literal>.
   </para>
   
   <para>
    El objeto <classname>MongoGridFSFile</classname> contiene un campo file (fichero) que
    contiene cualquier metadato del fichero.
   </para>
  </section>
  <!-- }}} -->
  
  <section xml:id="mongogridfs.synopsis">
   &reftitle.classsynopsis;
   
   <!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>MongoGridFS</classname></ooclass>
    
    <!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <modifier>extends</modifier>
      <classname>MongoCollection</classname>
     </ooclass>
    </classsynopsisinfo>
    <!-- }}} -->
    
    <classsynopsisinfo role="comment">Campos</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>public</modifier>
     <type>MongoCollection</type>
     <varname>chunks</varname>
     <initializer>&null;</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>protected</modifier>
     <type>string</type>
     <varname>filesName</varname>
     <initializer>&null;</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>protected</modifier>
     <type>string</type>
     <varname>chunksName</varname>
     <initializer>&null;</initializer>
    </fieldsynopsis>
    
    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongogridfs')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
   </classsynopsis>
   <!-- }}} -->
   
  </section>
  
  <section>
   &reftitle.seealso;
   <simplelist>
    <member>Documentación del núcleo de MongoDB sobre <link xlink:href="&url.mongodb.docs.gridfs;">GridFS</link></member>
    <member>Entrada del blog de LightCube Solutions sobre <link xlink:href="&url.mongodb.gridfs.fileupload;">guardar subidas de usuario</link></member>
    <member>Entrada del blog de LightCube Solutions sobre <link xlink:href="&url.mongodb.gridfs.metadata;">añadir metadatos a ficheros</link></member>
   </simplelist>
  </section>
 </partintro>
 
 &reference.mongo.entities.mongogridfs;
 
</phpdoc:classref>

<!-- 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
-->