PHP e JSON: leggere e filtrare dati da una risposta API

by theArchitect
Add as preferred source on Google
SHARE
PHP e JSON: leggere e filtrare dati da una risposta API
© Guida-HTML5.it

Introduzione

Quando si lavora con PHP e JSON, uno scenario molto comune è consumare i dati restituiti da una API esterna: ad esempio un servizio meteo, un catalogo prodotti, un sistema di pagamenti o una piattaforma di analytics. In questi casi non basta “decodificare” il JSON: bisogna anche selezionare solo i campi utili, gestire valori mancanti e trasformare i dati in una struttura più comoda per l’applicazione.

Questo tutorial si concentra proprio su un sotto-argomento pratico e spesso sottovalutato: come leggere un JSON proveniente da API e filtrarlo in modo pulito in PHP. È un passaggio molto utile perché le risposte JSON reali sono spesso più grandi del necessario, cambiano nel tempo e contengono campi opzionali.

Vedremo un esempio realistico: una risposta JSON con una lista di prodotti, da cui estrarre solo alcune informazioni essenziali per creare una scheda semplificata da mostrare in un pannello amministrativo o in una pagina frontend.

Codice completo

<?php
declare(strict_types=1);

/**
 * Esempio di JSON ricevuto da una API esterna.
 * In un caso reale arriverebbe da file_get_contents(), cURL o Guzzle.
 */
$jsonResponse = ´{
  "status": "ok",
  "generated_at": "2026-07-21T10:15:00Z",
  "data": [
    {
      "id": 101,
      "name": "Mouse wireless",
      "price": 24.90,
      "currency": "EUR",
      "stock": 18,
      "category": {
        "id": 5,
        "name": "Accessori"
      },
      "tags": ["tech", "office", "wireless"],
      "supplier": {
        "name": "Tech Supply",
        "country": "IT"
      }
    },
    {
      "id": 102,
      "name": "Tastiera meccanica",
      "price": 89.99,
      "currency": "EUR",
      "stock": 0,
      "category": {
        "id": 5,
        "name": "Accessori"
      },
      "tags": ["gaming", "keyboard"]
    },
    {
      "id": 103,
      "name": "Monitor 27 pollici",
      "price": 249.50,
      "currency": "EUR",
      "stock": 7,
      "category": {
        "id": 8,
        "name": "Monitor"
      },
      "tags": ["display", "office"],
      "supplier": {
        "name": "Visual Pro",
        "country": "DE"
      }
    }
  ]
}´;

/**
 * Decodifica JSON in array associativo.
 * JSON_THROW_ON_ERROR è una best practice perché rende gli errori espliciti.
 */
try {
    $payload = json_decode($jsonResponse, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    die("Errore nella decodifica JSON: " . $e->getMessage());
}

/**
 * Verifica minima della struttura attesa.
 */
if (!isset($payload[´status´], $payload[´data´]) || $payload[´status´] !== ´ok´ || !is_array($payload[´data´])) {
    die("Risposta API non valida o incompleta.");
}

/**
 * Filtra e normalizza i dati utili.
 * Obiettivo: creare una lista semplice con pochi campi essenziali.
 */
$products = array_map(function (array $item): array {
    return [
        ´id´ => $item[´id´] ?? null,
        ´name´ => $item[´name´] ?? ´Nome non disponibile´,
        ´price´ => isset($item[´price´]) ? number_format((float)$item[´price´], 2, ´,´, ´.´) : ´0,00´,
        ´currency´ => $item[´currency´] ?? ´EUR´,
        ´in_stock´ => (($item[´stock´] ?? 0) > 0),
        ´category_name´ => $item[´category´][´name´] ?? ´Categoria sconosciuta´,
        ´supplier_name´ => $item[´supplier´][´name´] ?? ´Fornitore non indicato´,
        ´primary_tag´ => $item[´tags´][0] ?? null
    ];
}, $payload[´data´]);

/**
 * Esempio di filtro ulteriore:
 * teniamo solo i prodotti disponibili in stock.
 */
$availableProducts = array_values(array_filter($products, function (array $product): bool {
    return $product[´in_stock´] === true;
}));

/**
 * Output finale in HTML.
 */
echo "<h2>Prodotti disponibili</h2>";
echo "<ul>";

foreach ($availableProducts as $product) {
    echo "<li>";
    echo "<strong>" . htmlspecialchars((string)$product[´name´]) . "</strong> - ";
    echo $product[´price´] . " " . htmlspecialchars($product[´currency´]);
    echo " | Categoria: " . htmlspecialchars($product[´category_name´]);
    echo " | Fornitore: " . htmlspecialchars($product[´supplier_name´]);
    echo " | Tag: " . htmlspecialchars((string)($product[´primary_tag´] ?? ´n/d´));
    echo "</li>";
}

echo "</ul>";

Spiegazione

Il codice parte da una stringa JSON di esempio, ma il flusso è lo stesso anche se il JSON arriva da una API reale. La prima operazione importante è la decodifica tramite json_decode() con il secondo parametro impostato a true, così da ottenere un array associativo invece di un oggetto.

La scelta di usare JSON_THROW_ON_ERROR è molto utile: se il JSON è malformato, PHP lancia un’eccezione JsonException invece di restituire null in modo ambiguo. Questo rende il debug più semplice e il codice più affidabile.

Subito dopo, il tutorial verifica che la risposta contenga i campi attesi: status e data. In un contesto reale, una API può restituire messaggi di errore, dati parziali o strutture diverse in base al risultato. Controllare la forma del payload è una buona abitudine.

La parte centrale è il filtraggio con array_map(). Qui trasformiamo ogni prodotto in una struttura più semplice, mantenendo solo i dati davvero utili:

  • id per identificare il prodotto;
  • name per il titolo;
  • price formattato per la visualizzazione;
  • currency per indicare la valuta;
  • in_stock come valore booleano derivato dallo stock;
  • category_name e supplier_name estratti da oggetti annidati;
  • primary_tag preso come primo elemento dell’array tags.

Notare l’uso dell’operatore di coalescenza null ??: serve a fornire un valore di fallback se il campo non esiste. Questo è fondamentale quando si lavora con JSON reali, perché i campi opzionali sono frequentissimi.

Dopo la normalizzazione, il codice applica un ulteriore filtro con array_filter() per tenere solo i prodotti disponibili in stock. In questo modo si separano chiaramente due fasi:

  • trasformazione dei dati grezzi in una forma più comoda;
  • selezione dei soli elementi che rispettano una condizione.

Infine, il codice genera un elenco HTML e usa htmlspecialchars() per proteggere l’output. Anche se il dato arriva da una API esterna, è sempre buona pratica trattarlo come non fidato quando viene stampato in pagina.

Best practice

Quando gestisci JSON proveniente da API in PHP, ci sono alcune regole pratiche che fanno davvero la differenza nel lungo periodo.

  • Usa sempre JSON_THROW_ON_ERROR per intercettare subito JSON non valido.
  • Valida la struttura minima attesa: non dare per scontato che i campi esistano.
  • Normalizza i dati subito: converti il JSON in una struttura interna semplice e coerente.
  • Separa trasformazione e visualizzazione: prima filtra i dati, poi stampali o inviali ad altri componenti.
  • Proteggi l’output con htmlspecialchars() quando mostri dati in HTML.
  • Gestisci i campi opzionali con fallback sensati, evitando warning e notice.
  • Preferisci funzioni pure per il filtraggio: sono più facili da testare e mantenere.

Un altro consiglio importante è non lavorare direttamente con la struttura JSON originale in tutta l’applicazione. Se la API cambia nome a un campo, rischi di dover modificare molti punti del codice. Conviene invece creare uno strato di trasformazione, come abbiamo fatto con array_map(), che “traduca” il payload esterno in un formato interno stabile.

Se i dati arrivano da una fonte remota, considera anche la gestione di timeout, errori di rete e risposte HTTP non 200. Il problema non è solo il JSON in sé, ma l’intero processo di acquisizione del dato.

Riepilogo

In questo tutorial abbiamo visto un caso molto concreto: leggere un JSON proveniente da una API e filtrarlo in PHP per ottenere una struttura più semplice e utile. Il flusso corretto è:

  • ricevere il JSON;
  • decodificarlo con gestione esplicita degli errori;
  • verificare la struttura minima;
  • trasformare i dati con array_map();
  • filtrare gli elementi con array_filter();
  • stampare i risultati in modo sicuro.

Questa tecnica è molto utile in dashboard, cataloghi prodotti, report, integrazioni con servizi esterni e qualsiasi progetto PHP che debba consumare dati JSON in modo affidabile.

Approfondisci con risorse ufficiali

Add as preferred source on Google
SHARE