Introduzione
Quando si lavora con PHP, il formato JSON è uno degli strumenti più utili per scambiare dati tra applicazioni, salvare impostazioni e integrare servizi esterni. Un caso pratico molto comune, ma spesso sottovalutato, è la gestione di file JSON locali: leggere un file, verificarne la struttura, modificare i dati e riscriverlo senza introdurre errori o corrompere il contenuto.
Questo argomento è diverso dai classici esempi su API o configurazioni dinamiche: qui ci concentriamo su una situazione concreta da progetto reale, cioè la gestione di un file JSON come archivio semplice e leggibile. È una soluzione utile per piccoli sistemi, tool interni, prototipi, pannelli admin o applicazioni che non richiedono ancora un database completo.
In questo tutorial vedremo come:
- leggere un file JSON in modo corretto;
- validare la struttura dei dati prima di usarli;
- aggiornare il contenuto con attenzione;
- salvare il file con formattazione leggibile;
- gestire gli errori più comuni in modo professionale.
Codice completo
<?php
declare(strict_types=1);
/**
* Esempio pratico: gestione di un file JSON che contiene una lista di utenti.
* Il file viene letto, validato, aggiornato e riscritto in modo sicuro.
*/
$pathFile = __DIR__ . ´/users.json´;
/**
* Legge un file JSON e lo converte in array associativo.
*
* @param string $filePath
* @return array
* @throws RuntimeException
*/
function leggiJsonDaFile(string $filePath): array
{
if (!file_exists($filePath)) {
throw new RuntimeException("Il file JSON non esiste: {$filePath}");
}
$contenuto = file_get_contents($filePath);
if ($contenuto === false) {
throw new RuntimeException("Impossibile leggere il file JSON.");
}
try {
$dati = json_decode($contenuto, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
throw new RuntimeException("JSON non valido: " . $e-Spiegazione
Il codice mostra un flusso completo e realistico: leggere un file JSON, controllare i dati, aggiungere un elemento e salvare tutto nuovamente. Vediamo i passaggi principali.
1. Lettura sicura del file
La funzione leggiJsonDaFile() controlla prima che il file esista. Questo evita errori banali ma frequenti, soprattutto in ambienti di sviluppo o in sistemi dove il file viene creato dinamicamente.
Subito dopo, il contenuto viene letto con file_get_contents(). Se la lettura fallisce, viene generata un’eccezione. Questo approccio è migliore rispetto al semplice silenziamento dell’errore, perché rende il problema visibile e gestibile.
2. Decodifica con gestione delle eccezioni
La funzione json_decode() converte la stringa JSON in un array PHP. L’opzione JSON_THROW_ON_ERROR è molto importante: invece di restituire null in caso di errore, lancia una JsonException. In questo modo si distinguono facilmente i casi di JSON vuoto, JSON non valido e altri problemi di parsing.
3. Validazione della struttura
Non basta che il JSON sia sintatticamente corretto: deve anche avere la struttura attesa. La funzione validaUtente() controlla che ogni record abbia i campi richiesti e che i valori abbiano il tipo giusto.
Per esempio:
- id deve essere un intero positivo;
- nome non deve essere vuoto;
- email deve essere valida;
- attivo deve essere booleano.
Questo passaggio è fondamentale quando il JSON proviene da fonti esterne o può essere modificato manualmente.
4. Aggiornamento del contenuto
Dopo la validazione, il tutorial aggiunge un nuovo utente all’array. Nelle applicazioni reali, questa logica può rappresentare un nuovo prodotto, una preferenza utente, una prenotazione o qualsiasi altra entità semplice.
È importante validare anche i nuovi dati prima di inserirli nel file. Non bisogna mai assumere che un dato sia corretto solo perché arriva dal codice interno.
5. Scrittura del file con formattazione leggibile
La funzione salvaJsonSuFile() usa json_encode() con le opzioni:
- JSON_PRETTY_PRINT per rendere il file leggibile;
- JSON_UNESCAPED_UNICODE per mantenere corretti i caratteri accentati;
- JSON_THROW_ON_ERROR per intercettare problemi di serializzazione.
Inoltre, file_put_contents() viene usato con LOCK_EX per ridurre il rischio di conflitti quando più processi scrivono sullo stesso file.
Best practice
- Usa sempre JSON_THROW_ON_ERROR: è il modo più chiaro per intercettare problemi sia in lettura sia in scrittura.
- Valida la struttura dopo il decode: un JSON valido non significa dati affidabili.
- Separa lettura, validazione e scrittura: il codice diventa più testabile e più facile da mantenere.
- Usa file lock in scrittura: utile quando il file può essere modificato da più richieste contemporaneamente.
- Evita di sovrascrivere senza controlli: se il JSON è corrotto, meglio fermarsi che salvare dati sbagliati.
- Preferisci array associativi quando lavori con dati semplici: sono più comodi da leggere e manipolare in PHP.
- Conserva una copia di backup per file importanti, soprattutto se il JSON viene usato come archivio persistente.
Riepilogo
La gestione di file JSON in PHP è una competenza pratica e molto utile. Con poche funzioni native puoi leggere, validare, aggiornare e riscrivere dati in modo efficace. Tuttavia, la semplicità del formato non deve far dimenticare alcuni aspetti essenziali: controllo degli errori, validazione della struttura e scrittura sicura.
In questo tutorial hai visto un approccio robusto per trattare un file JSON come archivio dati leggero. È una soluzione perfetta per piccoli progetti, strumenti interni e prototipi, purché venga usata con attenzione. Quando il progetto cresce, potrai poi migrare verso database o servizi più strutturati, mantenendo però la stessa disciplina nella gestione dei dati.
Approfondisci con risorse ufficiali
- PHP Manual - json_decode(): documentazione ufficiale sulla decodifica JSON.
- PHP Manual - json_encode(): opzioni disponibili per serializzare dati in JSON.
- PHP Manual - JSON constants: elenco completo delle costanti come JSON_THROW_ON_ERROR e JSON_PRETTY_PRINT.
- PHP Manual - file_get_contents(): lettura di file locali e remoti.
- PHP Manual - file_put_contents(): scrittura su file con opzioni di lock.
- PHP Manual - JsonException: gestione delle eccezioni legate al parsing JSON.