mirror of
https://github.com/php/doc-es.git
synced 2026-03-26 16:32:13 +01:00
4d083af4c3
git-svn-id: https://svn.php.net/repository/phpdoc/es/trunk@333835 c90b9560-bf6c-de11-be94-00142212c4b1
389 lines
16 KiB
XML
389 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: 11c9ca2b19737bb4cc3ba388a95605c28c6c51e5 Maintainer: seros Status: ready -->
|
|
<!-- Reviewed: no -->
|
|
<chapter xml:id="phar.using" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Utilizar Archivos Phar</title>
|
|
|
|
<section xml:id="phar.using.intro" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Utilizar Archivos Phar: Introduction</title>
|
|
<para>
|
|
Los archivos phar son similares en concepto a los archivo JAR de Java, pero están adaptados
|
|
a las necesidades y a la flexibilidad de apliciones de PHP. Un archivo Phar se
|
|
usa para distribuir una aplicación o biblioteca PHP completa en un único fichero. Una
|
|
aplicación de un archivo Phar se utiliza exactamente de la misma manera que otra aplicación PHP:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
php aplicacion.phar
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Utilizar una biblioteca de archivo Phar es idéntico a usar cualquier otra biblioteca de PHP:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
include 'biblioteca.phar';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
La envoltura de flujos <literal>phar</literal> proporciona el núcleo de la extensión Phar, y
|
|
está explicada en detalle <link linkend="phar.using.stream">aquí</link>.
|
|
La envoltura de flujos phar permite el acceso a los ficheros dentro de un archivo phar utilizando
|
|
las funciones estándar de ficheros de PHP <function>fopen</function>, <function>opendir</function>, y
|
|
y otras que trabajan sobre ficheros normales. La envoltura de flujos <literal>phar</literal> soporta todas
|
|
las operaciones de lectura/escritura tanto en ficheros como en directorios.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
include 'phar://biblioteca.phar/fichero/interno.php';
|
|
header('Content-type: image/jpeg');
|
|
// a los phar se puede acceder con la ruta completa o mediante un alias
|
|
echo file_get_contents('phar:///ruta_completa/a/biblioteca.phar/imagenes/wow.jpg');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
La clase <classname>Phar</classname> implementa una funcionalidad avanzada para acceder
|
|
a ficheros y crear arhivos phar. La clas Phar está explicada en detalle
|
|
<link linkend="phar.using.object">aquí</link>.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
try {
|
|
// abrir un phar existente
|
|
$p = new Phar('biblioteca.phar', 0);
|
|
// Phar extiende la clase DirectoryIterator de SPL
|
|
foreach (new RecursiveIteratorIterator($p) as $fichero) {
|
|
// $fichero en una clase PharFileInfo, y hereda de SplFileInfo
|
|
echo $fichero->getFileName() . "\n";
|
|
echo file_get_contents($fichero->getPathName()) . "\n"; // mostrar el contenido;
|
|
}
|
|
if (isset($p['fichero/interno.php'])) {
|
|
var_dump($p['fichero/interno.php']->getMetadata());
|
|
}
|
|
|
|
// crear un nuevo phar - phar.readonly debe ser 0 en php.ini
|
|
// phar.readonly está habilitado por omisión por motivos de seguridad.
|
|
// En servidores de producción, los archivos Phar nunca se crean,
|
|
// sólo se ejecutan.
|
|
if (Phar::canWrite()) {
|
|
$p = new Phar('nuevo_phar.tar.phar', 0, 'nuevo_phar.tar.phar');
|
|
// hacerlo un archivo phar basado en tar, comprimido con gzip (.tar.gz)
|
|
$p = $p->convertToExecutable(Phar::TAR, Phar::GZ);
|
|
|
|
// crear una transacción - no se escribe nada en nuevo_phar.phar
|
|
// hasta que stopBuffering() sea llamado, aunque se necesita almacenamiento temporal
|
|
$p->startBuffering();
|
|
// añadir todos los ficheros de /ruta/del/proyecto, guardándolos en el phar con el prefijo "proyecto"
|
|
$p->buildFromIterator(new RecursiveIteratorIterator(new DirectoryIterator('/ruta/del/proyecto')), '/ruta/del/');
|
|
|
|
// añadir un nuevo fichero mediante la API de acceso a arrays
|
|
$p['fichero1.txt'] = 'Información';
|
|
$fp = fopen('fichero_enorme.dat', 'rb');
|
|
// copiar toda la información del flujo
|
|
$p['datos/fichero_enorme.dat'] = $fp;
|
|
|
|
if (Phar::canCompress(Phar::GZ)) {
|
|
$p['datos/fichero_enorme.dat']->compress(Phar::GZ);
|
|
}
|
|
|
|
$p['imagenes/wow.jpg'] = file_get_contents('imagenes/wow.jpg');
|
|
// cualquier valor se puede guardar como metainformación específica del fichero
|
|
$p['imagenes/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
|
|
$p['index.php'] = file_get_contents('index.php');
|
|
$p->setMetadata(array('bootstrap' => 'index.php'));
|
|
|
|
// cuardar el archivo phar en el disco
|
|
$p->stopBuffering();
|
|
}
|
|
} catch (Exception $e) {
|
|
echo 'No se pudo abrir Phar: ', $e;
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Además, la verificación del contenido de ficheros phar se puede realizar utilizando cualquiera de los
|
|
algoritmos hash simétricos soportados (MD5, SHA1, SHA256 y SHA512 si la extensión Hash está habilitada)
|
|
y utilizando firmas de clave pública/privada asimétricas de OpenSSL (nuevo en Phar 2.0.0). Para
|
|
aprovechar la firmas de OpenSSL, se necesita generar una pareja de claves pública/privada, y
|
|
utilizar la clave privada para establecer la firma usando
|
|
<function>Phar::setSignatureAlgorithm</function>. Además, la clave pública se
|
|
extrae usando este código:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$public = openssl_get_publickey(file_get_contents('private.pem'));
|
|
$pkey = '';
|
|
openssl_pkey_export($public, $pkey);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
debe ser guardada junto al archivo phar que verifica. Si el archivo phar
|
|
es guardado como <literal>/ruta/a/mi.phar</literal>, la clave pública debe guardarse
|
|
como <literal>/ruta/a/mi.phar.pubkey</literal>, o phar no será capaz de verificar
|
|
la firma OpenSSL.
|
|
</para>
|
|
<para>
|
|
A partir de la verisón 2.0.0, la clase <classname>Phar</classname> también proporciona tres métodos estáticos, <function>Phar::webPhar</function>,
|
|
<function>Phar::mungServer</function> y <function>Phar::interceptFileFuncs</function>, los cuales son cruiciales
|
|
para empaquetar aplicaciones PHP diseñadas para un uso en sistemas de ficheros normales y aplicación basadas en web.
|
|
<function>Phar::webPhar</function> implementa un controlador principal que direcciona llamadas HTTP a la ubicación
|
|
correcta dentro del archivo phar. <function>Phar::mungServer</function> se utiliza para modificar los valores del
|
|
array <varname>$_SERVER</varname> para hacer que las aplicaciones procesen estos valores.
|
|
<function>Phar::interceptFileFuncs</function> ordena a Phar que intercepte llamdas a
|
|
<function>fopen</function>, <function>file_get_contents</function>, <function>opendir</function>, y
|
|
a todas las funciones basadas en estadísticas (<function>file_exists</function>, <function>is_readable</function>, etc.) y
|
|
direccione todas las rutas relativas a las ubicaciones dentro del archivo phar.
|
|
</para>
|
|
<para>
|
|
Como ejemplo, empaquetar una versión de la popular aplicación phpMyAdmin para usarla cono un archivo phar, requiere
|
|
solamente este sencillo script, y después se puede acceder a <literal>phpMyAdmin.phar.tar.php</literal> como un fichero normal
|
|
desde el servidor web después de modificar el usuario/contraseña:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
@unlink('phpMyAdmin.phar.tar.php');
|
|
copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
|
|
$a = new Phar('phpMyAdmin.phar.tar.php');
|
|
$a->startBuffering();
|
|
$a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
|
|
/* Servers configuration */
|
|
$i = 0;
|
|
|
|
/* Server localhost (config:root) [1] */
|
|
$i++;
|
|
$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
|
|
$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
|
|
$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
|
|
$cfg[\'Servers\'][$i][\'compress\'] = false;
|
|
$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
|
|
$cfg[\'Servers\'][$i][\'user\'] = \'root\';
|
|
$cfg[\'Servers\'][$i][\'password\'] = \'\';
|
|
|
|
|
|
/* End of servers configuration */
|
|
if (strpos(PHP_OS, \'WIN\') !== false) {
|
|
$cfg[\'UploadDir\'] = getcwd();
|
|
} else {
|
|
$cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
|
|
@mkdir(\'/tmp/pharphpmyadmin\');
|
|
@chmod(\'/tmp/pharphpmyadmin\', 0777);
|
|
}';
|
|
$a->setStub('<?php
|
|
Phar::interceptFileFuncs();
|
|
Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
|
|
echo "phpMyAdmin está intentando ejecutarse desde un navegador web\n";
|
|
exit -1;
|
|
__HALT_COMPILER();
|
|
');
|
|
$a->stopBuffering();
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</section>
|
|
<section xml:id="phar.using.stream" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Utilizar Archivos Phar: la envoltura de flujos phar</title>
|
|
<para>
|
|
La envoltura de flujos phar soporta completamente <function>fopen</function> para
|
|
leer y escribir (no añadir), <function>unlink</function>, <function>stat</function>,
|
|
<function>fstat</function>, <function>fseek</function>, <function>rename</function>
|
|
y operaciones de flujo de directorios <function>opendir</function> y a partir de la versión 2.0.0, <function>rmdir</function>
|
|
y <function>mkdir</function>.
|
|
</para>
|
|
<para>
|
|
También se pueden manipular compresiones de ficheros individuales y metadatos por fichero
|
|
en un archivo Phar usando contextos de flujo:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$contexto = stream_context_create(array('phar' =>
|
|
array('compress' => Phar::GZ)),
|
|
array('metadata' => array('user' => 'cellog')));
|
|
file_put_contents('phar://mi.phar/fichero.php', 0, $contexto);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
La envoltura de flujos <literal>phar</literal> no opera sobre ficheros remotos,
|
|
y no puede operar sobre ficheros remotos, and cannot operate on remote files, and so is allowed even when the
|
|
<link linkend="ini.allow-url-fopen">allow_url_fopen</link> and
|
|
<link linkend="ini.allow-url-include">allow_url_include</link> INI options
|
|
are disabled.
|
|
</para>
|
|
<para>
|
|
Aunque es posible crear archivos phar desde cero simplemente usando
|
|
operaciones de flujos, es mejor utilizar la funcionalidad interna
|
|
de la clase Phar. La envoltura de flujos se usa mejor para operaciones de sólo lectura.
|
|
</para>
|
|
</section>
|
|
<section xml:id="phar.using.object" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Utilizar Archivos Phar: las clases Phar y PharData</title>
|
|
<para>
|
|
La clase <classname>Phar</classname> admite la lectura y la manipulación
|
|
de archivos Phar, así como la iteración a través de la funcionalidad de
|
|
la clase <classname>RecursiveDirectoryIterator</classname>.
|
|
Con el soporte para la interfaz <classname>ArrayAccess</classname>,
|
|
se puede acceder a los ficheros que están dentro de un archivo Phar como si fueran
|
|
parte de un array asociativo.
|
|
</para>
|
|
<para>
|
|
La clase <classname>PharData</classname> extiende la clase <classname>Phar</classname>, y
|
|
permite crear y modificar archivos tar y zip no ejecutables (datos) incluso si
|
|
<literal>phar.readonly</literal>=1 en php.ini. Por lo tanto,
|
|
<function>PharData::setAlias</function> y <function>PharData::setStub</function>
|
|
están desactivados ya que los conceptos de alias y rutina de interoperabilidad (stub) son válidos únicamente para archivos
|
|
phar ejecutables.
|
|
</para>
|
|
<para>
|
|
Observe que al crear un archivo Phar, se debería pasar la
|
|
ruta completa al contructor del objeto de la clase <classname>Phar</classname>.
|
|
Las rutas relativas causarán un error en la inicialización.
|
|
</para>
|
|
<para>
|
|
Asumiendo que <literal>$p</literal> es un objeto de la clase Phar inicializado como sigue:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$p = new Phar('/ruta/a/miphar.phar', 0, 'miphar.phar');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
se creará un archivo Phar vacío en <literal>/ruta/a/miphar.phar</literal>,
|
|
o si <literal>/ruta/a/miphar.phar</literal> ya existe, se abrirá
|
|
de nuevo. El literal <literal>miphar.phar</literal> demuestra el concepto de un alias
|
|
que puede ser usado para referenciar a <literal>/ruta/a/miphar.phar</literal> en URLs, como en:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// estas dos llamadas a file_get_contents() son equivalentes si
|
|
// /ruta/a/miphar.phar tiene un alias especificado como "miphar.phar"
|
|
// en su manifiesto, o si el phar fue inicializado con la
|
|
// configuración del objeto Phar del ejemplo anterior
|
|
$f = file_get_contents('phar:///ruta/a/miphar.phar/loquesea.txt');
|
|
$f = file_get_contents('phar://miphar.phar/loquesea.txt');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Con el recién creado objeto <literal>$p</literal> de la clase <classname>Phar</classname>,
|
|
lo siguiente es posible:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>$a = $p['fichero.php']</literal> creates a <classname>PharFileInfo</classname>
|
|
class that refers to the contents of <literal>phar://miphar.phar/fichero.php</literal>
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>$p['fichero.php'] = $v</literal> crea un nuevo fichero
|
|
(<literal>phar://miphar.phar/fichero.php</literal>), o sobrescribe
|
|
un fichero existente dentro de <literal>miphar.phar</literal>. <literal>$v</literal>
|
|
puede ser una cadena o un puntero de fichero abierto, en cuyo caso todo el
|
|
contenido del fichero se usará para crear el nuevo fichero. Observe que
|
|
<literal>$p->addFromString('fichero.php', $v)</literal> es funcionalmente
|
|
equivalente a lo de más arriba. También es posible añadir el contenido de un fichero
|
|
con <literal>$p->addFile('/path/to/fichero.php', 'fichero.php')</literal>.
|
|
Por ultimo, se puede crear un directorio vacío con
|
|
<literal>$p->addEmptyDir('vacio')</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>isset($p['fichero.php'])</literal> se puede usar para determinar
|
|
si <literal>phar://miphar.phar/fichero.php</literal> existe dentro de
|
|
<literal>miphar.phar</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
<literal>unset($p['fichero.php'])</literal> borra
|
|
<literal>phar://miphar.phar/fichero.php</literal> de
|
|
<literal>miphar.phar</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Además, el objeto de la clase <classname>Phar</classname> es la única manera de acceder
|
|
a metainformación específica de Phar, a través de
|
|
<function>Phar::getMetadata</function>,
|
|
y la única manera de establecer o recuperar una rutina de interoperabilidad (stub) del cargador de PHP de un archivo Phar a través de
|
|
<function>Phar::getStub</function> y
|
|
<function>Phar::setStub</function>.
|
|
Además, la compresión del archivo completo Phar de una vez, sólo puede ser manipulada
|
|
utilizando la clase <classname>Phar</classname>.
|
|
</para>
|
|
<para>
|
|
La lista completa de la funcionalidad de objetos de la clase <classname>Phar</classname> está documentada
|
|
más adelante.
|
|
</para>
|
|
<para>
|
|
La clase <classname>PharFileInfo</classname> extiende a la
|
|
clase <classname>SplFileInfo</classname>,
|
|
y añade varios métodos para manipular detalles específicos de Phar de un fichero
|
|
contenido en un Phar, tales como la manipulación de la compresión y la metainformación.
|
|
</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
|
|
-->
|