sscanf()

La funzione PHP sscanf() legge una stringa ed estrae valori secondo un formato specificato — è l'inverso di sprintf(). Mentre sprintf() costruisce una stringa formattata a partire da variabili, sscanf() scompone una stringa formattata restituendone le variabili. È particolarmente utile quando il testo ha una struttura prevedibile (date, coordinate, righe di log, codici ID) e si vogliono ottenere parti pulite e tipizzate senza scrivere un'espressione regolare.

Questo capitolo tratta la sintassi, i due modi per ricevere i risultati, gli specificatori di formato più utilizzati e le insidie comuni.

Sintassi

sscanf(string $string, string $format, mixed &...$vars): array|int|null

• $string — il testo di input da analizzare.
• $format — un template che descrive cosa leggere, usando gli specificatori % (la stessa famiglia usata da printf).
• &...$vars — variabili opzionali, passate per riferimento, che ricevono i valori analizzati.

Il comportamento di sscanf() dipende dal fatto che si passino o meno queste variabili aggiuntive:

Restituire i valori come array

Se si omettono gli argomenti per riferimento, sscanf() restituisce tutto come array. Questo è lo stile più pulito nel PHP moderno e permette di evitare il passaggio di variabili per riferimento.

%s legge la prima parola non separata da spazi (John), e %d legge un intero (25, memorizzato come vero int, non come stringa "25"). L'output è:

John
25

Assegnare direttamente nelle variabili

Passando variabili dopo il formato, i valori vengono assegnati direttamente in esse. In questa modalità il valore restituito è il numero di campi corrispondenti, utile per validare l'input.

<?php
$input = 'John 25';
$matched = sscanf($input, '%s %d', $name, $age);

echo $matched . "\n"; // 2  (both fields were read)
echo $name . "\n";    // John
echo $age;            // 25
?>

Nota: in PHP 8 il prefisso & al momento della chiamata (es. sscanf($s, $f, &$name)) è stato rimosso. È sufficiente passare la variabile semplice — sscanf() dichiara internamente quei parametri come per riferimento.

Specificatori di formato comuni

I caratteri letterali nel formato (spazi, barre, due punti) devono essere presenti anche nell'input. Questo rende sscanf() eccellente per dati a struttura fissa come le date:

<?php
$date = '2026-06-21';
[$year, $month, $day] = sscanf($date, '%d-%d-%d');

printf("Year=%d Month=%d Day=%d", $year, $month, $day);
// Year=2026 Month=6 Day=21
?>

Quando usare sscanf() rispetto alle alternative

• Si usa sscanf() quando il formato è fisso e semplice e si vogliono risultati tipizzati in una sola riga.
• Si usa explode() quando è sufficiente dividere su un delimitatore e mantenere tutto come stringhe.
• Si usa preg_match() quando la struttura è irregolare o richiede regole di validazione che vanno oltre i semplici tipi di campo.
• Per fare l'operazione inversa — assemblare una stringa formattata — si usano sprintf() o printf().

Per leggere input formattato direttamente da un file invece che da una stringa, si veda fscanf(), che funziona allo stesso modo riga per riga.

Insidie

• %s si ferma agli spazi bianchi. Non cattura un valore composto da più parole. Per leggere il resto di una riga, si usa un scanset come %[^\n].
• Un campo non corrispondente interrompe il resto. Se %d è atteso ma l'input contiene lettere, l'analisi si interrompe; il valore restituito come conteggio permette di rilevarlo.
• Le variabili finali non corrispondenti diventano null. Verificare sempre il conteggio restituito prima di fare affidamento sulle variabili successive.

Pratica