pecl.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d1fa3096926b6cbaf9da1f831b6fe3302ae2e490 Maintainer: leonardolara Status: ready --><!-- CREDITS: narigone,ae,mauricio,adiel,leonardolara -->

<chapter xml:id="install.pecl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Instalação das extensões PECL</title>

 <sect1 xml:id="install.pecl.intro">
  <title>Introdução às Instalações PECL</title>
  &pecl.moving.to.pie;
  <simpara>
   &link.pecl; é um repositório de extensões PHP disponibilizadas através do
   sistema de pacotes <link xlink:href="&url.php.pear;">PEAR</link>.
   <!---->
   Esta seção do manual destina-se a demonstrar como obter e instalar extensões
   PECL.
  </simpara>
  <simpara>
   Estas instruções assumem que <literal>/path/to/php/src/dir/</literal> seja o
   caminho para o código-fonte do PHP e que <literal>extname</literal>
   seja o nome da extensão PECL. Ajuste adequadamente.
   Estas instruções também assumem uma familiaridade com o
   <link xlink:href="&url.php.pear.cli;">comando pear</link>.
   As informações no manual do PEAR para o comando
   <command>pear</command>
   também se aplicam ao comando
   <command>pecl</command>.
   <!---->
  </simpara>
  <simpara>
   Uma extensão compartilhada deve ser compilada, instalada e carregada para ser útil.
   Os métodos descritos abaixo fornecem várias instruções sobre como criar e
   instalar as extensões, mas não as carregam automaticamente.
   As extensões podem ser carregadas adicionando
   uma diretiva <link linkend="ini.extension">extension</link>
   ao arquivo &php.ini; ou através do uso da
   função
   <function>dl</function>.
  </simpara>
  <simpara>
   Ao compilar módulos PHP, é importante ter as versões apropriadas das
   ferramentas necessárias (autoconf, automake, libtool, etc.).
   Consulte as
   <link xlink:href="&url.php.anongit;">Instruções para Acesso Anônimo ao Git</link>
   para obter detalhes sobre as ferramentas e versões necessárias.
  </simpara>
 </sect1>

 <sect1 xml:id="install.pecl.downloads">
  <title>Baixando extensões PECL</title>
  &pecl.moving.to.pie;
  <simpara>
   Existem várias opções para baixar extensões PECL, como:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     O comando <command>pecl install extname</command> baixa o código das
     extensões automaticamente, portanto, neste caso, não há necessidade de
     baixar separadamente.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <link xlink:href="&url.pecl;">&url.pecl;</link>
    </simpara>
    <simpara>
     O site do PECL contém informações sobre as extensões que a equipe de
     desenvolvimento do PHP oferece.
     As informações disponíveis aqui incluem changelogs, notas de versão,
     requisitos e outros detalhes semelhantes.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <command>pecl download extname</command>
    </simpara>
    <simpara>
     As extensões PECL que possuem versões listadas no site do PECL estão
     disponíveis para download e instalação usando o
     <link xlink:href="&url.php.pear.cli;">comando pecl</link>.
     Revisões específicas também podem ser especificadas.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>git</acronym>
    </simpara>
    <simpara>
     Muitas extensões PECL podem ser encontradas no GitHub.
     <!-- TODO Expand -->
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>SVN</acronym>
    </simpara>
    <simpara>
     Algumas extensões PECL também podem ser encontradas no <acronym>SVN</acronym>.
     Uma visualização web pode ser encontrada em
     <link xlink:href="&url.php.svn;pecl/">&url.php.svn;pecl/</link>.
     Para baixar direto do <acronym>SVN</acronym>,
     os seguintes comandos podem ser usados:
    </simpara>
    <screen>
<![CDATA[
$ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname
]]>
    </screen>
   </listitem>
   <listitem>
    <simpara>
     Downloads do Windows
    </simpara>
    <simpara>
     O Projeto PHP compila e oferece DLLs do Windows para a maioria das
     extensões PECL na página do pacote.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 xml:id="install.pecl.windows">
  <title>Instalando uma extensão PHP no Windows</title>
  <para>
   Existem duas maneiras de carregar uma extensão PHP no Windows: compilando-a
   no PHP ou carregando a DLL.
   Carregar uma extensão pré-compilada é a maneira mais fácil e preferida.
  </para>
  <para>
   Para carregar uma extensão, ela deve estar disponível como um arquivo
   <filename>.dll</filename>
   no sistema.
   Todas as extensões são compiladas automaticamente e periodicamente pelo PHP
   Group (veja a próxima seção para download).
  </para>
  <para>
   Para compilar uma extensão no PHP, consulte a documentação sobre
   <link
   linkend="install.windows.building">compilação do código-fonte</link>.
  </para>
  <para>
   Para compilar uma extensão independente (um arquivo DLL), consulte a
   documentação sobre
   <link linkend="install.windows.building">compilação do código-fonte</link>.
   Se a DLL não estiver disponível na distribuição do PHP nem no PECL,
   pode ser necessário compilá-la antes que a extensão possa ser usada.
  </para>
  <sect2 xml:id="install.pecl.windows.find">
   <title>Onde encontrar uma extensão?</title>
   <para>
    As extensões do PHP geralmente são chamadas de
    <filename>php_*.dll</filename>
    (onde o asterisco representa o nome da extensão) e estão localizadas no
    diretório <filename>PHP\ext</filename>.
   </para>
   <para>
    O PHP vem com as extensões mais úteis para a maioria dos desenvolvedores.
    Elas são chamadas extensões <emphasis>nativas</emphasis> do PHP.
   </para>
   <para>
    Entretanto, se as extensões nativas não fornecerem a funcionalidade necessária,
    uma extensão que ofereça essa funcionalidade ainda pode ser encontrada no &link.pecl;.
    A biblioteca comunitária de extensões PHP (PECL) é um repositório de extensões PHP, que fornece um
    diretório de todas as extensões conhecidas e recursos de hospedagem para
    download e desenvolvimento de extensões PHP.
   </para>
   <para>
    Se uma extensão foi desenvolvida para usos específicos, ela pode ser hospedada no
    PECL para que outras pessoas com as mesmas necessidades possam se beneficiar delas.
    Um bom efeito colateral é que é uma excelente chance de receber feedbacks,
    agradecimentos, relatórios de erros e até mesmo correções/patches.
    Antes de enviar uma extensão para hospedagem no PECL, consulte sobre
    <link xlink:href="&url.pecl.submit;">Submissão ao PECL</link>.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.which">
   <title>Qual extensão baixar?</title>
   <para>
    <emphasis>
     Muitas vezes, haverá várias versões disponíveis de cada DLL:
    </emphasis>
    <itemizedlist>
     <listitem>
      <simpara>
       Números de versão diferentes (pelo menos os dois primeiros números devem corresponder)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Versões de thread safety diferentes
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Arquitetura de processador diferente (x86, x64, ...)
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Configurações de depuração diferentes
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>etc.</literal>
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Lembre-se de que as configurações de extensão devem corresponder a todas as
    configurações do executável PHP que está sendo usado.
    O script a seguir informará <emphasis>tudo</emphasis> sobre as configurações
    do PHP:
   </para>
   <para>
    <example>
     <title>
      A função
      <function>phpinfo</function>
     </title>
     <programlisting role="php">
<![CDATA[
<?php
phpinfo();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Ou na linha de comando, execute:
    <screen>
<![CDATA[
drive:\caminho\para\o\executavel\php.exe -i
]]>
    </screen>
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.loading">
   <title>Carregando uma extensão</title>
   <para>
    A forma mais comum de carregar uma extensão PHP é incluí-la no
    arquivo de configuração &php.ini;.
    Observe que muitas extensões já estão presentes no &php.ini; e
    só é preciso remover o ponto e vírgula para ativá-las.
   </para>
   <para>
    A partir do PHP 7.2.0, o nome da extensão pode ser usado
    ao invés do nome do arquivo da extensão.
    Como é independente do sistema operacional é mais fácil, especialmente para iniciantes, essa
    é a maneira recomendada de especificar as extensões a serem carregadas.
    Os nomes dos arquivos continuam suportados para compatibilidade com versões anteriores.
   </para>
   <screen>
<![CDATA[
;extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
extension=php_extname.dll
]]>
   </screen>
   <screen>
<![CDATA[
; A partir do PHP 7.2.0, prefira:
extension=extname
zend_extension=another_extension
]]>
   </screen>
   <para>
    No entanto, isso pode causar confusão em alguns servidores web porque eles
    não usam o arquivo &php.ini; localizado junto do executável PHP.
    Para descobrir onde o arquivo &php.ini; está, procure seu caminho na
    função <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>
    Depois de ativar uma extensão, salve o arquivo &php.ini;, reinicie o
    servidor web e verifique a função <function>phpinfo</function> novamente.
    A nova extensão agora deve ter sua própria seção.
   </para>
  </sect2>

  <sect2 xml:id="install.pecl.windows.problemsolving">
   <title>Resolvendo problemas</title>
   <para>
    Se uma extensão não aparecer na função <function>phpinfo</function>,
    os logs devem ser verificados para saber de onde vem o problema.
   </para>
   <para>
    Se o PHP estiver sendo usado na linha de comando (CLI),
    os erros de carregamento da extensão podem ser lidos diretamente na tela.
   </para>
   <para>
    Se o PHP estiver sendo usado com um servidor web, a localização e o formato
    dos logs irão variar dependendo do software usado.
    Consulte a documentação do servidor web para localizar os logs,
    pois isso não está relacionado com o PHP.
   </para>
   <para>
    Problemas comuns são a localização da DLL e das DLLs das quais ela depende,
    o valor da diretiva "<link linkend="ini.extension-dir">extension_dir</link>"
    no arquivo &php.ini; e incompatibilidades de configuração em tempo de compilação.
   </para>
   <para>
    Se o problema estiver em uma incompatibilidade de configuração em tempo de
    compilação, provavelmente a DLL errada foi baixada.
    Tente baixar novamente a extensão com as configurações corretas.
    Novamente, a função <function>phpinfo</function> pode ser de grande ajuda.
   </para>
  </sect2>

 </sect1>

 <sect1 xml:id="install.pecl.pear">
  <title>Compilando extensões PECL compartilhadas com o comando pecl</title>
  <simpara>
   O PECL facilita a criação de extensões PHP compartilhadas.
   Usando o
   <link xlink:href="&url.php.pear.cli;">comando pecl</link>,
   faça o seguinte:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname
]]>
  </screen>
  <simpara>
   Isso fará o download do código-fonte de <emphasis>extname</emphasis>,
   compilará e instalará <filename>extname.so</filename> em
   <link linkend="ini.extension-dir">extension_dir</link>.
   <filename>extname.so</filename>
   pode então ser carregada usando o &php.ini;.
  </simpara>
  <simpara>
   Por padrão, o comando <command>pecl</command> não instalará pacotes
   marcados com o estado <literal>alpha</literal>
   ou
   <literal>beta</literal>.
   Se nenhum pacote <literal>stable</literal> estiver disponível,
   um pacote <literal>beta</literal> pode ser instalado usando o seguinte
   comando:
  </simpara>
  <screen>
<![CDATA[
$ pecl install extname-beta
]]>
  </screen>
  <para>
   Uma versão específica também pode ser instalada usando esta forma:
  </para>
  <screen>
<![CDATA[
$ pecl install extname-0.1
]]>
  </screen>
  <note>
   <para>
    Depois de habilitar a extensão no &php.ini;, será necessário reiniciar
    o serviço web para que as alterações sejam detectadas.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="install.pecl.phpize">
  <title>Compilando extensões PECL compartilhadas com phpize</title>
  <simpara>
   Às vezes, usar o instalador <command>pecl</command> não é uma opção.
   Isso pode ocorrer porque há um firewall ou porque a extensão que está sendo
   instalada não está disponível como um pacote compatível com o PECL,
   como extensões não lançadas do git.
   Se tal extensão precisar ser compilada, as ferramentas de compilação de baixo
   nível podem ser usadas para realizar a compilação manualmente.
  </simpara>
  <simpara>
   O comando <command>phpize</command> é usado para preparar o ambiente de
   compilação para uma extensão PHP.
   No exemplo a seguir, o código-fonte de uma extensão está em um diretório
   chamado <filename>extname</filename>:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd extname
$ phpize
$ ./configure
$ make
# make install
]]>
   </screen>
  </para>
  <simpara>
   Uma instalação bem sucedida criará um arquivo <filename>extname.so</filename>
   e o colocará no diretório de extensões PHP
   <link linkend="ini.extension-dir">extension_dir</link>.
   O arquivo &php.ini; precisará ser ajustado, e uma
   linha <literal>extension=extname.so</literal>
   precisará ser adicionada antes que a extensão possa ser usada.
  </simpara>
  <simpara>
   Se o sistema não tiver o comando <command>phpize</command> e pacotes
   pré-compilados (como os do RPM) forem usados, certifique-se também de instalar a versão
   de desenvolvimento apropriada dos pacotes PHP, pois ela geralmente inclui o
   comando <command>phpize</command>
   juntamente com os arquivos de cabeçalho apropriados para compilar o PHP e suas extensões.
  </simpara>
  <simpara>
   Execute <command>phpize --help</command> para exibir informações de uso
   adicionais.
  </simpara>
 </sect1>

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

  <para>
   <command>php-config</command>
   é um script shell para obter informações sobre a configuração do PHP
   instalado.
  </para>

  <para>
   Quando as extensões estão sendo compiladas, se várias versões do PHP
   estiverem instaladas, a instalação para a qual compilar pode ser especificada
   usando a opção
   <option role="configure">--with-php-config</option>
   durante a configuração, definindo o caminho do respectivo script
   <command>php-config</command>.
  </para>

  <para>
   A lista de opções de linha de comando fornecida pelo script
   <command>php-config</command>
   pode ser consultada a qualquer momento executando
   <command>php-config</command>
   com a opção <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>Opções de linha de comando</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Opção</entry>
       <entry>Descrição</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>--prefix</entry>
       <entry>Prefixo do diretório onde o PHP está instalado, por exemplo /usr/local</entry>
      </row>
      <row>
       <entry>--includes</entry>
       <entry>
        Lista de opções <literal>-I</literal> com todos os arquivos de inclusão.
       </entry>
      </row>
      <row>
       <entry>--ldflags</entry>
       <entry>
        Flags <literal>LD</literal> com as quais o PHP foi compilado.
       </entry>
      </row>
      <row>
       <entry>--libs</entry>
       <entry>Bibliotecas extras com as quais o PHP foi compilado.</entry>
      </row>
      <row>
       <entry>--extension-dir</entry>
       <entry>Diretório onde as extensões são pesquisadas por padrão.</entry>
      </row>
      <row>
       <entry>--include-dir</entry>
       <entry>
        Prefixo do diretório onde os arquivos de cabeçalho são instalados por
        padrão.
       </entry>
      </row>
      <row>
       <entry>--php-binary</entry>
       <entry>Caminho completo para o binário php CLI ou CGI.</entry>
      </row>
      <row>
       <entry>--php-sapis</entry>
       <entry>Exibe todos os módulos SAPI disponíveis.</entry>
      </row>
      <row>
       <entry>--configure-options</entry>
       <entry>
        Opções de configuração para recriar a configuração da instalação atual do PHP.
       </entry>
      </row>
      <row>
       <entry>--version</entry>
       <entry>Versão do PHP.</entry>
      </row>
      <row>
       <entry>--vernum</entry>
       <entry>Versão do PHP como inteiro.</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </sect1>

 <sect1 xml:id="install.pecl.static">
  <title>Compilando extensões PECL estaticamente no PHP</title>
  <simpara>
   Às vezes, pode ser necessário criar uma extensão PECL estaticamente no binário do PHP.
   Para isso, o código-fonte da extensão precisará ser colocado no diretório
   <filename>/caminho/para/o/diretorio/php/src/ext/</filename>,
   e será necessário que o sistema de compilação do PHP gere o script de
   configuração novamente.
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd /caminho/para/o/diretorio/php/src/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname
]]>
   </screen>
  </para>
  <simpara>
   Isso resultará no seguinte diretório:
  </simpara>
  <screen>
<![CDATA[
/caminho/para/o/diretorio/php/src/ext/extname
]]>
  </screen>
  <simpara>
   Depois disso, o PHP precisa ser forçado a reconstruir o script de
   configuração e, em seguida, pode ser compilado normalmente:
  </simpara>
  <screen>
<![CDATA[
$ cd /caminho/para/o/diretorio/php/src
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
]]>
  </screen>
  <note>
   <simpara>
    Para executar o script <command>buildconf</command>, o
    <command>autoconf</command>
    <literal>2.68</literal>
    e o
    <command>automake</command>
    <literal>1.4+</literal>
    serão necessários.
    As versões mais recentes do <command>autoconf</command> podem funcionar,
    mas não são suportadas.
   </simpara>
  </note>
  <simpara>
   O uso de
   <option role="configure">--enable-extname</option>
   ou
   <option role="configure">--with-extname</option>
   depende da extensão.
   Normalmente, uma extensão que não requer bibliotecas externas usa
   <option role="configure">--enable</option>.
   Para ter certeza, execute o seguinte após <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
-->