ini.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 15841d188475e59c105f57c9022873f2cd7467b5 Maintainer: ae Status: ready --><!-- CREDITS: royopa,diegopires,narigone,ae,leonardolara -->
<chapter xml:id="configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>Configuração em tempo de execução</title>

 <sect1 xml:id="configuration.file">
  <title>O arquivo de configuração</title>

  <simpara>
   O arquivo de configuração (&php.ini;)
   é lido quando o PHP inicia. Para as versões de módulo de servidor,
   isso acontece apenas quando o servidor web for iniciado. Para as
   versões <acronym>CGI</acronym> e <acronym>CLI</acronym>, isso acontece
   a cada invocação.
  </simpara>
  <para>
   &php.ini; é procurado nesses lugares (na ordem):
   <itemizedlist>
    <listitem>
     <simpara>
      Local específico do módulo SAPI (diretiva <literal>PHPIniDir</literal>
      no Apache 2, opção de linha de comando <literal>-c</literal> no CGI e CLI)
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      A variável de ambiente <varname>PHPRC</varname>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      A localização do arquivo <literal>php.ini</literal>
      pode ser definida para versões diferentes do PHP. A raiz do registro depende da compilação em 32 ou 64 bits do sistema operacional (SO) e do PHP.
      Para um PHP 32 bits em um SO de 32 bits ou um PHP de 64 bits em um SO de 64 bits use <literal>[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal>, Para um PHP 32 bits em um SO de 64 bits use <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>].
      Para sistema onde a compilação em bits coincida, as seguintes chaves
      são examinadas, nessa ordem:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]</literal> e
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]</literal>, onde
      x, y e z significam os valores de versão PHP major, minor e release.
      Para PHP versão 32 bits em um SO de 64 bits, as seguintes chaves são examinadas em ordem:
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]</literal>,
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]</literal> e
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]</literal>, onde
      x, y e z significam os valores de versão PHP major, minor e release.
      Se houver um valor
      para <literal>IniFilePath</literal> nestas chaves, então o primeiro
      encontrado será utilizado para a localização do <literal>php.ini</literal>
      (apenas Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]</literal> ou
      <literal>[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]</literal>, valor de
      <literal>IniFilePath</literal> (Somente Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Diretório de trabalho atual (exceto CLI).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      O diretório do servidor web (para módulo SAPI), ou diretório do PHP
      (caso contrário, no Windows).
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Diretório do Windows (<filename class="directory">C:\windows</filename>
      ou <filename class="directory">C:\winnt</filename>) (para Windows), ou
      a opção de tempo de compilação <literal>--with-config-file-path</literal> .
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   Se <filename>php-SAPI.ini</filename> existe (onde SAPI é o SAPI usado, então o
   nome de arquivo é, por exemplo, <filename>php-cli.ini</filename> ou
   <filename>php-apache.ini</filename>), é usado ao invés do arquivo &php.ini;.
   O nome SAPI pode ser determinado pela função <function>php_sapi_name</function>.
  </para>
  <note>
   <para>
    O servidor web Apache muda o diretório para raiz durante a inicialização, causando com
    que o PHP tente ler o arquivo &php.ini; da raiz do arquivo de sistema, se ele existir.
   </para>
  </note>
  <para>
   O uso de variáveis de ambiente podem ser usadas no &php.ini; como mostrado abaixo.
  </para>
  <para>
   <example>
    <title>&php.ini; Variáveis de ambiente</title>
     <programlisting role="ini">
<![CDATA[
; PHP_MEMORY_LIMIT é lido das variáveis de ambiente
memory_limit = ${PHP_MEMORY_LIMIT}
]]>
     </programlisting>
    </example>
  </para>
  <para>
   As diretivas do arquivo &php.ini; tratadas por extensões são documentadas
   nas respectivas páginas das próprias extensões. A <link linkend="ini">lista de
   diretivas principais</link> está disponível no apêndice. Nem todas
   as diretivas do PHP estão documentadas no manual. Para uma lista completa
   das diretivas disponíveis na sua versão do PHP, por favor leia seu arquivo
   &php.ini;. Alternativamente, você pode encontrar
   <link xlink:href="&url.php.git.phpini;">a última versão do &php.ini;</link> no
   Git, que também pode ser útil.
  </para>
  <para>
   <example>
    <title>Exemplo de arquivo &php.ini;</title>
    <programlisting role="ini">
<![CDATA[
; qualquer texto após um ponto e virgula nú (;) é ignorado
[php] ; marcadores de sessão (textos dentro de colchetes) também são ignorados
; Valores booleanos podem ser:
;    true, on, yes
; ou false, off, no, none
register_globals = off
track_errors = yes

; vocẽ pode organizar strings dentro de aspas
include_path = ".:/usr/local/lib/php"

; contrabarra é tradado como um caracter normal
include_path = ".;c:\php\lib"
]]>
    </programlisting>
    <!-- TODO: add more details about values and expressions -->
   </example>
  </para>
  <para>
   É possível acessar as variáveis .ini
   dentro dos arquivos .ini. Exemplo: <literal>open_basedir = ${open_basedir}
   ":/new/dir"</literal>.
  </para>
  <sect2 xml:id="configuration.file.scan">
   <title>Configuração em diretório</title>

   <para>
    É possível configurar o PHP para procurar por arquivos .ini em um diretório
    após a leitura do &php.ini;. Isto é possível na compilação pela configuração da opção
    <option role="configure">--with-config-file-scan-dir</option>. No
    O diretório de configuração pode ser sobrescrito em tempo de execução
    através da configuração da variável de ambiente <varname>PHP_INI_SCAN_DIR</varname>.
   </para>

   <para>
    É possível procurar em vários diretórios os separando com o
    delimitador específico da plataforma (<literal>;</literal> no Windows, NetWare
    e RISC OS; <literal>:</literal> em todas as outras plataformas; o PHP
    utilizará a constante <constant>PATH_SEPARATOR</constant>).
    Se um diretório em branco estiver informado em <varname>PHP_INI_SCAN_DIR</varname>, o PHP
    também procurará pelo diretório informado na diretiva de compilação
    <option role="configure">--with-config-file-scan-dir</option>.
   </para>

   <para>
    Dentro de cada diretório o PHP irá pesquisar todos os arquivos terminados em
    <literal>.ini</literal> em ordem alfabética. A lista de arquivos
    é carregada, e nessa ordem são interpretados com uma chamada a
    <function>php_ini_scanned_files</function>, o por rodar o PHP com a opção
    <option>--ini</option>.
   </para>

   <informalexample>
    <screen>
<![CDATA[
Assumindo que o PHP foi configurado com --with-config-file-scan-dir=/etc/php.d,
e o separador de caminho é :...

$ php
  PHP irá carregar todos os arquivos de configuração em in /etc/php.d/*.ini.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
  PHP irá carregar todos os arquivos de configuração em /usr/local/etc/php.d/*.ini.


$ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
  PHP irá carregar todos os arquivos de configuração em /etc/php.d/*.ini, e então em
  /usr/local/etc/php.d/*.ini.

$ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
  PHP irá carregar todos os arquivos de configuração em /usr/local/etc/php.d/*.ini, e então em
  /etc/php.d/*.ini.
]]>
    </screen>
   </informalexample>
  </sect2>
 </sect1>

 <sect1 xml:id="configuration.file.per-user">
  <title>Arquivos .user.ini</title>

  <simpara>
   O PHP tem suporte para arquivos de configuração INI por
   cada diretório. Esses arquivos são processados <emphasis>apenas</emphasis> pelo
   CGI/FastCGI SAPI. Essa funcionalidade torna obsoleta a extensão PECL htscanner.
   Se você estiver rodando o PHP como um módulo do Apache, use arquivos &htaccess; para obter o mesmo
   efeito.
  </simpara>

  <simpara>
   Além do arquivo &php.ini; principal, o PHP procura por arquivos INI em cada
   diretório, iniciando no diretório do arquivo PHP requisitado e
   continua o caminho até a raiz do documento atual (conforme definido na variável
   <varname>$_SERVER['DOCUMENT_ROOT']</varname>). Caso o arquivo PHP esteja fora
   da raiz do documento, apenas o seu diretório é procurado.
  </simpara>
  <simpara>
   Somente configurações INI com
   os modos <constant>INI_PERDIR</constant> e
   <constant>INI_USER</constant> serão reconhecidos nos arquivos INI estilo
   .user.ini.
  </simpara>

  <simpara>
   Duas novas diretivas INI,
   <link linkend="ini.user-ini.filename">user_ini.filename</link> e
   <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link>
   controlam o uso de arquivos INI de usuário.
  </simpara>

  <simpara>
   A diretiva <link linkend="ini.user-ini.filename">user_ini.filename</link> define o nome do arquivo que o PHP
   procura em cada diretório; se for definido como uma string vazia, o PHP não
   fará a varredura em tudo. O padrão é <literal>.user.ini</literal>.
  </simpara>

  <simpara>
   A diretiva <link linkend="ini.user-ini.cache-ttl">user_ini.cache_ttl</link> controla a frequência de como os arquivos INI
   de usuário são relidos. O padrão é de 300 segundos (5 minutos).
  </simpara>
 </sect1>

 <sect1 xml:id="configuration.changes.modes">
  <title>Onde uma configuração deve ser definida</title>

  <para>
   Estes modos determinam quando e onde uma diretiva do PHP pode ou não pode
   ser definida, e cada diretiva no manual faz referência a um destes modos.
   Por exemplo, algumas definições podem ser feitas em um script PHP
   usando <function>ini_set</function>, enquanto outras só podem ser feitas no
   &php.ini; ou &httpd.conf;.
  </para>

  <para>
   Por exemplo, a configuração
   <link linkend="ini.output-buffering">output_buffering</link>
   é <constant>INI_PERDIR</constant> portanto não pode ser definida usando
   <function>ini_set</function>. Entretanto a diretiva
   <link linkend="ini.display-errors">display_errors</link> é
   <constant>INI_ALL</constant> portanto pode ser definida em qualquer lugar
   com <function>ini_set</function>.
  </para>

  <para>
   <variablelist>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('constant.ini-mode')/*)"><xi:fallback/></xi:include>
   </variablelist>
  </para>
 </sect1>

 <sect1 xml:id="configuration.changes">
  <title>Como mudar as configurações</title>

  <sect2 xml:id="configuration.changes.apache">
   <title>Executando PHP como módulo do Apache</title>
   <simpara>
    Quando usar o PHP como módulo do Apache, você pode mudar as
    configurações usando diretivas nos arquivos de configuração
    do Apache (ex.: &httpd.conf; e &htaccess;). Você precisará de
    privilégios "AllowOverride Options" ou "AllowOverride All" para fazer isso.
   </simpara>

   <para>
    Há várias diretivas do Apache que permitem que você
    mude a configuração do PHP de dentro dos arquivos de configuração
    do Apache. Para uma lista de quais diretivas são
    <constant>INI_ALL</constant>, <constant>INI_PERDIR</constant>,
    or <constant>INI_SYSTEM</constant>, olhe no apêndice
    <link linkend="ini.list">Lista de diretivas do arquivo php.ini</link>.
   </para>

   <para>
    <variablelist>
     <varlistentry>
      <term>
       <systemitem role="directive">php_value</systemitem>
       <parameter>name</parameter>
       <parameter>value</parameter>
      </term>
      <listitem>
       <para>
        Define o valor da diretiva especificada.
        Pode ser usado apenas com diretivas do tipo <constant>INI_ALL</constant> e <constant>INI_PERDIR</constant>.
        Para limpar um valor definido anteriormente, use o valor <literal>none</literal>.
       </para>
       <note>
        <simpara>
         Não use <systemitem role="directive">php_value</systemitem> para definir valores booleanos.
         A diretiva <systemitem role="directive">php_flag</systemitem> deve ser usada (veja abaixo).
        </simpara>
       </note>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_flag</systemitem>
       <parameter>name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Usado para definir uma diretiva de configuração booleana.
        Pode ser usada apenas com diretivas dos tipos <constant>INI_ALL</constant> e
        <constant>INI_PERDIR</constant>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_value</systemitem>
       <parameter>name</parameter>
       <parameter>value</parameter>
      </term>
      <listitem>
       <para>
        Define o valor da diretiva especificada.
        Essa diretiva <emphasis>não pode ser usada</emphasis> em arquivos &htaccess;.
        Qualquer tipo de diretiva definido com <systemitem role="directive">php_admin_value</systemitem>
        não pode ser sobrescrito pelo &htaccess; ou pela função <function>ini_set</function>.
        Para limpar um valor definido anteriormente, use o valor <literal>none</literal>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <systemitem role="directive">php_admin_flag</systemitem>
       <parameter>name</parameter>
       <parameter>on|off</parameter>
      </term>
      <listitem>
       <para>
        Usado para definir uma diretiva de configuração booleana.
        Essa diretiva <emphasis>não pode ser usada</emphasis> em arquivos &htaccess;.
        Qualquer tipo de diretiva definido com <systemitem role="directive">php_admin_flag</systemitem>
        não pode ser sobrescrito pelo &htaccess; ou pela função <function>ini_set</function>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    <example>
     <title>Exemplo de configuração do Apache</title>
     <programlisting role="ini">
<![CDATA[
<IfModule mod_php5.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag engine on
</IfModule>
]]>
     </programlisting>
    </example>
   </para>
   <caution>
    <para>
     Constantes PHP não existem fora do PHP. Por exemplo, no
     arquivo &httpd.conf; você não pode usar constantes do PHP
     como <constant>E_ALL</constant> ou <constant>E_NOTICE</constant>
     para definir a diretiva <link linkend="ini.error-reporting">error_reporting</link>,
     já que elas não terão significado algum e serão avaliadas como
     <emphasis>0</emphasis>. Ao invés disso, use os valores de máscara de bits associados.
     Essas constantes podem ser usados no &php.ini;
    </para>
   </caution>
  </sect2>

  <sect2 xml:id="configuration.changes.windows">
   <title>Mudando configuração do PHP através do registro do Windows</title>
   <simpara>
    Quando executar o PHP no Windows, os valores de configuração podem ser
    modificados para cada diretório, usando o registro do Windows. Os
    valores de configuração são armazenados na chave de registro
    <literal>HKLM\SOFTWARE\PHP\Per Directory Values</literal>,
    nas sub-chaves correspondentes aos caminhos dos diretórios. Por exemplo,
    valores para o diretório <literal>c:\inetpub\wwwroot</literal> estariam
    armazenados na chave <literal>HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot</literal>.
    As configurações para o
    diretório estarão ativas para qualquer script rodando neste
    diretório ou qualquer subdiretório dele. Os valores na chave
    devem ter o nome da diretiva de configuração do PHP e um
    valor string. Constantes PHP nos valores não são interpretados.
    Apenas valores de configuração modificáveis no
    <constant>INI_USER</constant> podem ser definidos
    desta forma, e valores do <constant>INI_PERDIR</constant> não podem,
    pois esses valores são recarregados em cada request.
   </simpara>
  </sect2>

  <sect2 xml:id="configuration.changes.other">
   <title>Outras interfaces para PHP</title>
   <para>
    Independente de como você execute PHP, você pode mudar certos valores durante
    a execução de seus scripts através da função <function>ini_set</function>. Veja
    a documentação na página <function>ini_set</function> para mais informações.
   </para>
   <para>
    Se você estiver interessado na lista completa das configurações
    definidas no seu sistema com os valores atuais, você pode executar a função
    <function>phpinfo</function>, e revisar a página resultante.
    Você pode também acessar os valores de configurações
    de diretivas individuais em tempo de execução usando as funções
    <function>ini_get</function> ou <function>get_cfg_var</function>.
   </para>
  </sect2>
 </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
-->