preg_replace
(PHP 4, PHP 5, PHP 7, PHP 8)
preg_replace — Здійснює пошук та заміну за регулярним виразом.
Опис
preg_replace( string|array $pattern, string|array $replacement, string|array $subject, int $limit = -1, int &$count = null): string|array|null
Виконує пошук збігів у рядку subject із шаблоном pattern і замінює їх на replacement
Для відповідності точному рядку, а не шаблону, замість цієї функції використовуйте функцію str_replace() або str_ireplace()
Список параметрів
pattern
Шуканий шаблон. Можливо як рядком, і масивом рядків.
Також доступні деякі модифікатори PCRE
replacement
Рядок або масив рядків для заміни. Якщо цей параметр є рядком, а pattern є масивом, всі шаблони будуть замінені цим рядком. Якщо і patternиreplacement є масивами, кожен елемент pattern буде замінений відповідним елементом з replacement. Якщо масив replacement містить менше елементів, ніж масив pattern, то всі зайві шаблони з pattern будуть замінені порожніми рядками.
replacement може містити посилання на вид \n, либо$n, причому останній варіант кращий. Кожне таке посилання буде замінено на підрядок, що відповідає n-ой підмасці. n може набувати значень від 0 до 99, причому посилання \0(либо$0) відповідає входженню всього шаблону. Підмаски нумеруються зліва направо, починаючи з одиниці. Зверніть увагу, що зворотні сліші у рядку (string) літерали можуть вимагати екранування.
При заміні за шаблоном з використанням посилань на підмаски може виникнути ситуація, коли безпосередньо за маскою слідує цифра (наприклад, встановлення цифри відразу після маски, що збіглася). У такому разі не можна використовувати знайому нотацію виду \1 для посилання на підмаски. Запис, наприклад, \11, збентежить preg_replace(), так як вона не зможе зрозуміти, чи хочете ви використовувати посилання \1, за якою слідує цифра або ж ви хочете просто використовувати посилання \11, за якою нічого не слідує. Це непорозуміння можна усунути, якщо скористатися конструкцією ${1}1, що використовує ізольоване посилання $1, і наступну за нею цифру
При использовании устаревшего модификатораe ця функція екранує деякі символи (а саме ' " \ та NULL) у рядках, що заміщають зворотні посилання. Це зроблено для засвідчення коректності синтаксису при використанні зворотних посилань усередині одинарних або подвійних лапок (наприклад, 'strlen(\'$1\')+strlen("$2")'). Переконайтеся, що ви володієте синтаксисом обробки рядків PHP для того, щоб точно усвідомлювати, як виглядатиме інтерпретований рядок.
subject
Рядок або масив рядків для пошуку та заміни.
Якщо subject є масивом, то пошук із заміною здійснюється для кожного елемента масиву subject, а значення, що повертається, також буде масивом.
Якщо параметр subject є асоціативним масивом, ключі будуть збережені у значенні, що повертається.
limit
Максимально можлива кількість замін кожного шаблону для кожного рядка subjectПо умолчанию равно-1 (без обмежень).
count
Якщо зазначено, то ця змінна буде заповнена кількістю зроблених замін.
Значення, що повертаються
preg_replace() повертає масив, якщо параметр subject є масивом, інакше повертається рядок.
Якщо знайдені збіги, повертається нова версія subject, иначеsubject повертається недоторканим, у разі помилки повертається null
Помилки
Використання модифікатора "\e" є помилкою; у цьому випадку видається помилка рівня E_WARNING;.
Якщо переданий шаблон регулярного виразу не компілюється в допустимий регулярний вираз, видається помилка рівня E_WARNING
Приклади
Приклад #1 Використання підмасок, за якими слідує цифра
Результат виконання наведеного прикладу:
April1,2003
Приклад #2 Використання масивів з числовими індексами як аргументи функції preg_replace()
Результат виконання наведеного прикладу:
The bear black slow jumps over the lazy dog.
Відсортувавши за ключами шаблони та заміни, отримуємо бажаний результат:
Результат виконання наведеного прикладу:
The slow black bear jumps over the lazy dog.
Приклад #3 Заміна на декілька шаблонів
Результат виконання наведеного прикладу:
$startDate = 5/27/1999
Приклад #4 Чищення пробілів
Цей приклад вичищає зайві прогалини у рядку.
Приклад #5 Использование параметраcount
Результат виконання наведеного прикладу:
xp***to
3
Примітки
Зауваження :
При использовании массивов в
patternиreplacement, ключі обробляються в порядку, в якому вони знаходяться в масиві. Цей порядок не завжди збігається з числовим порядком індексів. Якщо ви використовуєте індекси для порівняння один з одним потрібногоpatternиreplacement, то вам необхідно прогнати через функцію ksort()оба массива перед использованиемpreg_replace()
Зауваження :
Якщо і
patternиreplacementє масивами, правила відповідності діятимуть послідовно. Тобто друга параpatternreplacementбуде працювати з рядком, отриманим у результаті першої париpatternreplacement, а не з вихідним рядком. Якщо ви хочете імітувати заміну, що діє паралельно, наприклад, поміняти місцями два значення, замініть один шаблон проміжним заповнювачем, а потім у наступній парі замініть цей проміжний заповнювач необхідною заміною.
Дивіться також
- Регулярні вирази PCRE
- preg_quote() - Екранує символи у регулярних виразах
- preg_filter() - Здійснює пошук та заміну за регулярним виразом
- preg_match() - Виконує перевірку на відповідність регулярному виразу
- preg_replace_callback() - Виконує пошук за регулярним виразом та заміною з використанням callback-функції
- preg_split() - Розбиває рядок за регулярним виразом
- preg_last_error() - Повертає код помилки виконання останнього регулярного вираження PCRE
- str_replace() - Замінює всі входження рядка пошуку на рядок заміни