substr_replace()

Introduction

La fonction substr_replace() remplace une partie d'une chaîne par une autre chaîne, en se basant sur une position numérique plutôt que sur un motif de recherche. Vous lui indiquez où commencer et combien de caractères écraser, et elle insère le remplacement à cet endroit. Cela la rend idéale pour les modifications à position fixe — masquer les chiffres d'une carte de crédit, remplacer une tranche d'une date, ou insérer du texte à un décalage connu.

Cela diffère de str_replace(), qui recherche et remplace en faisant correspondre une sous-chaîne. Utilisez substr_replace() quand vous connaissez la position ; utilisez str_replace() quand vous connaissez la valeur.

Syntaxe

substr_replace(
    array|string $string,
    array|string $replace,
    array|int $offset,
    array|int|null $length = null
): string|array

La fonction retourne la chaîne résultante. Elle ne modifie pas $string en place — vous devez capturer la valeur de retour.

Exemple de base

En commençant à l'index 7 (w), cinq caractères sont supprimés et "universe" est inséré à leur place.

Insertion sans suppression

Passez 0 comme longueur et rien n'est supprimé — le remplacement est simplement inséré avant le décalage.

<?php

echo substr_replace("Hello", "ABC", 2, 0); // HeABCllo

Remplacement à partir d'un décalage négatif

Un $offset négatif compte à rebours depuis la fin de la chaîne, ce qui est pratique quand vous ne connaissez pas la longueur à l'avance.

<?php

echo substr_replace("Hello", "X", -1);     // HellX  (replace the last character)
echo "\n";
echo substr_replace("12345", "X", 1, -1);  // 1X5    (replace from index 1 to 1-before-the-end)

Exemple pratique : masquage de chiffres

Écraser une tranche connue avec le même nombre de caractères * est une utilisation courante dans la réalité — par exemple, pour masquer une partie d'un numéro de carte.

<?php

$card = "4111111111111111";
echo substr_replace($card, "********", 4, 8); // 4111********1111

Utilisation avec des tableaux

Si vous passez un tableau de chaînes, substr_replace() applique le remplacement à chaque élément et retourne un nouveau tableau. Vous pouvez également passer des tableaux pour $replace, $offset et $length afin d'utiliser des valeurs différentes par élément.

<?php

$names = ["Alice", "Bob", "Carol"];
$result = substr_replace($names, "***", 1, 2);
print_r($result);
// Array
// (
//     [0] => A***ce
//     [1] => B***
//     [2] => C***ol
// )

Erreurs courantes

• Elle retourne une nouvelle chaîne. substr_replace($s, ...) seul ne produit rien de visible — assignez ou affichez le résultat.
• Les décalages sont des positions en octets, pas en caractères. Pour les textes multi-octets (UTF-8), il n'existe pas de mb_substr_replace ; calculez les décalages avec soin ou reconstruisez la chaîne avec mb_substr().
• Un décalage au-delà de la fin de la chaîne ajoute le remplacement en fin de chaîne plutôt que d'écraser.

Fonctions associées

• str_replace() — remplacer en faisant correspondre une valeur plutôt qu'une position.
• substr() — extraire une portion d'une chaîne.
• strpos() — trouver la position à passer à substr_replace().
• str_pad() — compléter une chaîne jusqu'à une longueur donnée.

Conclusion

substr_replace() est le pendant basé sur la position de str_replace(). Une fois que vous retenez que le décalage et la longueur décrivent une tranche — et qu'une longueur de 0 insère tandis qu'un décalage négatif compte depuis la fin — c'est un outil précis pour masquer, découper et modifier des chaînes à des positions connues.

Pratique