substr_replace()
Функция substr_replace() в PHP заменяет часть строки другой строкой по числовой позиции.
Введение
Функция substr_replace() заменяет часть строки другой строкой, опираясь на числовую позицию, а не на поисковый шаблон. Вы указываете где начать и сколько символов перезаписать, и функция вставляет замену на указанное место. Это делает её идеальной для правок в фиксированных позициях — маскировки цифр кредитной карты, замены части даты или вставки текста по известному смещению.
Это отличается от str_replace(), которая находит и заменяет по совпадению подстроки. Используйте substr_replace(), когда знаете позицию; используйте str_replace(), когда знаете значение.
Синтаксис
substr_replace(
array|string $string,
array|string $replace,
array|int $offset,
array|int|null $length = null
): string|array| Параметр | Описание |
|---|---|
$string | Входная строка (или массив строк — см. Работа с массивами). |
$replace | Строка замены, вставляемая на позицию $offset. |
$offset | Место начала замены. Отрицательное значение отсчитывается от конца строки. |
$length | Количество символов для перезаписи. Пропустите (или передайте null), чтобы заменить до конца строки. Отрицательное значение останавливает замену за столько символов до конца. 0 вставляет текст без удаления символов. |
Функция возвращает результирующую строку. Она не изменяет $string на месте — необходимо захватить возвращаемое значение.
Базовый пример
Начиная с индекса 7 (w), пять символов удаляются и на их место вставляется "universe".
Вставка без удаления
Передайте 0 в качестве длины, и ничего не будет удалено — замена просто вставится перед смещением.
<?php
echo substr_replace("Hello", "ABC", 2, 0); // HeABClloЗамена с отрицательным смещением
Отрицательный $offset отсчитывается от конца строки, что удобно, когда длина заранее неизвестна.
<?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)Практический пример: маскировка цифр
Перезапись известного фрагмента тем же количеством символов * — распространённый реальный случай, например, скрытие части номера карты.
<?php
$card = "4111111111111111";
echo substr_replace($card, "********", 4, 8); // 4111********1111Работа с массивами
Если передать массив строк, substr_replace() применит замену к каждому элементу и вернёт новый массив. Вы также можете передать массивы для $replace, $offset и $length, чтобы использовать разные значения для каждого элемента.
<?php
$names = ["Alice", "Bob", "Carol"];
$result = substr_replace($names, "***", 1, 2);
print_r($result);
// Array
// (
// [0] => A***ce
// [1] => B***
// [2] => C***ol
// )Распространённые ошибки
- Функция возвращает новую строку.
substr_replace($s, ...)без присвоения ничего не сделает — сохраните или выведите результат. - Смещения являются байтовыми позициями, а не позициями символов. Для многобайтового (UTF-8) текста не существует
mb_substr_replace; тщательно вычисляйте смещения или перестройте строку с помощьюmb_substr(). - Смещение за пределами конца строки добавляет замену в конец, а не перезаписывает.
Связанные функции
str_replace()— замена по значению, а не по позиции.substr()— извлечение части строки.strpos()— поиск позиции для передачи вsubstr_replace().str_pad()— дополнение строки до заданной длины.
Заключение
substr_replace() — это аналог str_replace(), работающий по позиции. Как только вы запомните, что смещение и длина описывают срез — и что длина 0 вставляет текст, а отрицательное смещение отсчитывается от конца — функция станет точным инструментом для маскировки, соединения и редактирования строк в известных позициях.