PHP preg_filter() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Regex

Definition

In PHP, preg_filter() runs a regular-expression replace like preg_replace(), but only keeps subjects that actually matched the pattern.

When $subject is an array, the result is an array of replaced strings for the items that matched (keys are preserved). When $subject is a string and nothing matches, the function returns null instead of the original string.

Syntax

Call preg_filter() with the values you need. Start with this line.

PHP
$result = preg_filter('/\d+/', '#', $subject);
CallWhat it does
preg_filter('/\d+/', 'X', 'dog12')Returns "dogX", because the digits matched.
preg_filter('/\d+/', 'X', 'bird')Returns null, because the string has no digits.
preg_filter('/\d+/', 'X', ['cat', 'dog12'])Returns an array with only the replaced "dogX" entry.

preg_filter() and preg_replace() use the same pattern, replacement, limit and count arguments. The difference is the return value: preg_replace() always returns every subject (changed or not), while preg_filter() drops non-matches.

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

Parameters

ParameterDescription
patternRequired. A PCRE pattern string such as /\d+/, or an array of patterns. Patterns use delimiters and optional flags.
replacementRequired. The replacement string (or array of strings). Backreferences like $1 are allowed.
subjectRequired. The string or array of strings to search.
limitOptional. Maximum replacements per subject. Default -1 means no limit.
countOptional. Passed by reference. Receives how many replacements were made.

Return Value

Return ValueDescription
string|array|nullFor a string subject: the replaced string, or null if there was no match. For an array subject: an array of only the subjects that matched (after replacement). Returns null on error.

PHP Examples

Example 1 — Replace Digits in One String

Call preg_filter() on a short string that contains digits.

PHP
<?php
$result = preg_filter('/\d+/', '#', 'a1b22c');

var_dump($result);

How It Works

  1. The pattern /\d+/ matches one or more digits. Slashes are the delimiters.
  2. preg_filter() finds 1 and 22 and replaces each with #.
  3. Because at least one match happened, you get the replaced string back.
  4. var_dump() shows the type and the final text a#b#c.

Example 2 — No Match Returns null

Compare a matching string with one that does not match.

PHP
<?php
var_dump(preg_filter('/\d+/', 'X', 'dog12'));
var_dump(preg_filter('/\d+/', 'X', 'bird'));

How It Works

  1. dog12 contains digits, so the match succeeds and the result is dogX.
  2. bird has no digits, so there is no match.
  3. For a scalar subject with no match, preg_filter() returns null.
  4. preg_replace() would have returned bird unchanged. That is the main difference.

Example 3 — Filter an Array of Subjects

Pass an array and keep only the items that matched the pattern.

PHP
<?php
$subjects = ['cat', 'dog12', 'bird', 'fish3'];
$result = preg_filter('/\d+/', 'X', $subjects);

print_r($result);

How It Works

  1. Four strings are tested against /\d+/.
  2. Only dog12 and fish3 contain digits, so only those keys remain.
  3. Keys 1 and 3 are preserved from the original array.
  4. cat and bird are dropped because they did not match.

Frequently Asked Questions

preg_filter() performs a regular-expression replace and returns only the subjects that matched. Non-matching string subjects become null; non-matching array items are omitted.
Both replace matches the same way. preg_replace() always returns every subject. preg_filter() returns only subjects that had a match, or null for a string that did not match.
When $subject is a single string and the pattern does not match, or when an error occurs. For arrays, non-matches are simply left out of the result array.
No. It returns a new value. Your original $subject variable stays the same unless you assign the result back to it.
Yes. The pattern, replacement, limit and count parameters work the same way. Only the filtering behavior of the return value is different.

Next: preg_grep()

preg_grep() filters an array and returns only the elements whose string values match a reg.

preg_grep() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful