preg_replace_callback_array

Introduzione

In PHP, le espressioni regolari sono uno strumento essenziale per confrontare, cercare e trasformare stringhe. Disponibile dalla versione PHP 7.1, la funzione preg_replace_callback_array() consente di sostituire tutte le corrispondenze di diversi pattern di espressioni regolari in un'unica chiamata, dove ogni pattern ha il proprio callback che calcola la sostituzione. È la controparte basata su array di preg_replace_callback(): invece di passare un pattern e un callback, si passa una mappa di coppie pattern => callback.

Questo capitolo spiega cosa restituisce la funzione, illustra i suoi parametri e mostra esempi eseguibili, incluse le insidie più comuni relative all'ordine dei pattern e ai tipi di ritorno.

Quando usarla

Ricorri a preg_replace_callback_array() quando:

• Devi applicare logica di sostituzione diversa a pattern diversi in un'unica passata sul soggetto.
• Altrimenti dovresti concatenare più chiamate a preg_replace_callback() — raggrupparle mantiene il codice leggibile e l'intento in un unico punto.
• Il valore di sostituzione non può essere espresso come stringa statica, quindi il semplice preg_replace() non è sufficiente — devi calcolarlo dal testo trovato.

Se hai un solo pattern, usa preg_replace_callback(). Se le sostituzioni sono stringhe fisse, usa preg_replace().

Sintassi

preg_replace_callback_array(
    array $pattern_and_callbacks,
    string|array $subject,
    int $limit = -1,
    int &$count = null,
    int $flags = 0
): string|array|null

Valore di ritorno: se $subject è una stringa, viene restituita una stringa; se $subject è un array, viene restituito un array. In caso di errore regex restituisce null.

Nota: I callback devono restituire una stringa. Un valore di ritorno numerico (come un int) viene automaticamente convertito in stringa. Restituire null produce una stringa vuota.

Esempio di base

Il primo callback converte in maiuscolo ogni parola; il secondo incrementa ogni sequenza di cifre. Entrambi i pattern vengono applicati allo stesso soggetto in un'unica chiamata.

<?php

$patterns_and_callbacks = [
  '/[a-z]+/i' => function ($matches) {
    return strtoupper($matches[0]);
  },
  '/\d+/' => function ($matches) {
    return (int) $matches[0] + 1;
  },
];

$string = 'This is a test string with 1234';

echo preg_replace_callback_array($patterns_and_callbacks, $string);
// THIS IS A TEST STRING WITH 1235

Qui $matches[0] è il testo completo corrispondente al pattern. Il secondo callback restituisce un intero (1234 + 1), che PHP converte nella stringa "1235".

L'ordine dei pattern è importante

I pattern vengono applicati nell'ordine dell'array, e ognuno opera sul risultato del precedente. Ciò significa che un callback precedente può modificare il testo che un pattern successivo vede — una fonte comune di sorprese.

<?php

$subject = 'abc123';

$result = preg_replace_callback_array([
  // Runs first: wraps every digit run in brackets.
  '/\d+/' => fn ($m) => '[' . $m[0] . ']',
  // Runs second: now sees "abc[123]" and upper-cases the letters.
  '/[a-z]+/' => fn ($m) => strtoupper($m[0]),
], $subject);

echo $result;
// ABC[123]

Se invertissi i due pattern, le lettere verrebbero convertite in maiuscolo prima che il pattern delle cifre venisse eseguito — il risultato per le cifre è lo stesso, ma in generale l'ordine può cambiare l'output.

Contare le sostituzioni con $count

Passa una variabile come quarto argomento per sapere quante sostituzioni sono avvenute tra tutti i pattern.

<?php

$subject = 'cat dog cat bird cat';

$result = preg_replace_callback_array(
  ['/cat/' => fn ($m) => 'fish'],
  $subject,
  -1,
  $count
);

echo $result . "\n"; // fish dog fish bird fish
echo "Replacements: $count"; // Replacements: 3

Lavorare con un array come soggetto

Quando $subject è un array, la funzione elabora ogni elemento e restituisce un array della stessa forma.

<?php

$subjects = ['Order #12', 'Order #7'];

$result = preg_replace_callback_array(
  ['/\d+/' => fn ($m) => str_pad($m[0], 4, '0', STR_PAD_LEFT)],
  $subjects
);

print_r($result);
// Array
// (
//     [0] => Order #0012
//     [1] => Order #0007
// )

Insidie comuni

• Dimenticare i delimitatori. Le chiavi devono essere stringhe regex valide con delimitatori, ad es. '/\d+/', non '\d+'. Un delimitatore mancante fa sì che la chiamata restituisca null e generi un avviso.
• Restituire non-stringhe intenzionalmente. Sebbene i ritorni numerici vengano convertiti automaticamente, restituire array od oggetti genera un TypeError. Converti o formatta il valore prima di restituirlo.
• Supporre che i pattern siano indipendenti. Come mostrato sopra, ogni pattern opera sull'output del precedente. Organizza la mappa deliberatamente.
• Usare gruppi di cattura vs. la corrispondenza completa. $matches[0] è l'intera corrispondenza; $matches[1], $matches[2], … sono i gruppi catturati. Fai riferimento all'indice corretto per la tua logica.

Funzioni correlate

• preg_replace_callback() — pattern singolo + callback singolo.
• preg_replace() — sostituisce con stringhe statiche o backreference.
• preg_match() e preg_match_all() — trova corrispondenze senza sostituire.
• PHP callback functions — come funzionano i callable in PHP.

Conclusione

preg_replace_callback_array() offre un modo pulito e in singola passata per applicare logiche di sostituzione diverse a più pattern regex. Eccelle quando ogni pattern necessita della propria sostituzione calcolata, sostituendo quella che altrimenti sarebbe una serie di chiamate concatenate a preg_replace_callback(). Ricorda che i pattern vengono eseguiti nell'ordine dell'array e che i callback devono restituire stringhe, e la funzione manterrà il codice di trasformazione del testo compatto e leggibile.

Esercizio