(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.
Esta função não deve ser usada com entradas não confiáveis a menos que
scanner_mode seja igual a INI_SCANNER_RAW,
já que a saída analisada pode conter valores de constantes
sensíveis como as que contêm senhas de banco de dados.
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.