archived-doc-es/install/pecl.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d1fa3096926b6cbaf9da1f831b6fe3302ae2e490 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="install.pecl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Instalación de extensiones PECL</title>

 <sect1 xml:id="install.pecl.intro">
  <title>Introducción a las instalaciones PECL</title>
  &pecl.moving.to.pie;
  <simpara>
   &link.pecl; es un repositorio de extensiones PHP que están disponibles a través del
   sistema de empaquetado <link xlink:href="&url.php.pear;">PEAR</link>.
   Esta sección del manual está destinada a demostrar cómo obtener e
   instalar extensiones PECL.
  </simpara>
  <simpara>
   Estas instrucciones asumen que <literal>/path/to/php/src/dir/</literal> es la
   ruta a la distribución del código fuente de PHP y que <literal>extname</literal> es
   el nombre de la extensión PECL. Ajuste según corresponda.
   Estas instrucciones también asumen familiaridad con el
   <link xlink:href="&url.php.pear.cli;">comando pear</link>.
   La información en el manual de PEAR para el
   comando <command>pear</command>
   también se aplica al
   comando <command>pecl</command>.
  </simpara>
  <simpara>
   Una extensión compartida debe ser compilada, instalada y cargada para ser útil.
   Los métodos descritos a continuación proporcionan varias instrucciones sobre cómo compilar e
   instalar las extensiones, pero no las cargan automáticamente.
   Las extensiones pueden cargarse añadiendo una
   directiva <link linkend="ini.extension">extension</link>
   al fichero &php.ini; o mediante el uso de la
   función <function>dl</function>.
  </simpara>
  <simpara>
   Al compilar módulos PHP, es importante tener versiones conocidas y buenas de las
   herramientas requeridas (autoconf, automake, libtool, etc.).
   Consulte las
   <link xlink:href="&url.php.anongit;">Instrucciones de Git Anónimo</link>
   para obtener detalles sobre las herramientas requeridas y las versiones necesarias.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.downloads">
  <title>Descarga de extensiones PECL</title>
  &pecl.moving.to.pie;
  <simpara>
   Hay varias opciones para descargar extensiones PECL, como:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     El comando <command>pecl install extname</command> descarga el
     código de la extensión automáticamente, por lo que en este caso no es necesaria una
     descarga separada.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link xlink:href="&url.pecl;">&url.pecl;</link>
    </simpara>
    <simpara>
     El sitio web de PECL contiene información sobre las diferentes extensiones que
     ofrece el Equipo de Desarrollo de PHP.
     La información disponible aquí incluye: registro de cambios, notas de la versión,
     requisitos y otros detalles similares.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <command>pecl download extname</command>
    </simpara>
    <simpara>
     Las extensiones PECL que tienen versiones publicadas en el sitio web de PECL están disponibles
     para descarga e instalación usando el
     <link xlink:href="&url.php.pear.cli;">comando pecl</link>.
     También pueden especificarse revisiones específicas.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>git</acronym>
    </simpara>
    <simpara>
     Muchas extensiones PECL residen en GitHub.
     <!-- TODO Expand -->
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>SVN</acronym>
    </simpara>
    <simpara>
     Algunas extensiones PECL también residen en <acronym>SVN</acronym>.
     Una vista basada en web puede verse en
     <link xlink:href="&url.php.svn;pecl/">&url.php.svn;pecl/</link>.
     Para descargar directamente desde <acronym>SVN</acronym>,
     puede usarse la siguiente secuencia de comandos:
    </simpara>
    <screen>
<![CDATA[
$ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname
]]>
    </screen>
   </listitem>
   <listitem>
    <simpara>
     Descargas para Windows
    </simpara>
    <simpara>
     El proyecto PHP compila y ofrece DLLs de Windows para la mayoría de las extensiones PECL
     en la página del paquete.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 xml:id="install.pecl.windows">
  <title>Instalación de una extensión PHP en Windows</title>
  <para>
   Hay dos formas de cargar una extensión PHP en Windows: compilarla en
   PHP o cargar la DLL.
   Cargar una extensión precompilada es la forma más fácil y preferida.
  </para>
  <para>
   Para cargar una extensión, debe estar disponible como un
   fichero <filename>.dll</filename>
   en el sistema.
   Todas las extensiones son compiladas automáticamente y periódicamente por el Grupo PHP
   (consulte la siguiente sección para la descarga).
  </para>
  <para>
   Para compilar una extensión en PHP, consulte la
   documentación de <link linkend="install.windows.building">compilación desde el código fuente</link>.
  </para>
  <para>
   Para compilar una extensión independiente (también conocida como un fichero DLL), consulte la
   documentación de <link linkend="install.windows.building">compilación desde el código fuente</link>.
   Si el fichero DLL no está disponible ni con la distribución de PHP ni en PECL,
   puede ser necesario compilarlo antes de que la extensión pueda usarse.
  </para>
  <sect2 xml:id="install.pecl.windows.find">
   <title>¿Dónde encontrar una extensión?</title>
   <para>
    Las extensiones PHP suelen llamarse <filename>php_*.dll</filename> (donde el
    asterisco representa el nombre de la extensión), y se encuentran en la
    carpeta <filename>PHP\ext</filename>.
   </para>
   <para>
    PHP incluye las extensiones más útiles para la mayoría de los desarrolladores.
    Se llaman extensiones <emphasis>incluidas</emphasis>.
   </para>
   <para>
    Sin embargo, si las extensiones incluidas no proporcionan la funcionalidad necesaria,
    aún puede encontrarse una extensión que lo haga en &link.pecl;.
    La Biblioteca de Extensiones de la Comunidad PHP (PECL) es un repositorio para
    Extensiones PHP, que proporciona un directorio de todas las extensiones conocidas y ofrece
    instalaciones para descargar y desarrollar extensiones PHP.
   </para>
   <para>
    Si una extensión ha sido desarrollada para usos particulares, puede estar alojada en
    PECL para que otros con las mismas necesidades puedan beneficiarse de ella.
    Un buen efecto secundario es que es una buena oportunidad para recibir comentarios,
    (con suerte) agradecimientos, informes de errores e incluso correcciones/parches.
    Antes de enviar una extensión para alojarla en PECL, lea
    <link xlink:href="&url.pecl.submit;">PECL submit</link>.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.which">
   <title>¿Qué extensión descargar?</title>
   <para>
    <emphasis>
     Muchas veces, habrá varias versiones de cada DLL disponibles:
    </emphasis>
    <itemizedlist>
     <listitem>
      <simpara>
       Diferentes números de versión (al menos los dos primeros números deben coincidir)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Diferentes configuraciones de seguridad de hilos
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Diferentes arquitecturas de procesador (x86, x64, ...)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Diferentes configuraciones de depuración
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>etc.</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Tenga en cuenta que la configuración de la extensión debe coincidir con todas las configuraciones de
    el ejecutable de PHP que se está utilizando.
    El siguiente script PHP informará <emphasis>todo</emphasis> sobre la configuración de PHP:
   </para>
   <para>
    <example>
     <title>
      Llamada a <function>phpinfo</function>
     </title>
     <programlisting role="php">
<![CDATA[
<?php
phpinfo();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    O desde la línea de comandos, ejecute:
    <screen>
<![CDATA[
drive:\path\to\php\executable\php.exe -i
]]>
    </screen>
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.loading">
   <title>Carga de una extensión</title>
   <para>
    La forma más común de cargar una extensión PHP es incluirla en el
    fichero de configuración &php.ini;.
    Tenga en cuenta que muchas extensiones ya están presentes en el &php.ini; y
    que solo es necesario eliminar el punto y coma para activarlas.
   </para>
   <para>
    Tenga en cuenta que, a partir de PHP 7.2.0, puede usarse el nombre de la extensión
    en lugar del nombre del fichero de la extensión.
    Al ser independiente del sistema operativo y más fácil, especialmente para los recién llegados, se convierte
    en la forma recomendada de especificar las extensiones a cargar.
    Los nombres de fichero siguen siendo compatibles con versiones anteriores.
   </para>
   <screen>
<![CDATA[
;extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
; A partir de PHP 7.2.0, se prefiere:
extension=extname
zend_extension=another_extension
]]>
   </screen>
   <para>
    Sin embargo, algunos servidores web son confusos porque no usan
    el &php.ini; ubicado junto al ejecutable de PHP.
    Para averiguar dónde reside el &php.ini; real, busque su ruta
    en <function>phpinfo</function>:
   </para>
   <screen>
<![CDATA[
Configuration File (php.ini) Path  C:\WINDOWS
]]>
   </screen>
   <screen>
<![CDATA[
Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini
]]>
   </screen>
   <para>
    Después de activar una extensión, guarde &php.ini;, reinicie el servidor web y
    verifique <function>phpinfo</function> nuevamente.
    La nueva extensión debería tener ahora su propia sección.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.problemsolving">
   <title>Resolución de problemas</title>
   <para>
    Si la extensión no aparece en <function>phpinfo</function>,
    deben revisarse los registros para saber de dónde proviene el problema.
   </para>
   <para>
    Si PHP se está utilizando desde la línea de comandos (CLI), el error de carga de la extensión
    puede leerse directamente en la pantalla.
   </para>
   <para>
    Si PHP se está utilizando con un servidor web, la ubicación y el formato de los registros
    varían según el software.
    Lea la documentación del servidor web para localizar los registros, ya que no tiene
    nada que ver con PHP en sí.
   </para>
   <para>
    Los problemas comunes son la ubicación de la DLL y las DLLs de las que depende, el
    valor de la configuración "<link linkend="ini.extension-dir">extension_dir</link>"
    dentro de &php.ini; y las incompatibilidades en la configuración de compilación.
   </para>
   <para>
    Si el problema radica en una incompatibilidad en la configuración de compilación, probablemente la DLL
    descargada no es la correcta.
    Intente descargar la extensión nuevamente con la configuración adecuada.
    Nuevamente, <function>phpinfo</function> puede ser de gran ayuda.
   </para>
  </sect2>

 </sect1>

 <sect1 xml:id="install.pecl.pear">
  <title>Compilación de extensiones PECL compartidas con el comando pecl</title>
  <simpara>
   PECL facilita la creación de extensiones PHP compartidas.
   Usando el
   <link xlink:href="&url.php.pear.cli;">comando pecl</link>,
   haga lo siguiente:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname
]]>
  </screen>
  <simpara>
   Esto descargará el código fuente de <emphasis>extname</emphasis>,
   lo compilará e instalará <filename>extname.so</filename> en el
   <link linkend="ini.extension-dir">extension_dir</link>.
   <filename>extname.so</filename>
   luego puede cargarse a través de &php.ini;.
  </simpara>
  <simpara>
   Por omisión, el comando <command>pecl</command> no instalará paquetes
   que estén marcados con el estado <literal>alpha</literal> o
   <literal>beta</literal>.
   Si no hay paquetes <literal>stable</literal> disponibles,
   puede instalarse un paquete <literal>beta</literal> usando el siguiente
   comando:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname-beta
]]>
  </screen>
  <para>
   También puede instalarse una versión específica usando esta variante:
  </para>
  <screen>
<![CDATA[
$ pecl install extname-0.1
]]>
  </screen>
  <note>
   <para>
    Después de habilitar la extensión en &php.ini;, es necesario reiniciar el servicio web para que
    los cambios surtan efecto.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="install.pecl.phpize">
  <title>Compilación de extensiones PECL compartidas con phpize</title>
  <simpara>
   A veces, usar el instalador <command>pecl</command> no es una opción.
   Esto podría deberse a que hay un firewall o porque la extensión que se está
   instalando no está disponible como un paquete compatible con PECL, como extensiones no publicadas
   de git.
   Si es necesario compilar dicha extensión, se pueden usar las herramientas de compilación de bajo nivel para
   realizar la compilación manualmente.
  </simpara>
  <simpara>
   El comando <command>phpize</command> se utiliza para preparar el entorno de compilación
   para una extensión PHP.
   En el siguiente ejemplo, los fuentes de una extensión están en un directorio
   llamado <filename>extname</filename>:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd extname
$ phpize
$ ./configure
$ make
# make install
]]>
   </screen>
  </para>
  <simpara>
   Una instalación exitosa habrá creado <filename>extname.so</filename> y
   lo habrá colocado en el directorio de extensiones de PHP
   <link linkend="ini.extension-dir">extensions directory</link>.
   El &php.ini; deberá ajustarse y se deberá añadir una
   línea <literal>extension=extname.so</literal>
   antes de que la extensión pueda usarse.
  </simpara>
  <simpara>
   Si el sistema no tiene el comando <command>phpize</command>, y
   se usan paquetes precompilados (como RPMs), asegúrese de instalar también la
   versión de desarrollo adecuada del paquete PHP, ya que a menudo incluyen el
   comando <command>phpize</command>
   junto con los ficheros de cabecera adecuados para compilar PHP y sus extensiones.
  </simpara>
  <simpara>
   Ejecute <command>phpize --help</command> para mostrar información adicional de uso.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.php-config">
  <title>
   <command>php-config</command>
  </title>

  <para>
   <command>php-config</command>
   es un script de shell simple para obtener información sobre la configuración instalada de PHP.
  </para>

  <para>
   Cuando las extensiones se están compilando, si hay varias versiones de PHP instaladas, la instalación para la cual
   se va a compilar puede especificarse usando la opción
   <option role="configure">--with-php-config</option>
   durante la configuración, estableciendo la ruta del script respectivo
   <command>php-config</command>.
  </para>

  <para>
   La lista de opciones de línea de comandos proporcionadas por el
   script <command>php-config</command> puede consultarse en cualquier momento ejecutando
   <command>php-config</command>
   con el modificador <option>-h</option>:
   <screen>
<![CDATA[
Usage: /usr/local/bin/php-config [OPTION]
Options:
  --prefix            [...]
  --includes          [...]
  --ldflags           [...]
  --libs              [...]
  --extension-dir     [...]
  --include-dir       [...]
  --php-binary        [...]
  --php-sapis         [...]
  --configure-options [...]
  --version           [...]
  --vernum            [...]
]]>
   </screen>
  </para>

  <para>
   <table>
    <title>Opciones de línea de comandos</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Opción</entry>
       <entry>Descripción</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>--prefix</entry>
       <entry>Prefijo del directorio donde está instalado PHP, p. ej. /usr/local</entry>
      </row>
      <row>
       <entry>--includes</entry>
       <entry>
        Lista de opciones <literal>-I</literal> con todos los ficheros de inclusión
       </entry>
      </row>
      <row>
       <entry>--ldflags</entry>
       <entry>
        <literal>LD</literal>
        flags con los que se compiló PHP
       </entry>
      </row>
      <row>
       <entry>--libs</entry>
       <entry>Bibliotecas adicionales con las que se compiló PHP</entry>
      </row>
      <row>
       <entry>--extension-dir</entry>
       <entry>Directorio donde se buscan las extensiones por omisión</entry>
      </row>
      <row>
       <entry>--include-dir</entry>
       <entry>
        Prefijo del directorio donde se instalan los ficheros de cabecera por omisión
       </entry>
      </row>
      <row>
       <entry>--php-binary</entry>
       <entry>Ruta completa al binario CLI o CGI de php</entry>
      </row>
      <row>
       <entry>--php-sapis</entry>
       <entry>Mostrar todos los módulos SAPI disponibles</entry>
      </row>
      <row>
       <entry>--configure-options</entry>
       <entry>
        Opciones de configuración para recrear la configuración de la instalación actual de PHP
       </entry>
      </row>
      <row>
       <entry>--version</entry>
       <entry>Versión de PHP</entry>
      </row>
      <row>
       <entry>--vernum</entry>
       <entry>Versión de PHP como entero</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>

 <sect1 xml:id="install.pecl.static">
  <title>Compilación de extensiones PECL estáticamente en PHP</title>
  <simpara>
   Puede ser necesario compilar una extensión PECL estáticamente en el binario de PHP.
   Para hacerlo, el código fuente de la extensión deberá colocarse bajo el
   directorio <filename>/path/to/php/src/dir/ext/</filename>,
   y el sistema de compilación de PHP deberá regenerar su script de configuración.
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd /path/to/php/src/dir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname
]]>
   </screen>
  </para>
  <simpara>
   Esto dará como resultado el siguiente directorio:
  </simpara>
  <screen>
<![CDATA[
/path/to/php/src/dir/ext/extname
]]>
  </screen>
  <simpara>
   Desde aquí, PHP necesita ser forzado a reconstruir el script de configuración, y luego
   puede ser compilado normalmente:
  </simpara>
  <screen>
<![CDATA[
$ cd /path/to/php/src/dir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
]]>
  </screen>
  <note>
   <simpara>
    Para ejecutar el script <command>buildconf</command>, se necesitarán
    <command>autoconf</command>
    <literal>2.68</literal>
    y
    <command>automake</command>
    <literal>1.4+</literal>.
    Versiones más recientes de <command>autoconf</command> pueden funcionar pero no están
    soportadas.
   </simpara>
  </note>
  <simpara>
   Si se usa
   <option role="configure">--enable-extname</option>
   o
   <option role="configure">--with-extname</option>
   depende de la extensión.
   Normalmente, una extensión que no requiere bibliotecas externas usa
   <option role="configure">--enable</option>.
   Para estar seguro, ejecute lo siguiente después de <command>buildconf</command>:
  </simpara>
  <screen>
<![CDATA[
$ ./configure --help | grep extname
]]>
  </screen>
 </sect1>
</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
-->