Perform a regular expression search and replace

- « PCRE Functions

- preg_grep »

- PHP Manual
- PCRE Functions
- Perform a regular expression search and replace

# preg_filter

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

preg_filter — Perform a regular expression search and replace

### Description

preg_filter(
string|array `$pattern`,
string|array `$replacement`,
string|array `$subject`,
int `$limit` = -1,
int `&$count` = `null`
): string|array|null

preg_filter() is identical to preg_replace() except it only returns the (possibly transformed) subjects where there was a match. For details about how this function works, read the preg_replace() documentation.

### Parameters

Parameters are described in the documentation for preg_replace().

### Return Values

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.

### Errors/Exceptions

If the regex pattern passed does not compile to a valid regex, an `E_WARNING` is emitted.

### Examples

Example #1 Example comparing preg_filter() with preg_replace()

    <?php$subject = array('1', 'a', '2', 'b', '3', 'A', 'B', '4'); $pattern = array('/\d/', '/[a-z]/', '/[1a]/'); $replace = array('A:$0', 'B:$0', 'C:$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 above example will output:

    preg_filter returns
    Array
    (
        [0] => A:C:1
        [1] => B:C:a
        [2] => A:2
        [3] => B:b
        [4] => A:3
        [7] => A:4
    )
    preg_replace returns
    Array
    (
        [0] => A:C:1
        [1] => B:C:a
        [2] => A:2
        [3] => B:b
        [4] => A:3
        [5] => A
        [6] => B
        [7] => A:4
    )

### See Also

- PCRE Patterns
- preg_quote() - Quote regular expression characters
- preg_replace() - Perform a regular expression search and replace
- preg_replace_callback() - Perform a regular expression search and replace using a callback
- preg_grep() - Return array entries that match the pattern
- preg_last_error() - Returns the error code of the last PCRE regex execution