archived-doc-es/reference/phar/fileformat.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f9c4a68ef4f89e51e6d9b905ad3ddb6492386dd3 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->
<chapter xml:id="phar.fileformat" xmlns="http://docbook.org/ns/docbook">
 <title>¿Qué hace que un phar sea un phar y no un tar o un zip?</title>
 <section xml:id="phar.fileformat.ingredients" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Los componentes de todas las archivos Phar, independientemente del formato de archivo</title>
  <para>
   Todos los archivos Phar contienen de tres a cuatro secciones:
   <orderedlist>
    <listitem>
     <para>
      Un contenedor
     </para>
    </listitem>
    <listitem>
     <para>
      Un manifiesto que describe el contenido
     </para>
    </listitem>
    <listitem>
     <para>
      El contenido del archivo
     </para>
    </listitem>
    <listitem>
     <para>
      Una firma (opcional) para verificar la integridad
      (solo con el formato de archivo phar)
     </para>
    </listitem>
   </orderedlist>
  </para>
 </section>
 <section xml:id="phar.fileformat.stub" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>El contenedor de archivo Phar</title>
  <para>
   Un contenedor Phar es un simple archivo PHP. El contenedor mínimo contiene:
  </para>
  <para>
   <programlisting role="php">
<![CDATA[<?php __HALT_COMPILER();]]>
   </programlisting>
  </para>
  <para>
   Un contenedor debe contener al menos el token <literal>__HALT_COMPILER();</literal>
   como conclusión. Típicamente, un contenedor contendrá las siguientes funcionalidades
   de carga:
  </para>
  <para>
   <programlisting role="php">
<![CDATA[
<?php
Phar::mapPhar();
include 'phar://monphar.phar/index.php';
__HALT_COMPILER();
   ]]>
   </programlisting>
  </para>
  <para>
   No hay restricciones sobre el contenido de un contenedor Phar, excepto la necesidad de
   concluir con <literal>__HALT_COMPILER();</literal>. La etiqueta de cierre PHP <literal><![CDATA[?>]]></literal> puede ser
   incluida u omitida, pero no puede haber más de un espacio entre el <literal>;</literal> y la etiqueta de cierre
   <literal><![CDATA[?>]]></literal>, de lo contrario la extensión phar no será capaz de leer el
   manifiesto del archivo.
  </para>
  <para>
   En un archivo phar basado en tar o zip, el contenedor se almacena en el archivo
   <literal>.phar/stub.php</literal>. El contenedor por defecto de los archivos Phar basados en
   phar contiene aproximadamente 7ko de código para extraer el contenido del phar y ejecutarlo.
   Consulte la función <function>Phar::createDefaultStub</function> para más detalles.
  </para>
  <para>
   El alias phar se almacena, en el caso de un archivo phar basado en tar o zip, en el archivo
   <literal>.phar/alias.txt</literal> como texto plano.
  </para>
 </section>
 <section xml:id="phar.fileformat.comparison" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Comparación entre Phar, Tar y Zip</title>
  <para>
   ¿Cuáles son las ventajas y desventajas de cada uno de los tres formatos soportados
   por la extensión phar? Esta tabla intenta responder a esta pregunta.
   <table>
    <title>Tabla comparativa: Phar, Tar y Zip</title>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>Funcionalidad</entry>
       <entry>Phar</entry>
       <entry>Tar</entry>
       <entry>Zip</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Formato de archivo estándar</entry>
       <entry>No</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Puede ser ejecutado sin la extensión Phar
        <link linkend="phar.fileformat.phartip">[1]</link>
       </entry>
       <entry>Sí</entry>
       <entry>No</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Compresión por archivo</entry>
       <entry>Sí</entry>
       <entry>No</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Compresión para todo el archivo</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Validación por firma de todo el archivo</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Soporte de aplicaciones específicamente web</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Metadatos por archivo</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Metadatos para todo el archivo</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Creación/modificación de archivo
        <link linkend="phar.fileformat.phartip2">[2]</link>
       </entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Soporte completo de todas las funciones de flujo</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
      <row>
       <entry>Puede ser creado/modificado incluso si phar.readonly=1
        <link linkend="phar.fileformat.phartip3">[3]</link>
       </entry>
       <entry>No</entry>
       <entry>Sí</entry>
       <entry>Sí</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para xml:id="phar.fileformat.phartip">
   <tip>
    <para>
     [1] PHP no puede acceder directamente al contenido de un archivo Phar sin que la extensión
     Phar esté instalada si utiliza un <literal>contenedor</literal>
     que extrae el contenido del archivo phar. El contenedor
     creado por <function>Phar::createDefaultStub</function> extrae
     el archivo phar y ejecuta su contenido desde un directorio temporal si
     no se encuentra ninguna extensión phar.
    </para>
   </tip>
  </para>
  <para xml:id="phar.fileformat.phartip2">
   <tip>
    <para>
     [2] Todos los accesos en escritura requieren que <literal>phar.readonly</literal> esté
     desactivado en el php.ini o directamente desde la línea de comandos.
    </para>
   </tip>
  </para>
  <para xml:id="phar.fileformat.phartip3">
   <tip>
    <para>
     [3] Solo los archivos tar o zip sin <literal>.phar</literal> en su
     nombre y sin contenedor ejecutable <literal>.phar/stub.php</literal>
     pueden ser creados si phar.readonly=1.
    </para>
   </tip>
  </para>
 </section>
 <section xml:id="phar.fileformat.tar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Los phars basados en Tar</title>
  <para>
   Los archivos basados en el formato de archivo tar son conformes al formato moderno
   USTAR. El diseño de los encabezados del archivo tar lo hace más eficiente que el formato de archivo zip
   y tan eficiente como el formato de archivo phar cuando se trata de acceder a los datos.
   Los nombres de archivos están limitados a 255 bytes, incluyendo la ruta completa dentro del archivo phar
   basado en tar. Estos archivos pueden ser completamente comprimidos en formato gzip o bzip2 mientras
   siguen siendo ejecutables por la extensión Phar.
  </para>
  <para>
   Hay un soporte limitado para leer los tarballs en el formato pax interchangeable,
   pero todos los encabezados pax reconocidos (actualmente, typeflag <literal>x</literal>
   y <literal>g</literal>) son silenciosamente ignorados.
   También hay un soporte limitado para los archivos GNU Tar;
   actualmente, los encabezados <literal>././@LongLink</literal> son resueltos.
  </para>
  <para>
   Para comprimir un archivo completo, utilice <function>Phar::compress</function>.
   Para descomprimir un archivo completo, utilice <function>Phar::decompress</function>.
  </para>
 </section>
 <section xml:id="phar.fileformat.zip" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Los phars basados en Zip</title>
  <para>
   Los archivos basados en el formato de archivo zip soportan numerosas funcionalidades
   incluidas en el formato zip. Los metadatos por archivo o sobre todo el archivo se almacenan
   en los comentarios del archivo zip y del archivo zip como una cadena de caracteres serializada.
   Los comentarios zip ya existentes serán leídos sin problemas como una cadena. Las lecturas/escrituras
   comprimidas son soportadas por la compresión zlib DEFLATE, y solo las lecturas comprimidas por
   la compresión bzip2. No hay límite en el número de archivos dentro de un archivo phar
   basado en zip. Los directorios vacíos se almacenan en el archivo zip como archivos con una barra final,
   como <literal>mon/repertoire/</literal>
  </para>
 </section>
 <section xml:id="phar.fileformat.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>El formato de archivo Phar</title>
  <para>
   El formato de archivo phar está compuesto por contenedor/manifiesto/contenido/firma, y almacena
   las informaciones cruciales de lo que está contenido en el archivo phar en su
   <literal>manifiesto</literal>.
  </para>
  <para>
   El manifiesto Phar es un formato altamente optimizado que permite la especificación archivo por archivo
   de la compresión, los permisos y hasta metadatos de usuario tales como el usuario o el
   grupo propietario. Todos los valores de más de un byte son almacenados en formato little-endian,
   A excepción de la versión de la API que es almacenada por razones históricas en 3 trozos
   big-endian.
  </para>
  <para>
   Todos los flags no utilizados están reservados para un uso futuro y no deben ser utilizados
   para almacenar informaciones personalizadas. Utilice los metadatos por archivo para almacenar
   metadatos personalizados sobre archivos particulares.
  </para>
  <para>
   El formato de archivo básico del manifiesto de un archivo Phar es el siguiente:
  </para>
  <para>
   <table>
    <title>Formato global del manifiesto Phar</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Tamaño en bytes</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4 bytes</entry>
       <entry>Longitud del manifiesto en bytes (limitada a 1 MB)</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Número de archivos en el Phar</entry>
      </row>
      <row>
       <entry>2 bytes</entry>
       <entry>Versión de la API del manifiesto Phar (actualmente 1.0.0)</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Flags "bitmapped" globales del Phar</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Longitud del alias Phar</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>El alias Phar (longitud basada en el valor anterior)</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Longitud de los metadatos Phar (<literal>0</literal> si no hay)</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>Metadatos Phar serializados, almacenados en un formato <function>serialize</function></entry>
      </row>
      <row>
       <entry>al menos 24 * bytes de las entradas</entry>
       <entry>Entradas para cada archivo</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
 <section xml:id="phar.fileformat.flags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Flags "bitmapped" globales del Phar</title>
  <para>
   Estos son los flags "bitmapped" actualmente reconocidos por la extensión Phar
   para el bitmap completo global de Phar:
  </para>
  <para>
   <table>
    <title>Valores de bitmap reconocidos</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Valor</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>0x00010000</literal></entry>
       <entry>Si está presente, el Phar contiene una firma de verificación</entry>
      </row>
      <row>
       <entry><literal>0x00001000</literal></entry>
       <entry>
        Si está presente, el Phar contiene al menos 1 archivo que es
        comprimido mediante zlib DEFLATE
       </entry>
      </row>
      <row>
       <entry><literal>0x00002000</literal></entry>
       <entry>
        Si está presente, el Phar contiene al menos 1 archivo que es
        comprimido mediante bzip2
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
 <section xml:id="phar.fileformat.manifestfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Definición de las entradas del manifiesto Phar</title>
  <para>
   Cada archivo del manifiesto contiene las siguientes informaciones:
  </para>
  <para>
   <table>
    <title>Entrada del manifiesto Phar</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Tamaño en bytes</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4 bytes</entry>
       <entry>Longitud del nombre de archivo en bytes</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>Nombre de archivo (longitud basada en el valor anterior)</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Tamaño del archivo descomprimido en bytes</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Timestamp Unix del archivo</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Tamaño del archivo comprimido en bytes</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Suma de control CRC32 del contenido descomprimido del archivo</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Flags bitmapped específicos del archivo</entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>Longitud de los metadatos del archivo serializados (<literal>0</literal> si no hay)</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>Metadatos del archivo serializados, almacenados en un formato <function>serialize</function></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   Se debe notar que a partir de la API 1.1.1, los directorios vacíos son almacenados como nombres de archivo
   con una barra final como <literal>mon/repertoire/</literal>
  </para>
  <para>
   Los valores reconocidos de flags bitmapped específicos del archivo son:
  </para>
  <para>
   <table>
    <title>Valores reconocidos de bitmap</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Valor</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>0x000001FF</literal></entry>
       <entry>
        Estos bits están reservados para definir permisos específicos del archivo.
        Estos son utilizados para <function>fstat</function>
        y pueden ser utilizados para recrear los permisos deseados en caso de extracción.
       </entry>
      </row>
      <row>
       <entry><literal>0x00001000</literal></entry>
       <entry>
        Si está presente, el archivo es comprimido mediante zlib DEFLATE
       </entry>
      </row>
      <row>
       <entry><literal>0x00002000</literal></entry>
       <entry>
        Si está presente, el archivo es comprimido mediante bzip2
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
 <section xml:id="phar.fileformat.signature" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Formato de firma Phar</title>
  <para>
   Los Phar que contienen una firma siempre tienen la firma añadida al final del Phar,
   después del cargador, el manifiesto y el contenido.
   Los tipos de firma soportados hasta la fecha son MD5, SHA1, SHA256, SHA512,
   y OPENSSL.
  </para>
  <para>
   <table>
    <title>Formato de firma</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Longitud en bytes</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>variante</entry>
       <entry>
        La firma actual, 20 bytes para una SHA1,
        16 bytes para una MD5, 32 bytes para una SHA256,
        y 64 bytes para una SHA512. La longitud de una firma
        OPENSSL depende del tamaño de la clave privada.
       </entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>
        Los flags de firma. <literal>0x0001</literal> es utilizado para
        definir una firma MD5, <literal>0x0002</literal> para una SHA1,
        <literal>0x0003</literal> para una SHA256 y <literal>0x0004</literal>
        para una SHA512. El soporte para las firmas SHA256 y SHA512 está disponible
        a partir de la versión 1.1.0 de la API.
        <literal>0x0010</literal> es utilizado para definir una firma OPENSSL,
        que está disponible a partir de la versión 1.1.1 de la API, si OpenSSL está disponible.
       </entry>
      </row>
      <row>
       <entry>4 bytes</entry>
       <entry>
        <literal>GBMB</literal> mágico utilizado para definir la presencia de una firma.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </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
-->