(PHP 4, PHP 5, PHP 7, PHP 8)
parse_ini_file — Interpreta um arquivo de configuração
$filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array|false
parse_ini_file() carrega o arquivo INI
especificado em filename e retorna
as configurações contidas nele em um array associativo.
A estrutura do arquivo INI é a mesma do php.ini.
filenameO nome do arquivo INI sendo interpretado. Se um caminho relativo for usado, será avaliado relativamente ao diretório atual de trabalho, e depois no caminho include_path.
process_sections
Definindo o parâmetro process_sections
para true, obtém-se um array multidimensional com os nomes
das seções e configurações incluídos. O padrão para
process_sections é false
scanner_mode
Pode ser INI_SCANNER_NORMAL (padrão) ou
INI_SCANNER_RAW. Se INI_SCANNER_RAW
for fornecido, os valores das opções não serão interpretados.
A partir do PHP 5.6.1, também pode ser especificado como INI_SCANNER_TYPED.
Nesse modo, os tipos boolean, null e integer são preservados quando possível.
Os valores string "true", "on" e "yes"
são convertidos em true. "false", "off", "no"
e "none" são considerados false. "null" é convertido para null
no modo tipado. Além disso, todas as strings numéricas são convertidas para o tipo inteiro, se possível.
As configurações são retornadas como um array associativo em caso de sucesso,
e false em caso de falha.
Exemplo #1 Conteúdo de sample.ini
; Este é um arquivo de configuração de exemplo ; Comentários iniciam com ';', como no php.ini [primeira_secao] um = 1 cinco = 5 animal = PASSARO [segunda_secao] path = "/usr/local/bin" URL = "http://www.example.com/~username" [terceira_secao] versaophp[] = "5.0" versaophp[] = "5.1" versaophp[] = "5.2" versaophp[] = "5.3" urls[svn] = "http://svn.php.net" urls[git] = "http://git.php.net"
Exemplo #2 Exemplo de parse_ini_file()
Constantes (mas não "constantes mágicas" como __FILE__)
também podem ser interpretadas
no arquivo INI. Se for definida uma constante como um valor INI antes
de executar parse_ini_file(), ela será intergrada aos
resultados. Somente valores INI são avaliados e o valor deve ser apenas a constante. Por exemplo:
<?php
define('PASSARO', 'Pássaro Dodo');
// Interpreta sem as seções
$ini_array = parse_ini_file("sample.ini");
print_r($ini_array);
// Interpreta com as seções
$ini_array = parse_ini_file("sample.ini", true);
print_r($ini_array);
?>O exemplo acima produzirá algo semelhante a:
Array
(
[um] => 1
[cinco] => 5
[animal] => Pássaro Dodo
[path] => /usr/local/bin
[URL] => http://www.example.com/~username
[versaophp] => Array
(
[0] => 5.0
[1] => 5.1
[2] => 5.2
[3] => 5.3
)
[urls] => Array
(
[svn] => http://svn.php.net
[git] => http://git.php.net
)
)
Array
(
[primeira_secao] => Array
(
[um] => 1
[cinco] => 5
[animal] = Pássaro Dodo
)
[segunda_secao] => Array
(
[path] => /usr/local/bin
[URL] => http://www.example.com/~username
)
[terceira_secao] => Array
(
[versaophp] => Array
(
[0] => 5.0
[1] => 5.1
[2] => 5.2
[3] => 5.3
)
[urls] => Array
(
[svn] => http://svn.php.net
[git] => http://git.php.net
)
)
)
Exemplo #3 parse_ini_file() interpretando um arquivo php.ini
<?php
// Uma função simples usada para comparar os resultados abaixo
function sim_nao($expression)
{
return($expression ? 'Sim' : 'Não');
}
// Obtém o caminho para o php.ini usando a função php_ini_loaded_file()
$ini_path = php_ini_loaded_file();
// Interpreta o php.ini
$ini = parse_ini_file($ini_path);
// Mostra e compara os valores, note que usar get_cfg_var()
// levará aos mesmos resultados para interpretado e carregado aqui
echo '(interpretado) magic_quotes_gpc = ' . sim_nao($ini['magic_quotes_gpc']) . PHP_EOL;
echo '(carregado) magic_quotes_gpc = ' . sim_nao(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
?>O exemplo acima produzirá algo semelhante a:
(parsed) magic_quotes_gpc = Sim (loaded) magic_quotes_gpc = Sim
Exemplo #4 Interpolação de Valor
Além de avaliar constantes, alguns caracteres possuem significado especial em um valor INI.
Adicionamente, variáveis de ambiente e opções de configuração previamente definidas (consulte get_cfg_var()) podem ser lidas usando
a sintaxe ${}.
; | é usado par OR bit a bit
tres = 2|3
; & é usado para AND bit a bit
quatro = 6&5
; ^ é usado para XOR bit a bit
cinco = 3^6
; ~ é usado para inversão bit a bit
dois_negativo = ~1
; () é usado para agrupamento
sete = (8|7)&(6|5)
; Interpola a variável de ambiente PATH
path = ${PATH}
; Interpola a opção de configuração 'memory_limit'
limite_de_memoria_configurado = ${memory_limit}
Exemplo #5 Fazendo Escape de Caracteres
Alguns caracteres têm significado especial em strings com aspas duplas e devem ser escapados pela barra invertida prefixada.
Primeiramente, eles são as aspas duplas " como marcação dos limites, e a barra invertida \ em si
(se seguida por um dos caracteres especiais):
fala = "Ela disse \"Exatamente meu ponto\"." ; Resulta em uma string contendo aspas duplas. dica = "Use \\\" para escapar aspas duplas" ; Resulta em: Use \" para escapar aspas duplas
Há uma excecão feita para caminhos do tipo Windows: é possível não escapar barra invertida no final se a string entre aspas for diretamente seguida por uma quebra de linha:
save_path = "C:\Temp\"
Se for necessário escapar aspas duplas seguidas pode quebra de linha em um valor com várias linhas, é possível usar concatenação de valores da seguinte forma (há uma string com aspas duplas diretamente seguida por outra):
long_text = "Lorem \"ipsum\""" dolor" ; Resulta em: Lorem "ipsum"\n dolor
Outro caractere com significado especial é $ (sinal de cifrão).
Deve ser escapado se for seguido de chave:
code = "\${test}"
Escapar caracteres não é suportado no modo INI_SCANNER_RAW
(neste modo todos os caracateres são processados como eles são).
Note que o interpretador INI não suporta sequências escape padrões (\n, \t etc.).
Se necessário, faça pós processamento do resultado de parse_ini_file() com a função stripcslashes().
Nota:
Essa função não tem relação nenhuma com o arquivo php.ini. Ele já está processado no momento em o script é executado. Esta função pode ser usada para ler os arquivos de configuração da própria aplicação do usuário.
Nota:
Se um valor no arquivo INI tiver algum caractere não alfanumérico, ele precisará ser envolvido em aspas duplas (").
Nota: Existem algumas palavras reservadas que não podem ser usadas como chaves em arquivos INI. Elas incluem:
null,yes,no,true,false,on,offenone. Valoresnull,off,noefalseresultam em"", e os valoreson,yesetrueresultam em"1", a menos que o modoINI_SCANNER_TYPEDseja usado. Os caracteres?{}|&~!()^"não devem ser usados em nenhum lugar da chave e têm um significado especial no valor.
Nota:
Entradas sem um sinal de igualdade são ignoradas. Por exemplo, "foo" é ignorado enquanto que "bar =" é interpretado e adicionado com um valor vazio. Por exemplo, o MySQL tem uma configuração "no-auto-rehash" no arquivo my.cnf que não leva um valor, portanto ela é ignorada.
Nota:
Arquivos INI são feralmente tratados como texto puro por servidores web e depois enviados aos navegadores se requisitados. Isto quer dizer que para segurança deve-se manter os arquivos INI fora da raiz de documentos da web ou reconfigurar seu servidor web para não disponibilizá-los. Falha em fazer isso pode introduzir um risco de segurança.