PHP preg_filter() Function

The PHP preg_filter() function performs a regular expression search and replace. This function is similar to preg_replace() except it only returns the (possibly transformed) subjects where there was a match.

Syntax

preg_filter(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 no matches are found or an error occurred, an empty array is returned when subject is an array or null otherwise.

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_filter($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_filter() with preg_replace()

The example below illustrates on difference between preg_filter() and preg_replace() functions.

<?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_filter returns\n";
print_r(preg_filter($pattern, $replace, $subject)); 

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

The output of the above code will be:

preg_filter returns
Array
(
    [0] => P:R:1
    [1] => Q:R:p
    [2] => P:2
    [3] => Q:q
    [4] => P:3
    [7] => P:4
)
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
)

❮ PHP RegEx Reference