str_ireplace()

La fonction str_ireplace() en PHP remplace toutes les occurrences d'une chaîne recherchée par une chaîne de remplacement, sans tenir compte de la casse. C'est la variante insensible à la casse de str_replace() : tout fonctionne de la même manière, sauf que la recherche ne distingue pas les majuscules des minuscules. Cela fait de str_ireplace() le bon choix lorsque la casse du texte cible est inconnue ou incohérente — par exemple, lors du nettoyage de saisies utilisateur ou de la normalisation de balises qui peuvent apparaître sous la forme PHP, php ou Php.

Cet article couvre la syntaxe de str_ireplace(), le comportement de chaque paramètre, l'utilisation des tableaux, le comptage des remplacements et les pièges à éviter.

Syntaxe

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

La fonction prend trois paramètres obligatoires et un optionnel :

• $search — la valeur (ou tableau de valeurs) à rechercher.
• $replace — la valeur (ou tableau de valeurs) par laquelle la remplacer.
• $subject — la chaîne (ou tableau de chaînes) dans laquelle effectuer la recherche.
• $count (optionnel) — une variable passée par référence qui est renseignée avec le nombre total de remplacements effectués.

La fonction retourne le $subject modifié. Si $subject est un tableau, un tableau est retourné avec le remplacement appliqué à chaque élément.

Exemple de base

Même si nous recherchons "FOX" en majuscules, str_ireplace() ignore la casse et correspond au "fox" en minuscules dans le sujet. Le résultat est :

The quick brown cat jumps over the lazy dog

Avec la fonction str_replace() standard, sensible à la casse, le même appel ne trouverait aucune correspondance et la chaîne serait retournée inchangée.

Utiliser des tableaux pour la recherche et le remplacement

Lorsque $search et $replace sont tous deux des tableaux, chaque valeur de recherche est associée au remplacement situé au même index. Cela permet d'effectuer plusieurs substitutions en un seul appel :

<?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.
?>

Notez que la casse des entrées dans $search n'a pas d'importance — "GREEN" correspond quand même à "green". Si $replace contient moins d'éléments que $search, les remplacements manquants sont traités comme des chaînes vides (les correspondances sont supprimées).

Lorsque $search est un tableau mais que $replace est une chaîne unique, cette chaîne remplace toutes les valeurs recherchées :

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

Compter les remplacements avec $count

Passez un quatrième argument par référence pour savoir combien de remplacements ont été effectués :

<?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
?>

Les trois variantes PHP, php et PhP sont toutes reconnues, donc $count vaut 3. Cela est pratique pour la validation — par exemple, vérifier si un mot interdit est apparu.

Pièges à garder à l'esprit

• Le remplacement n'est pas recherché à nouveau. str_ireplace() traite les termes de recherche de gauche à droite et ne re-scanne jamais le texte déjà inséré, donc elle ne peut pas boucler indéfiniment. Mais l'ordre a toujours de l'importance lorsqu'un terme de recherche est une sous-chaîne d'un autre.
• Elle opère sur les octets, pas sur les caractères multioctets. Pour les textes UTF-8 où l'insensibilité à la casse doit respecter les lettres accentuées ou non latines, str_ireplace() peut ne pas se comporter comme prévu. Utilisez plutôt les fonctions de chaîne mb_* de PHP ou preg_replace() avec le modificateur i.
• Utilisez str_replace() quand la casse est importante. Si vous avez besoin d'une correspondance exacte sensible à la casse, utilisez str_replace() — elle est légèrement plus rapide car elle saute l'étape de normalisation de la casse.

Résumé

str_ireplace() effectue une recherche-remplacement insensible à la casse sur des chaînes. Utilisez-la pour des substitutions simples et littérales où la casse doit être ignorée ; utilisez str_replace() lorsque la casse est importante, et preg_replace() lorsque vous avez besoin d'une correspondance basée sur des motifs ou tenant compte des caractères multioctets.

Pratique