parse_ini_string()

O que é a função parse_ini_string()?

A função parse_ini_string() analisa uma string escrita no formato de configuração INI e retorna seu conteúdo como um array associativo. Ela é a equivalente em memória de parse_ini_file(): em vez de ler configurações de um arquivo em disco, lê-as de uma string que você já possui em uma variável.

Isso é útil quando os dados de configuração chegam de algum lugar diferente de um arquivo local — uma coluna de banco de dados, uma resposta HTTP, uma variável de ambiente ou um here-doc incorporado no seu código. O próprio formato INI é o mesmo que o PHP usa para php.ini: pares chave = valor, cabeçalhos [seção] opcionais e comentários com ;.

Esta página aborda a assinatura da função, a saída seccionada versus plana, os três modos de scanner e as armadilhas mais comuns (palavras reservadas, caracteres especiais e falhas de análise).

Sintaxe

parse_ini_string(
    string $ini_string,
    bool $process_sections = false,
    int $scanner_mode = INI_SCANNER_NORMAL
): array|false

A função retorna um array associativo em caso de sucesso, ou false em caso de falha.

Exemplo Básico

Comece com uma string plana de pares chave = valor e leia os valores de volta pela chave:

<?php

$config = parse_ini_string(
    "; Example configuration string\n" .
    "name = John Doe\n" .
    "email = [email protected]\n" .
    "phone = 555-555-5555"
);

echo $config['name'];  // John Doe
echo $config['email']; // [email protected]
echo $config['phone']; // 555-555-5555

A linha inicial começando com ; é um comentário e é ignorada. Cada outra linha torna-se uma entrada no array retornado, indexada pelo nome à esquerda do =.

Agrupando Valores por Seção

Arquivos INI frequentemente organizam configurações relacionadas sob cabeçalhos [seção]. Passe true como segundo argumento para manter essa estrutura no resultado — cada seção torna-se um array aninhado:

<?php

$ini = "[settings]\nname = John Doe\nemail = [email protected]";

$config = parse_ini_string($ini, true);
print_r($config);

Saída:

Array
(
    [settings] => Array
        (
            [name] => John Doe
            [email] => [email protected]
        )

)

Com $process_sections no seu padrão false, o cabeçalho [settings] é descartado e você obtém um único array plano com name e email.

Modos de Scanner

O terceiro argumento controla como os valores são interpretados:

• INI_SCANNER_NORMAL (padrão) — os valores são retornados como strings e constantes/palavras especiais são avaliadas.
• INI_SCANNER_RAW — os valores são retornados exatamente como escritos, sem interpretação. Use isso para preservar strings literais.
• INI_SCANNER_TYPED — booleanos, números e null são convertidos para seus tipos nativos do PHP em vez de strings.

INI_SCANNER_TYPED é o mais útil para configuração real, pois evita que você precise converter strings manualmente:

<?php

$ini = "debug = true\nretries = 3\ntimeout = 1.5";

$config = parse_ini_string($ini, false, INI_SCANNER_TYPED);
var_dump($config);

Saída:

array(3) {
  ["debug"]=>
  bool(true)
  ["retries"]=>
  int(3)
  ["timeout"]=>
  float(1.5)
}

No modo normal, esses mesmos valores seriam todos strings ("1" para true, "3", "1.5").

Palavras Reservadas e Aspas

Alguns caracteres e palavras têm significado especial no formato INI, portanto, fique atento a estes casos:

• As palavras true, false, on, off, yes, no, none e null são interpretadas como booleanos/null no modo tipado e como "1"/"" no modo normal. Se você precisar do texto literal, envolva o valor em aspas ou use INI_SCANNER_RAW.
• Os caracteres ?{}|&~!()^" são reservados e não devem ser usados fora de um valor entre aspas.
• Um valor que contém espaços ou caracteres especiais deve estar entre aspas: path = "C:\Program Files".

Tratando Falhas de Análise

parse_ini_string() retorna false se a entrada não puder ser analisada, portanto, verifique o resultado antes de usá-lo:

<?php

$config = parse_ini_string($_POST['config'] ?? '', true);

if ($config === false) {
    echo 'Invalid configuration string.';
} else {
    // safe to use $config here
    print_r($config);
}

Um valor em branco não é uma falha — name = simplesmente produz uma string vazia para aquela chave. Falhas reais ocorrem por sintaxe malformada, como um valor sem aspas que usa caracteres reservados.

Quando Usar

Recorra a parse_ini_string() quando:

• O texto de configuração já está em memória (carregado de um banco de dados, uma API ou um stream) em vez de em disco.
• Você quer um formato de configuração leve e sem dependências que não desenvolvedores possam editar.
• Você precisa validar ou transformar conteúdo INI antes de persistí-lo em um arquivo.

Se a configuração estiver em um arquivo real, use parse_ini_file() em vez disso — ela lê e analisa em uma única etapa. Para estruturas de dados mais ricas, considere JSON via json_decode().

Conclusão

parse_ini_string() converte uma string no formato INI em um array PHP, com agrupamento opcional por seção e três modos de scanner para controlar como os valores são tipados. Use $process_sections para preservar a estrutura [seção], prefira INI_SCANNER_TYPED quando quiser booleanos e números reais, e sempre verifique um retorno false quando a entrada não for confiável.

Prática