str_ireplace()

La funzione str_ireplace() in PHP sostituisce tutte le occorrenze di una stringa di ricerca con una stringa di sostituzione, ignorando la distinzione tra maiuscole e minuscole. È il gemello case-insensitive di str_replace(): tutto funziona allo stesso modo, tranne che la ricerca non è sensibile alle lettere maiuscole e minuscole. Questo rende str_ireplace() la scelta giusta quando la combinazione di maiuscole e minuscole del testo di destinazione è sconosciuta o inconsistente — ad esempio, quando si elabora l'input dell'utente o si normalizzano tag che possono apparire come PHP, php o Php.

Questo articolo tratta la sintassi di str_ireplace(), il comportamento di ciascun parametro, come lavorare con gli array, come contare le sostituzioni e le insidie da tenere a mente.

Sintassi

str_ireplace(
    array|string $search,
    array|string $replace,
    string|array $subject,
    int &$count = null
): string|array

La funzione accetta tre parametri obbligatori e uno opzionale:

• $search — il valore (o array di valori) da cercare.
• $replace — il valore (o array di valori) con cui sostituirlo.
• $subject — la stringa (o array di stringhe) in cui cercare.
• $count (opzionale) — una variabile passata per riferimento che viene riempita con il numero totale di sostituzioni effettuate.

Restituisce il $subject modificato. Se $subject è un array, viene restituito un array con la sostituzione applicata a ogni elemento.

Esempio base

Anche se cerchiamo "FOX" in maiuscolo, str_ireplace() ignora la distinzione tra maiuscole e minuscole e trova il "fox" minuscolo nel soggetto. L'output è:

The quick brown cat jumps over the lazy dog

Con la funzione standard e case-sensitive str_replace(), la stessa chiamata non troverebbe corrispondenze e la stringa verrebbe restituita invariata.

Utilizzo di array per ricerca e sostituzione

Quando $search e $replace sono entrambi array, ogni valore di ricerca viene abbinato alla sostituzione con lo stesso indice. Questo permette di eseguire più sostituzioni in una sola chiamata:

<?php
$search  = ["red", "GREEN", "Blue"];
$replace = ["crimson", "emerald", "navy"];
$subject = "Red, green and blue are colors.";

echo str_ireplace($search, $replace, $subject);
// crimson, emerald and navy are colors.
?>

Si noti che la combinazione di maiuscole e minuscole delle voci in $search non ha importanza — "GREEN" corrisponde comunque a "green". Se $replace ha meno elementi di $search, le sostituzioni mancanti vengono trattate come stringhe vuote (le corrispondenze vengono rimosse).

Quando $search è un array ma $replace è una singola stringa, quella stringa sostituisce ogni valore di ricerca:

<?php
echo str_ireplace(["cats", "dogs"], "pets", "I have CATS and Dogs.");
// I have pets and pets.
?>

Contare le sostituzioni con $count

Passa un quarto argomento per riferimento per sapere quante sostituzioni sono state effettuate:

<?php
$text   = "PHP is great. php is fun. PhP rocks.";
$result = str_ireplace("php", "PHP", $text, $count);

echo $result . "\n";       // PHP is great. PHP is fun. PHP rocks.
echo "Replacements: $count"; // Replacements: 3
?>

Le tre varianti PHP, php e PhP vengono tutte trovate, quindi $count è 3. Questo è utile per la validazione — ad esempio, per verificare se una parola vietata è apparsa.

Insidie da tenere a mente

• La sostituzione non viene cercata di nuovo. str_ireplace() elabora i termini di ricerca da sinistra a destra e non riscansiona mai il testo già inserito, quindi non può andare in loop infinito. Ma l'ordine è comunque importante quando un termine di ricerca è una sottostringa di un altro.
• Opera sui byte, non sui caratteri multibyte. Per il testo UTF-8 in cui la case-insensitivity deve rispettare lettere accentate o non latine, str_ireplace() potrebbe non comportarsi come previsto. Usa le funzioni stringa mb_* di PHP o preg_replace() con il modificatore i.
• Usa str_replace() quando le maiuscole/minuscole sono importanti. Se hai bisogno di una corrispondenza esatta e case-sensitive, usa str_replace() — è leggermente più veloce perché salta il passaggio di normalizzazione delle maiuscole.

Riepilogo

str_ireplace() esegue la ricerca e sostituzione case-insensitive sulle stringhe. Usala per sostituzioni semplici e letterali dove le maiuscole/minuscole devono essere ignorate; usa str_replace() quando le maiuscole/minuscole sono importanti, e preg_replace() quando hai bisogno di corrispondenze basate su pattern o consapevoli dei caratteri multibyte.

Pratica