PHP preg_replace() Function

The PHP preg_replace() function performs a regular expression search and replace.

Syntax

preg_replace(pattern, replacement, subject, limit, count)

Parameters

`pattern`	`Required.` Specify the pattern to search for. It can be either a string or an array with strings.
`replacement`	`Required.` Specify the string or an array with strings to replace. It replacement is done as per following: If replacement parameter is a string and the pattern parameter is an array then all patterns will be replaced by that string. If both pattern and replacement parameters are arrays, each pattern will be replaced by the replacement counterpart. If there are fewer elements in the replacement array than in the pattern array, any extra patterns will be replaced by an empty string. The replacement strings may contain a backreference in the form \n or $n where n is the index of a group in the pattern. In the returned string, instances of \n and $n will be replaced with the substring that was matched by the group or, if \0 or $0 are used, by the whole expression. n can be from 0 to 99. A backreference immediately followed by another number can be created using {}. For example - ${2}1 creates an isolated $2 backreference and 1 as a literal.
`subject`	`Required.` Specify the string or an array with strings in which replacements are being performed. If subject is an array, then the replacements is performed on every element of the array, and returns the replaced array.
`limit`	`Optional.` Specify the maximum possible replacements for each pattern in each subject string. Default is -1 (no limit).
`count`	`Optional.` If specified, this variable will contain the number of replacements done.

Return Value

Returns an array if the subject parameter is an array, or a string otherwise. If matches are found, the new subject will be returned, otherwise subject will be returned unchanged or null if an error occurred.

Example: using backreferences followed by numeric literals

The example below illustrates on using backreferences followed by numeric literals.

<?php
$string = 'May 25, 2005';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}01, $3';
echo preg_replace($pattern, $replacement, $string);
?>

The output of the above code will be:

May01, 2005

Example: using pattern and replacement as arrays

In the example below, pattern and replacement are used as arrays while using this function.

<?php
$string = 'The quick brown fox jumps over the lazy dog.';

$pattern = array('/quick/', '/brown/', '/fox/');
$replacement = array('slow', 'black', 'wolf');

echo preg_replace($pattern, $replacement, $string);
?>

The output of the above code will be:

The slow black wolf jumps over the lazy dog.

Example: using count parameter

The example below shows how to use count parameter of this function.

<?php
$count = 0;

$string = "May 1, 2015";

echo preg_replace(array('/\d/', '/\s/'), '*', 
                  $string, -1 , $count)."\n";
echo "Number of replacements: $count"; 
?>

The output of the above code will be:

May**,*****
Number of replacements: 7

Example: comparing preg_replace() with preg_filter()

The example below illustrates on difference between preg_replace() and preg_filter() functions. preg_filter() only returns the (possibly transformed) subjects where there was a match.

<?php
$subject = array('1', 'p', '2', 'q', '3', 'P', 'Q', '4'); 
$pattern = array('/\d/', '/[a-z]/', '/[1p]/'); 
$replace = array('P:$0', 'Q:$0', 'R:$0'); 

echo "preg_replace returns\n";
print_r(preg_replace($pattern, $replace, $subject)); 

echo "preg_filter returns\n";
print_r(preg_filter($pattern, $replace, $subject)); 
?>

The output of the above code will be:

preg_replace returns
Array
(
    [0] => P:R:1
    [1] => Q:R:p
    [2] => P:2
    [3] => Q:q
    [4] => P:3
    [5] => P
    [6] => Q
    [7] => P:4
)
preg_filter returns
Array
(
    [0] => P:R:1
    [1] => Q:R:p
    [2] => P:2
    [3] => Q:q
    [4] => P:3
    [7] => P:4
)

❮ PHP RegEx Reference