Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Regular Expressions

PHP preg_replace() function

Reference for PHP preg_replace(): replace text matched by a regular expression, use backreferences, arrays of patterns, limits, counts and the null failure value.

The preg_replace() function replaces every part of a string that matches a regular expression. The replacement can refer to captured groups with $1, ${1} or \1, so you can rearrange or reuse pieces of the matched text.

Reach for it when a plain str_replace() is not enough: patterns instead of fixed text, case-insensitive matching with /i, or reshaping text such as dates.

PHP
<?php
echo preg_replace('/\s+/', ' ', "too   many\n spaces");
// too many spaces

Try it

PHP Backreferences and limits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Arrays of patterns and arrays of subjects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
preg_replace(
    string|array $pattern,
    string|array $replacement,
    string|array $subject,
    int $limit = -1,
    int &$count = null
): string|array|null
Name Description
$pattern A pattern, or an array of patterns.
$replacement The replacement string, or an array matched to the patterns by position. References: $0 (whole match), $1..$99, ${n} for disambiguation. The older \1 form also works.
$subject A string, or an array of strings (the result is then an array with the same keys).
$limit Maximum replacements per pattern per subject. -1 means no limit.
$count Optional. Set to the total number of replacements made.

Return value: the new string (or array). Returns null if an error occurred (invalid pattern, bad UTF-8 with /u, backtracking limit).

Errors / Exceptions: an invalid pattern emits a warning and gives null. A pattern array shorter than the replacement array is fine, but a replacement array shorter than the pattern array uses empty strings for the missing ones.

Usage notes

  • Check for null. Assigning the result blindly can wipe out your data when something went wrong; see preg_last_error().
  • Group followed by a digit. $10 means group ten. Write ${1}0 to say "group one, then a zero", as in the example above.
  • Patterns in an array are applied in order, each on the result of the previous one. Swapping values this way does not work; use preg_replace_callback() or strtr().
  • No match returns the subject unchanged.
  • Quoting the replacement. A literal $ or backslash followed by a digit must be escaped with a backslash. For user text, use preg_replace_callback() so the text is not interpreted.
  • The e modifier was removed in PHP 7. Computing replacements with code is what the callback function is for.
  • Unicode: add /u for UTF-8 text, otherwise multi-byte characters can be split.
  • Performance. For fixed text prefer str_replace(), which is faster and has no escaping rules.
  • Escape user input put into the pattern with preg_quote().