archived-doc-es/install/pecl.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 10fd0ed41bec930e789c111c611486d6d7c38a98 Maintainer: chuso 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 en PECL</title>
  <simpara>
   <link xlink:href="&url.pecl;">PECL</link> es un respositorio de extensiones de PHP
   disponible mediante el sistema de paquetes <link xlink:href="&url.php.pear;">PEAR</link>.
   Esta sección del manual tiene por objetivo ilustrar cómo obtener e instalar
   extensiones PECL.
  </simpara>
  <simpara>
   Estas instrucciones asumen que la ruta al fuente de su distribución de PHP es
   <literal>/your/phpsrcdir/</literal>, y que <literal>extname</literal> es el nombre
   de la extensión PECL. Ajuste a sus valores. Estas instrucciones, además, asumen
   conocimientos del <link xlink:href="&url.php.pear.cli;">comando pear</link>.
   La información del manual de PEAR para el comando <literal>pear</literal> también
   es aplicable al comando <literal>pecl</literal>.
  </simpara>
  <simpara>
   Para poder usarse, una extensión compartida se debe construir, instalar, y cargar.
   Los métodos descritos abajo le proporcionan varias instrucciones para construir
   e instalar extensiones, pero no se cargarán automáticamente.
   Éstas se pueden cargar añadiendo una directiva <link
   linkend="ini.extension">extension</link>. al fichero &php.ini;,
   o bien mediante el uso de la función <function>dl</function>.
  </simpara>
  <simpara>
   Al construir un módulo PHP, es importante contar con las versiones correctas
   de las herramientas requeridas (autoconf, automake, libtool, etc.). Para
   conocer los detalles de las herramientas requeridas y sus versiones, revise las
   <link xlink:href="&url.php.anongit;">Instrucciones de Git Anónimo</link>.
  </simpara>
 </sect1>
 
 <sect1 xml:id="install.pecl.downloads">
  <title>Descarga de extensiones PECL</title>
  <simpara>
   Existen varias opciones para descargar extensiones PECL, a saber:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     El comando <literal>pecl install extname</literal> descarga el código
     de la extensión automáticamente, de modo que en este caso no se hace necesario
     realizar una descarga por separado.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link xlink:href="&url.pecl;">&url.pecl;</link>
    </simpara>
    <simpara>
     La página web de PECL contiene información sobre las diferentes extensiones
     que ofrece el Equipo de Desarrollo de PHP. La información disponible aquí
     incluye: ChangeLog, notas de la versión, requisitos, y otros detalles similares.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <literal>pecl download extname</literal>
    </simpara>
    <simpara>
     Puede descargar e instalar las extensiones PECL listadas en el sitio
     web de PECL usando el <link xlink:href="&url.php.pear.cli;">comando pecl</link>.
     También se podrán especificar versiones concretas.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>SVN</acronym>
    </simpara>
    <simpara>
     La mayor parte de las extensiones PECL también están alojadas en <acronym>SVN</acronym>.
     Puede consultar la interfaz web en <link xlink:href="&url.php.svn;pecl/">&url.php.svn;pecl/</link>.  
     Para descargar directamente del <acronym>SVN</acronym>, debe usar la siguiente
     secuencia de comandos:
    </simpara>
    <para>
     <screen>
      $ svn checkout http://svn.php.net/repository/pecl/extname/trunk extname
     </screen>
    </para>
   </listitem>
   <listitem>
    <simpara>
     Descargas para Windows
    </simpara>
    <simpara>
     Actualmente el proyecto PHP no compila binarios para Windows
     de las extensiones PECL. En cualquier caso, para compilar PHP
     bajo Windows, revise el capítulo titulado
     <link linkend="install.windows.building">construcción de la fuente en Windows</link>.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>
 
 <sect1 xml:id="install.pecl.windows">
  <title>Instalación una extensión de PHP en Windows</title>
  <para>
   Dispone de dos formas para cargar extensiones PHP en Windows: o bien compilándolas en PHP,
   o bien cargando su DLL. El método recomendado y más sencillo es cargar una extensión pre-compilada.
  </para>
  <para>
   Para cargar una extensión, debe estar disponible como fichero ".dll" en su sistema.
   Todas las extensiones son compiladas por el Grupo PHP automática y periódicamente
   (revise la siguiente sección para realizar descargas).
  </para>
  <para>
   Para compilar una extensión en PHP, por favor, acceda a la documentación de
   <link linkend="install.windows.building">construcción de la fuente</link>.
  </para>
  <para>
   Para compilar una extensión independiente (o lo que es lo mismo, un fichero DLL), por favor, revise la
   documentación de <link linkend="install.windows.building">construcción de la fuente</link>.
   Si el fichero DLL no está disponible ni en su distribución de PHP ni en PECL, deberá compilarla
   antes de poder comenzar a usarla.
  </para>
  
  <sect2 xml:id="install.pecl.windows.find">
   <title>¿Dónde encontrar una extensión?</title>
   <para>
    Las extensiones de PHP generalmente se llaman "php_*.dll" (donde el asterisco representa
    el nombre de la extensión) y se localizan bajo la carpeta "PHP\ext".
   </para>
   <para>
    PHP se distribuye con las extensiones más útiles para la mayoría de desarrolladores. Se les llama
    extensiones del "núcleo".
   </para>
   <para>
    En cualquier caso, si necesita una funcionalidad que no proporciona ninguna de las extensiones
    del núcleo, podrá buscarla en PECL. La Biblioteca de la Comunidad de Extensiones de PHP (PECL) es
    un repositorio de extensiones PHP, que proporciona un directorio de todas las extensiones conocidas,
    y aloja utilidades para descargar y desarrollar extensiones de PHP.
   </para>
   <para>
    Si usted ha desarrollado una extensión para su propio uso, quizá quiera considerar alojarla
    en PECL, de forma que otros desarrolladores con las mismas necesidades puedan verse beneficiados
    de su tiempo. Una de las ventajas es que tendrá la oportunidad de recibir colaboración,
    (ojalá) agradecimientos, informes de errores, e incluso parches/correcciones. Antes de enviar
    su extensión para ser alojada en PECL, por favor, lea
    <link xlink:href="&url.pecl.submit;">el envío a PECL</link>.
   </para>
  </sect2>
  
  <sect2 xml:id="install.pecl.windows.which">
   <title>¿Qué extensión descargar?</title>
   <para>
    <emphasis>A menudo, encontrará varias versiones de cada DLL:</emphasis>
    <itemizedlist>
     <listitem>
      <simpara>
       Números de versión diferentes (al menos los dos primeros números deben coincidir)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Diferentes ajustes de seguridad en hilos
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Diferentes arquitecturas de procesadores (x86, x64, ...)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Diferentes ajustes de depuración
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>etc.</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Debe tener en cuenta que los ajustes de su extensión deben coincidir con la configuración
    del ejecutable de PHP que está utilizando. El siguiente script de PHP le dirá
    <emphasis>todo</emphasis> sobre sus ajustes de PHP:
   </para>
   <para>
    <example>
     <title>llamada a <function>phpinfo</function></title>
     <programlisting role="php">
<![CDATA[
<?php
phpinfo();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    O ejecute desde la línea de comandos:
    <screen>
<![CDATA[
drive:\\path\to\php\executable\php.exe -i
]]>
    </screen>
   </para>
  </sect2>
  
  <sect2 xml:id="install.pecl.windows.loading">
   <title>Cargando una extensión</title>
   <para>
    La forma más común de cargar una extensión PHP consiste en incluirla en el fichero de configuración
    <filename>php.ini</filename>. Por favor, tenga en cuenta que ya hay muchas extensiones
    presentes en el fichero <filename>php.ini</filename> y que sólo es necesario eliminar el punto y coma
    para activarlas.
    <screen>
<![CDATA[
;extension=php_extname.dll
]]>
    </screen>
    <screen>
<![CDATA[
extension=php_extname.dll
]]>
    </screen>
   </para>
   <para>
    Sin embargo, algunos servidores web puede resultar confusos, dado que no utilizan el <filename>php.ini</filename>
    ubicado junto al ejecutable de PHP. Para averiguar dónde se localiza el <filename>php.ini</filename> en uso,
    consulte su ruta usando <function>phpinfo</function>:
    <screen>
<![CDATA[
Configuration File (php.ini) Path  C:\WINDOWS
]]>
    </screen>
    <screen>
<![CDATA[
Loaded Configuration File   C:\Program Files\PHP\5.2\php.ini
]]>
    </screen>
   </para>
   <para>
    Tras activar una extensión, guarde el fichero <filename>php.ini</filename>, reinicie el servidor web y
    vuelva a comprobar <function>phpinfo</function>. La nueva extensión debe ahora tener su propia sección.
   </para>
  </sect2>
  
  <sect2 xml:id="install.pecl.windows.problemsolving">
   <title>Resolviendo problemas</title>
   <para>
    Si la extensión no aparece en <function>phpinfo</function>, compruebe los registro de errores
    para conocer qué provoca el problema.
   </para>
   <para>
    Si está utilizando PHP desde la línea de comandos (CLI), podrá leer directamente en pantalla
    el error en la carga de la extensión.
   </para>
   <para>
    Si está usando PHP en un servidor web, la localización y formato de los registros vería en función
    de su software. Por favor, lea la documentación de su servidor web para localizar los registros,
    dado que esto no lo gestiona el propio ejecutable de PHP.
   </para>
   <para>
    Los problemas más comunes son la ubicación del fichero DLL, el valor de "<link linkend="ini.extension-dir">
    extension_dir</link>" en <filename>php.ini</filename>, y desajustes de configuración en tiempo
    de compilación.
   </para>
   <para>
    Si el problema reside en desajustes de configuración en tiempo de compilación, seguramente se deba a que no
    se ha descargado el fichero DLL correcto. Pruebe a descargar de nuevo la extensión con los ajustes correctos.
    De nuevo, <function>phpinfo</function> puede resultar de gran ayuda.
   </para>
  </sect2>
  
 </sect1>
 
 <sect1 xml:id="install.pecl.pear">
  <title>Compilando 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>
  <para>
   <screen>
    $ pecl install extname
   </screen>
  </para>
  <simpara>
   Esto descargará el código fuente de <emphasis>extname</emphasis>, 
   lo compilará, e instalará <filename>extname.so</filename> en su <link
   linkend="ini.extension-dir">extension_dir</link>.  
   Ahora se puede cargar <filename>extname.so</filename> mediante &php.ini;
  </simpara>
  <simpara>
   Por omisión, el comando <literal>pecl</literal> no instalará paquetes
   marcados en los estados <literal>alpha</literal> o <literal>beta</literal>.
   Si no hay paquetes disponibles en estado <literal>stable</literal>,
   podrá instalar un paquete en estado <literal>beta</literal> utilizando el siguiente
   comando:
  </simpara>
  <para>
   <screen>
    $ pecl install extname-beta
   </screen>
  </para>
  <para>
   Del mismo modo, podrá también instalar una versión en concreto usando esta variante:
  </para>
  <para>
   <screen>
    $ pecl install extname-0.1
   </screen>
  </para>
  <note>
   <para>
    Tras activar la extensión en &php.ini;, será necesario reiniciar el servidor web
    para hacer efectivos los cambios.
   </para>
  </note>
 </sect1>
 
 <sect1 xml:id="install.pecl.phpize">
  <title>Compilando extensiones PEC compartidas con phpize</title>
  <simpara>
   A menudo no es posible utilizar el instalador <literal>pecl</literal>.
   Esto se puede deber a que se encuentra tras un cortafuegos, o a que
   la extensión que trata de instalar no está disponible como paquete compatible
   con PECL, como por ejemplo extensiones no liberadas desde el SVN. Si necesita
   construir una extensión de este tipo, puede llevar a cabo esta tarea manualmente
   utilizando las herramientas de construcción de bajo nivel.
  </simpara>
  <simpara>
   El comando <literal>phpize</literal> se utiliza para preparar el entorno
   de compilación de la extensión de PHP. En el siguiente ejemplo, el fuente de una extensión
   se ubica en un directorio llamado <filename>extname</filename>:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd extname
$ phpize
$ ./configure
$ make
# make install
]]>
   </screen>
  </para>
  <simpara>
   En caso de que la instalación sea correcta, se creará <filename>extname.so</filename>
   y se salvará en el <link linkend="ini.extension-dir">directorio de extensiones</link>
   de PHP.  Quizá necesite ajustar el fichero &php.ini; y añadir una línea
   <literal>extension=extname.so</literal> antes de poder usar la extensión.
  </simpara>
  <simpara>
   Si el sistema no contiene el comando <literal>phpize</literal>, y se están utilizando
   paquetes pre-compilados (como RPM), asegúrese de instalar también la
   versión de desarrollo apropiada del paquete PHP, dado que a menudo incluyen
   el comando <literal>phpize</literal> con los ficheros de cabeceras necesarios
   para construir PHP y sus extensiones.
  </simpara>
  <simpara>
   Ejecute <command>phpize --help</command> para mostrar información de uso adicional.
  </simpara>
 </sect1>
 
 <sect1 xml:id="install.pecl.php-config">
  <title>php-config</title>
  
  <para>
   php-config es una utilidad de consola que permite obtener información sobre
   la configuración de la instalación de PHP.
  </para>
  
  <para>
   A la hora de compilar extensiones, si se tuvieran varias versiones de PHP instaladas,
   se podrá especificar sobre cuál se va a construir usando el modificador
   <literal>--with-php-config</literal> durante la configuración, donde especificaremos
   la ruta a su respecto script php-config.
  </para>
  
  <para>
   En cualquier momento podrá consutlarse la lista de opciones de la utilidad php-config
   ejecutando php-config 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 PHP está instalado, p.ej. /usr/local</entry>
      </row>
      <row>
       <entry>--includes</entry>
       <entry>Lista de opciones -I con todos los ficheros incluídos</entry>
      </row>
      <row>
       <entry>--ldflags</entry>
       <entry>Banderas LD con las que se ha compilado PHP</entry>
      </row>
      <row>
       <entry>--libs</entry>
       <entry>Bibliotecas extras con las que se ha compilado PHP</entry>
      </row>
      <row>
       <entry>--extension-dir</entry>
       <entry>Directorio en el que se buscan por omisión las extensiones</entry>
      </row>
      <row>
       <entry>--include-dir</entry>
       <entry>Prefijo de directorio donde se buscan por omisión los ficheros de cabeceras</entry>
      </row>
      <row>
       <entry>--php-binary</entry>
       <entry>Ruta completa al binario de php CLI o CGI</entry>
      </row>
      <row>
       <entry>--php-sapis</entry>
       <entry>Muestra 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 en forma de entero</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>
 
 <sect1 xml:id="install.pecl.static">
  <title>Compilando extensiones PECL estáticamente en PHP</title>
  <simpara>
   Quizá necesite construir una extensión PECL estáticamente en su binario
   de PHP. Para hacer esto, necesitará ubicar el fuente de la extensión bajo
   el directorio <filename>/su/directorio_fuentes_php/ext/</filename> e indicarle al sistema de
   construcción de PHP que regenere su script de configuración.
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd /your/phpsrcdir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname
]]>
   </screen>
  </para>
  <simpara>
   Esto generará el siguiente directorio:
  </simpara>
  <para>
   <screen>
    /your/phpsrcdir/ext/extname
   </screen>
  </para>
  <simpara>
   Desde aquí, fuerce a PHP a regenerar el script de configuración, y entonces
   construya PHP con normalidad:
  </simpara>
  <para>
   <screen>
    $ cd /your/phpsrcdir 
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install
   </screen>
  </para>
  <note>
   <simpara>
    Necesitará autoconf 2.13 y automake 1.4+ para ejecutar el
    script 'buildconf' (es posible que funcionen versiones más recientes de autoconf,
    pero no están oficialmente soportadas).
   </simpara>
  </note>
  <simpara>
   Dependiendo de la extensión, utilizará <literal>--enable-extname</literal> 
   o <literal>--with-extname</literal>. Las extensiones que no requieren
   de bibliotecas externas generalmente utilizan <literal>--enable</literal>.
   Para asegurarse, ejecute el siguiente comando después de buildconf:
  </simpara>
  <para>
   <screen>
    $ ./configure --help | grep extname
   </screen>
  </para>
 </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
-->