preg_match()

Introduzione

preg_match() esegue una corrispondenza con un'espressione regolare su una stringa. Indica se un pattern PCRE è presente nel soggetto e, facoltativamente, acquisisce cosa ha trovato. Si ferma alla prima corrispondenza — se hai bisogno di ogni occorrenza, usa invece preg_match_all().

Questo capitolo tratta la firma e i valori di ritorno, come viene popolato l'array $matches, i flag più utili e le insidie (la trappola 0 vs false, l'ancoraggio, i delimitatori) che causano spesso problemi.

Sintassi

preg_match(
    string $pattern,
    string $subject,
    array &$matches = null,
    int $flags = 0,
    int $offset = 0
): int|false

Valore di ritorno: 1 se il pattern ha trovato una corrispondenza, 0 se non l'ha trovata, oppure false in caso di errore (pattern non valido). Poiché preg_match() restituisce al massimo 1, non indica quante corrispondenze esistono — solo che ce n'era una.

Esempio base

Il pattern acquisisce una parola alfabetica seguita da spazio bianco e un'altra parola. In caso di corrispondenza, $matches[0] contiene la corrispondenza completa (This is), mentre $matches[1] / $matches[2] contengono i due gruppi acquisiti (This e is).

La trappola 0 vs false

Un bug molto comune è usare == per testare il risultato. preg_match() restituisce 0 per "nessuna corrispondenza" e false solo in caso di errore, e 0 == false è true in PHP. Confronta sempre con l'operatore stretto:

<?php

$result = preg_match('/[0-9]+/', 'abc');

// Wrong: treats "no match" and "error" the same
if ($result == false) {
  echo "ambiguous\n";
}

// Right: distinguish the three outcomes
if ($result === false) {
  echo "Error in the pattern\n";
} elseif ($result === 0) {
  echo "No match\n";
} else {
  echo "Matched\n";
}

Questo stampa ambiguous e poi No match.

Gruppi con nome

Aggiungi (?<name>...) al tuo pattern e $matches conterrà le acquisizioni sia con l'indice numerico che con il nome, il che mantiene il codice leggibile quando l'ordine dei gruppi cambia:

<?php

$date = '2026-06-21';
preg_match('/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/', $date, $m);

echo $m['year'] . "\n";  // 2026
echo $m['month'] . "\n"; // 06
echo $m['day'];          // 21

Acquisizione degli offset con PREG_OFFSET_CAPTURE

Passa il flag PREG_OFFSET_CAPTURE e ogni voce in $matches diventa una coppia [testo_corrispondente, byte_offset], così puoi sapere dove si è verificata la corrispondenza:

<?php

preg_match('/world/', 'hello world', $m, PREG_OFFSET_CAPTURE);

echo $m[0][0] . "\n"; // world
echo $m[0][1];        // 6

Pattern case-insensitive e ancorati

I modificatori vanno dopo il delimitatore di chiusura. Il modificatore i ignora le maiuscole/minuscole; ^ e $ ancorano la corrispondenza all'inizio e alla fine della stringa, così l'intero soggetto deve corrispondere al pattern:

<?php

var_dump(preg_match('/^hello$/i', 'HELLO')); // int(1)
var_dump(preg_match('/^hello$/i', 'hello!')); // int(0)

Quando usare qualcos'altro

• Ogni occorrenza, non solo la prima → preg_match_all().
• Cerca e sostituisci → preg_replace().
• Dividi una stringa su un pattern → preg_split(); per un delimitatore fisso, il semplice explode() è più veloce.
• Sfuggi l'input dell'utente prima di incorporarlo in un pattern → preg_quote().
• Un ripasso della sintassi PCRE → il capitolo sulle espressioni regolari PHP.

Conclusione

preg_match() è la funzione principale per verificare se una stringa corrisponde a un pattern e per estrarre i gruppi acquisiti. Ricorda i suoi tre valori di ritorno, confronta con === per evitare la trappola 0/false, e passa a preg_match_all() quando una sola corrispondenza non è sufficiente.

Esercitazione