parse_ini_string()

Che cos'è la funzione parse_ini_string()?

La funzione parse_ini_string() analizza una stringa scritta nel formato di configurazione INI e restituisce il suo contenuto come array associativo. È la versione in-memory di parse_ini_file(): invece di leggere le impostazioni da un file su disco, le legge da una stringa già presente in una variabile.

Questa funzione è utile quando i dati di configurazione provengono da una fonte diversa da un file locale — una colonna di database, una risposta HTTP, una variabile d'ambiente o un here-doc incorporato nel codice. Il formato INI è lo stesso usato da PHP per php.ini: coppie key = value, intestazioni [section] opzionali e commenti con ;.

Questa pagina tratta la firma della funzione, l'output suddiviso per sezioni rispetto a quello piatto, le tre modalità di scansione e i problemi più comuni (parole riservate, caratteri speciali e fallimenti di analisi).

Sintassi

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

La funzione restituisce un array associativo in caso di successo, oppure false in caso di errore.

Esempio di base

Inizia con una stringa piatta di coppie key = value e leggi i valori tramite chiave:

<?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

La prima riga che inizia con ; è un commento e viene ignorata. Ogni altra riga diventa una voce nell'array restituito, con chiave pari al nome a sinistra del =.

Raggruppamento dei valori per sezione

I file INI spesso organizzano le impostazioni correlate sotto intestazioni [section]. Passa true come secondo argomento per mantenere quella struttura nel risultato — ogni sezione diventa un array annidato:

<?php

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

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

Output:

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

)

Con $process_sections lasciato al valore predefinito false, l'intestazione [settings] viene eliminata e si ottiene un singolo array piatto con name ed email.

Modalità di scansione

Il terzo argomento controlla come vengono interpretati i valori:

• INI_SCANNER_NORMAL (predefinito) — i valori vengono restituiti come stringhe e costanti/parole speciali vengono valutate.
• INI_SCANNER_RAW — i valori vengono restituiti esattamente come scritti, senza alcuna interpretazione. Usalo per preservare le stringhe letterali.
• INI_SCANNER_TYPED — booleani, numeri e null vengono convertiti nei loro tipi PHP nativi invece di stringhe.

INI_SCANNER_TYPED è il più utile per la configurazione reale, perché evita di dover convertire manualmente le stringhe:

<?php

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

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

Output:

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

In modalità normale, quegli stessi valori sarebbero tutti stringhe ("1" per true, "3", "1.5").

Parole riservate e virgolette

Alcuni caratteri e parole hanno un significato speciale nel formato INI, quindi fai attenzione a questi aspetti:

• Le parole true, false, on, off, yes, no, none e null vengono interpretate come booleani/null in modalità typed e come "1"/"" in modalità normale. Se hai bisogno del testo letterale, racchiudi il valore tra virgolette o usa INI_SCANNER_RAW.
• I caratteri ?{}|&~!()^" sono riservati e non devono essere usati al di fuori di un valore tra virgolette.
• Un valore che contiene spazi o caratteri speciali deve essere tra virgolette: path = "C:\Program Files".

Gestione degli errori di analisi

parse_ini_string() restituisce false se l'input non può essere analizzato, quindi verifica il risultato prima di utilizzarlo:

<?php

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

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

Un valore vuoto non è un errore — name = restituisce semplicemente una stringa vuota per quella chiave. Gli errori reali derivano da una sintassi malformata, ad esempio un valore non tra virgolette che usa caratteri riservati.

Quando utilizzarla

Usa parse_ini_string() quando:

• Il testo di configurazione è già in memoria (caricato da un DB, un'API o uno stream) anziché su disco.
• Vuoi un formato di configurazione leggero e senza dipendenze che anche i non sviluppatori possano modificare.
• Hai bisogno di validare o trasformare contenuto INI prima di salvarlo in un file.

Se la configurazione si trova in un file reale, usa invece parse_ini_file() — legge e analizza in un solo passaggio. Per strutture dati più ricche, considera JSON tramite json_decode().

Conclusione

parse_ini_string() trasforma una stringa in formato INI in un array PHP, con raggruppamento opzionale per sezioni e tre modalità di scansione per controllare come i valori vengono tipizzati. Usa $process_sections per preservare la struttura [section], preferisci INI_SCANNER_TYPED quando vuoi veri booleani e numeri, e verifica sempre il ritorno false quando l'input non è attendibile.

Pratica