parse_ini_file()

Cos'è la Funzione parse_ini_file()?

La funzione parse_ini_file() è una funzione PHP built-in che legge un file di configurazione scritto nel formato INI e restituisce le sue impostazioni come array associativo. INI è il semplice formato chiave = valore usato dallo stesso php.ini, ed è una scelta popolare per memorizzare le impostazioni dell'applicazione (credenziali del database, flag di funzionalità, chiavi API) al di fuori del codice.

Questa pagina spiega la sintassi, come i valori INI vengono tipizzati, come funzionano le sezioni, le modalità dello scanner e le insidie (parole riservate, gestione degli errori) che è necessario conoscere prima di utilizzarla in produzione.

Ecco la sintassi di base della funzione parse_ini_file():

La sintassi PHP di parse_ini_file()

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

I parametri sono:

• $filename — percorso del file INI da analizzare.
• $process_sections (opzionale) — quando è true, il risultato è un array multidimensionale indicizzato dai nomi [section] presenti nel file. Il valore predefinito è false, che appiattisce ogni chiave in un unico array.
• $scanner_mode (opzionale) — controlla come i valori vengono interpretati. Uno tra:
  • INI_SCANNER_NORMAL (predefinito) — i valori vengono restituiti come stringhe; true/on/yes diventano "1" e false/off/no diventano "".
  • INI_SCANNER_RAW — i valori vengono presi verbatim; nessuna interpolazione di ${...} o costanti.
  • INI_SCANNER_TYPED — booleani, interi e null mantengono i loro tipi PHP nativi (vedi sotto).

La funzione restituisce un array in caso di successo, oppure false in caso di errore (ad esempio, il file non esiste), quindi è necessario verificare sempre il risultato prima di utilizzarlo.

Come Usare la Funzione parse_ini_file()

Inizia con un file di configurazione in formato INI. I commenti iniziano con il punto e virgola (;):

config.ini

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

Poi analizzalo e leggi i valori tramite chiave:

Lettura di un file INI semplice

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

Il controllo === false è importante: parse_ini_file() restituisce false in caso di errore (file mancante, percorso non leggibile), e trattarlo come un array provocherebbe dei warning.

Raggruppare le Impostazioni con le Sezioni

I file di configurazione reali sono di solito suddivisi in [sezioni]. Passa true come secondo argomento per mantenere quella struttura come array annidato:

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

Con $process_sections impostato a true, ogni sezione diventa un sotto-array. Questo evita che chiavi con lo stesso nome (ad esempio un comune host in due sezioni) si sovrascrivano a vicenda.

Come Vengono Tipizzati i Valori (Modalità Scanner)

Per impostazione predefinita ogni valore viene restituito come stringa — i booleani vengono convertiti in "1" o in una stringa vuota "", e i numeri rimangono testuali:

<?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 si desidera i tipi PHP nativi, usa 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)

Questa è la modalità più sicura quando il codice si basa su booleani reali (if ($c['enabled'])) anziché su stringhe truthy — nota che la stringa "0" e la stringa vuota vengono entrambe valutate come falsy, ma "false" analizzato in modalità NORMAL sarebbe truthy, il che è una frequente fonte di bug.

Parole Riservate e Insidie

Alcuni caratteri e parole hanno un significato speciale nei file INI e possono causare sorprese:

• Valori riservati: null, yes, no, true, false, on, off, none vengono interpretati. Per mantenerli letterali, racchiudi il valore tra virgolette: mode = "off".
• Caratteri riservati: ?{}|&~!()^" non devono essere usati in un valore non quotato.
• Chiavi denominate null, yes, no, true, false, on, off, none non sono consentite come chiavi.
• Il ; avvia un commento, quindi un valore contenente un punto e virgola deve essere quotato.

Per file non attendibili o caricati da utenti, preferisci il più sicuro parse_ini_string() dopo aver letto il file con file_get_contents(), oppure valida prima il percorso — non analizzare mai percorsi arbitrari forniti dall'utente.

Quando Usare parse_ini_file()

parse_ini_file() è una buona soluzione quando si desidera un file di configurazione modificabile da esseri umani che anche i non sviluppatori possono ritoccare, e quando i dati sono semplici impostazioni chiave/valore. Per dati profondamente annidati o ricchi di array, JSON (json_decode()) o array PHP restituiti da un file incluso con require sono di solito una scelta migliore. Consulta Gestione File PHP per l'insieme più ampio di funzioni sui file, e Costanti PHP poiché i valori INI possono fare riferimento a costanti definite in modalità INI_SCANNER_NORMAL.

Conclusione

La funzione parse_ini_file() trasforma un file di configurazione INI in un array PHP con una sola chiamata. Ricorda le tre cose che causano più problemi: verifica il ritorno di false, passa true per $process_sections quando il file usa [sections], e usa INI_SCANNER_TYPED quando hai bisogno di booleani e interi reali invece di stringhe.

Esercitazione