parse_ini_file()

O que é a Função parse_ini_file()?

A função parse_ini_file() é uma função nativa do PHP que lê um arquivo de configuração escrito no formato INI e retorna suas configurações como um array associativo. INI é o formato simples chave = valor usado pelo próprio php.ini, sendo uma escolha popular para armazenar configurações de aplicações (credenciais de banco de dados, flags de funcionalidades, chaves de API) fora do seu código.

Esta página explica a sintaxe, como os valores INI são tipados, como as seções funcionam, os modos de scanner e as armadilhas (palavras reservadas, tratamento de erros) que você precisa conhecer antes de usá-la em produção.

Veja a sintaxe básica da função parse_ini_file():

A sintaxe PHP de parse_ini_file()

parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array|false

Os parâmetros são:

• $filename — caminho para o arquivo INI a ser analisado.
• $process_sections (opcional) — quando true, o resultado é um array multidimensional indexado pelos nomes de [seção] presentes no arquivo. O padrão é false, que achata todas as chaves em um único array.
• $scanner_mode (opcional) — controla como os valores são interpretados. Um dos seguintes:
  • INI_SCANNER_NORMAL (padrão) — os valores são retornados como strings; true/on/yes tornam-se "1" e false/off/no tornam-se "".
  • INI_SCANNER_RAW — os valores são tomados literalmente; sem interpolação de ${...} ou constantes.
  • INI_SCANNER_TYPED — booleanos, inteiros e null mantêm seus tipos nativos PHP (veja abaixo).

A função retorna um array em caso de sucesso, ou false em caso de falha (por exemplo, se o arquivo não existir), portanto sempre verifique o resultado antes de usá-lo.

Como Usar a Função parse_ini_file()

Comece com um arquivo de configuração no formato INI. Os comentários começam com ponto e vírgula (;):

config.ini

; Example configuration file
name = John Doe
email = [email protected]
phone = 555-555-5555

Em seguida, analise o arquivo e leia os valores pela chave:

Lendo um arquivo INI simples

<?php

$config = parse_ini_file('config.ini');

if ($config === false) {
    echo "Failed to parse config.ini";
} else {
    echo $config['name'];  // John Doe
    echo $config['email']; // [email protected]
    echo $config['phone']; // 555-555-5555
}

A verificação === false é importante: parse_ini_file() retorna false em caso de falha (arquivo inexistente, caminho ilegível), e tratar isso como um array geraria avisos.

Agrupando Configurações com Seções

Arquivos de configuração reais geralmente são divididos em [seções]. Passe true como segundo argumento para manter essa estrutura como um array aninhado:

database.ini

[database]
host = localhost
port = 3306

[app]
name = "My App"
debug = true

<?php

$config = parse_ini_file('database.ini', true);

echo $config['database']['host']; // localhost
echo $config['database']['port']; // 3306
echo $config['app']['name'];      // My App

Com $process_sections definido como true, cada seção torna-se um sub-array. Isso evita que chaves com o mesmo nome (um host comum em duas seções, por exemplo) se sobrescrevam.

Como os Valores São Tipados (Modos de Scanner)

Por padrão, todo valor é retornado como uma string — booleanos são convertidos para "1" ou uma string vazia "", e números permanecem textuais:

<?php
// enabled = true, count = 42 in the INI file
$c = parse_ini_file('app.ini');
var_dump($c['enabled']); // string(1) "1"
var_dump($c['count']);   // string(2) "42"

Se você quiser tipos PHP nativos, use INI_SCANNER_TYPED:

<?php
$c = parse_ini_file('app.ini', false, INI_SCANNER_TYPED);
var_dump($c['enabled']); // bool(true)
var_dump($c['count']);   // int(42)

Este é o modo mais seguro quando seu código depende de booleanos reais (if ($c['enabled'])) em vez de strings truthy — note que a string "0" e a string vazia ambas são avaliadas como falsy, mas "false" analisado no modo NORMAL seria truthy, o que é uma fonte frequente de bugs.

Palavras Reservadas e Armadilhas

Alguns caracteres e palavras têm significado especial em arquivos INI e podem causar surpresas:

• Valores reservados: null, yes, no, true, false, on, off, none são interpretados. Para mantê-los literais, envolva o valor entre aspas: mode = "off".
• Caracteres reservados: ?{}|&~!()^" não devem ser usados em um valor sem aspas.
• Chaves nomeadas null, yes, no, true, false, on, off, none não são permitidas como chaves.
• O ; inicia um comentário, portanto um valor que contenha ponto e vírgula deve estar entre aspas.

Para arquivos não confiáveis ou enviados por usuários, prefira o mais seguro parse_ini_string() após ler o arquivo com file_get_contents(), ou valide o caminho primeiro — nunca analise caminhos arbitrários fornecidos por usuários.

Quando Usar parse_ini_file()

parse_ini_file() é uma boa opção quando você quer um arquivo de configuração editável por humanos que não desenvolvedores possam ajustar, e quando os dados são configurações simples de chave/valor. Para dados profundamente aninhados ou com muitos arrays, JSON (json_decode()) ou arrays PHP retornados de um arquivo incluído com require geralmente são uma escolha melhor. Veja Manipulação de Arquivos PHP para o conjunto mais amplo de funções de arquivo, e Constantes PHP já que valores INI podem referenciar constantes definidas no modo INI_SCANNER_NORMAL.

Conclusão

A função parse_ini_file() transforma um arquivo de configuração INI em um array PHP com uma única chamada. Lembre-se das três coisas que costumam causar problemas: verifique o retorno false, passe true para $process_sections quando seu arquivo usar [seções], e use INI_SCANNER_TYPED quando precisar de booleanos e inteiros reais em vez de strings.

Prática