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

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

<book xml:id="book.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <?phpdoc extension-membership="bundled" ?>
 <title>Phar</title>

 <!-- {{{ preface -->
 <preface xml:id="intro.phar">
  &reftitle.intro;
  <para>
   La extensión phar proporciona un medio para empaquetar una aplicación PHP completa en un único archivo
   llamado "phar" (PHP Archive) para facilitar la instalación y configuración.
   Además de este servicio, la extensión también proporciona una clase de abstracción de formato de archivo
   para crear y manipular archivos tar y zip a través de la clase
   <classname>PharData</classname>, de manera similar a como
   PDO proporciona una interfaz unificada para acceder a diferentes bases de datos. Sin embargo, a diferencia de PDO,
   que no puede transferir datos entre bases de datos, Phar tiene la capacidad de convertir archivos tar,
   zip y phar con una sola línea de código. Consulte
   <function>Phar::convertToExecutable</function> para obtener un ejemplo.
  </para>
  <para>
   ¿Qué es phar? Las archivos phar son en realidad un medio práctico para agrupar
   varios archivos en uno solo. Así, un archivo phar permite distribuir una
   aplicación PHP completa en un único archivo y ejecutarla desde este archivo
   sin necesidad de extraerlo en el disco. Además, los archivos phar pueden ser ejecutados
   por PHP tan fácilmente como cualquier otro archivo, tanto desde la línea de comandos como a través
   de un servidor web. Phar es una especie de memoria USB para aplicaciones PHP.
  </para>
  <para>
   Phar implementa esta funcionalidad mediante <link linkend="book.stream">un
   flujo</link>. Normalmente, para utilizar un archivo externo desde un script PHP, se
   debe utilizar la función <function>include</function>:
  </para>
  <para>
   <example>
    <title>Utilizar un archivo externo</title>
    <programlisting role="php">
     <![CDATA[
 <?php
 include '/ruta/al/archivo/externo.php';
 ?>
     ]]>
    </programlisting>
   </example>
  </para>
  <para>
   Puede considerarse que PHP convierte en realidad
   <literal>/ruta/al/archivo/externo.php</literal> en un
   flujo <literal>file:///ruta/al/archivo/externo.php</literal>, y que
   utiliza de forma oculta las funciones de flujo de archivos planos para acceder
   a archivos locales.
  </para>
  <para>
   Para utilizar un archivo llamado <literal>archivo.php</literal> contenido en un archivo phar
   <literal>/ruta/al/miphar.phar</literal>,
   la sintaxis es casi similar a la sintaxis <literal>file://</literal> anterior.
  </para>
  <para>
   <example>
    <title>Utilizar un archivo contenido en un archivo phar</title>
    <programlisting role="php">
     <![CDATA[
 <?php
 include 'phar:///ruta/al/miphar.phar/archivo.php';
 ?>
     ]]>
    </programlisting>
   </example>
  </para>
  <para>
   En realidad, un archivo phar puede tratarse como si fuera un disco externo, utilizando
   cualquiera de las funciones relacionadas con <function>fopen</function>, <function>opendir</function> y
   <function>mkdir</function> para leer, modificar o crear nuevos archivos o directorios dentro del
   archivo phar. Esto permite que aplicaciones PHP completas sean distribuidas en un único archivo
   y ejecutadas desde él.
  </para>
  <para>
   El uso más común de un archivo phar es distribuir una aplicación completa
   en un único archivo. Por ejemplo, el instalador PEAR que se incluye con las versiones de PHP
   se distribuye mediante un archivo phar. Para utilizar el archivo phar distribuido de esta manera, este
   puede ser ejecutado mediante la línea de comandos o a través de un navegador web.
  </para>
  <para>
   Los archivos phar pueden distribuirse en formato <literal>tar</literal>,
   <literal>zip</literal> o en el formato <literal>phar</literal> especialmente diseñado
   para la extensión phar. Cada formato de archivo tiene sus ventajas e inconvenientes. Los archivos
   zip y tar pueden ser extraídos por cualquier herramienta de terceros que pueda leer el formato, pero
   requieren la extensión phar para ser ejecutados por PHP. El formato de archivo phar es único y dedicado
   a la extensión phar y solo puede ser creado por esta o por el paquete PEAR
   <link xlink:href="&url.pear.package;PHP_Archive">PHP_Archive</link>, pero tiene la ventaja de no
   requerir la instalación de la extensión phar para que la aplicación empaquetada pueda ser ejecutada.
  </para>
  <para>
   En otras palabras, incluso con la extensión phar desactivada, es posible ejecutar o incluir
   un archivo basado en phar. Acceder a archivos individuales dentro de un archivo phar solo es
   posible con la extensión phar a menos que el archivo phar haya sido creado por PHP_Archive.
  </para>
  <para>
   La extensión phar también es capaz de convertir un archivo phar desde un tar hacia un archivo zip
   o phar con un solo comando:
  </para>
  <para>
   <example>
    <title>Convertir un archivo phar al formato tar</title>
    <programlisting role="php">
     <![CDATA[
 <?php
 $phar = new Phar('miphar.phar');
 $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // produce miphar.phar.tar.gz
 ?>
     ]]>
    </programlisting>
   </example>
  </para>
  <para>
   Phar puede comprimir archivos individuales o un archivo completo
   utilizando la compresión <link linkend="book.zlib">gzip</link> o
   <link linkend="book.bzip2">bzip2</link>, y puede verificar la integridad del archivo
   automáticamente utilizando funciones de firma MD5, SHA-1, SHA-256 o SHA-512.
  </para>
  <para>
   Finalmente, la extensión phar está orientada a la seguridad, desactiva por defecto los accesos
   de escritura en archivos phar ejecutables y requiere la desactivación a nivel de sistema
   del parámetro <literal>phar.readonly</literal> del php.ini para crear o modificar archivos phar.
   Los archivos tar y zip sin el marcador ejecutable pueden ser siempre creados o modificados
   utilizando la clase <classname>PharData</classname>.
  </para>
  <para>
   Si se crean aplicaciones con el propósito de distribuirlas, se debe leer
   <link linkend="phar.creating">Cómo crear archivos Phar</link>. Si se desea
   más información sobre las diferencias entre los formatos de archivo que phar soporta,
   se debe leer <link linkend="phar.fileformat">Phar, Tar y Zip</link>.
  </para>
  <para>
   Si se utilizan aplicaciones phar, hay trucos muy útiles en
   <link linkend="phar.using">Cómo utilizar archivos Phar</link>.
  </para>
  <para>
   La palabra <literal>phar</literal> es la contracción de <literal>PHP</literal> y de
   <literal>Archive</literal> y está fuertemente inspirada
   en la palabra <literal>jar</literal> (Java Archive) familiar a los desarrolladores Java.
  </para>
  <para>
   La implementación de los archivos Phar se basa en el paquete PEAR
   <link xlink:href="&url.pear.package;PHP_Archive">PHP_Archive</link>, y
   los detalles de implementación son los mismos, aunque la extensión Phar
   es más potente. Además, esta permite que la mayoría de las aplicaciones
   PHP sean ejecutadas sin modificación mientras que los archivos basados en PHP_Archive
   requieren a menudo muchas modificaciones para funcionar.
  </para>
 </preface>
 <!-- }}} -->

 &reference.phar.setup;
 &reference.phar.constants;
 &reference.phar.using;
 &reference.phar.creating;
 &reference.phar.fileformat;
 &reference.phar.Phar;
 &reference.phar.PharData;
 &reference.phar.PharFileInfo;
 &reference.phar.PharException;

</book>

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