PHP preg_replace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Regex

Definition

In PHP, preg_replace() replaces every match of a regular expression with a replacement string (or each pattern in an array).

It works on a string or an array of strings. Unlike preg_filter(), non-matching subjects are kept unchanged. You can limit how many replacements happen and receive the count by reference.

Syntax

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

PHP
$new = preg_replace('/\s+/', ' ', $text);
CallWhat it does
preg_replace('/\d+/', '#', 'a1b22c')Returns "a#b#c".
preg_replace('/cat/', 'dog', 'a cat')Returns "a dog".
preg_replace('/\d+/', 'X', 'hello')Returns "hello" unchanged when nothing matches.

In the replacement, $0 is the full match and $1, $2 are capturing groups. For per-match PHP logic, use preg_replace_callback() instead.

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

Parameters

ParameterDescription
patternRequired. A pattern string with delimiters, or an array of patterns.
replacementRequired. Replacement string or array of strings. May include $n backreferences.
subjectRequired. String or array of strings to rewrite.
limitOptional. Max replacements per subject. Default -1 means replace all.
countOptional. Receives the number of replacements performed.

Return Value

Return ValueDescription
string|array|nullThe subject after replacements. For arrays, every element is returned (changed or not). null on error.

PHP Examples

Example 1 — Replace Digits with a Marker

Swap every run of digits for a single # character.

PHP
<?php
echo preg_replace('/\d+/', '#', 'a1b22c'), PHP_EOL;

How It Works

  1. The pattern /\d+/ matches one or more digits.
  2. 1 and 22 are each replaced with #.
  3. Letters stay in place.
  4. The final string is a#b#c.

Example 2 — Limit Replacements and Count Them

Replace only once and capture how many changes were made.

PHP
<?php
$text = 'a1b2c3';
$result = preg_replace('/\d/', 'X', $text, 1, $count);
echo $result, PHP_EOL;
echo $count, PHP_EOL;

How It Works

  1. Without a limit, every digit would become X.
  2. limit 1 stops after the first replacement.
  3. Only the first digit changes, so the result is aXb2c3.
  4. $count is 1 because only one replacement ran.

Example 3 — Use a Backreference in the Replacement

Wrap each matched word in brackets using $0.

PHP
<?php
echo preg_replace('/[a-z]+/', '[$0]', 'hi 42 bye'), PHP_EOL;

How It Works

  1. The pattern matches lowercase words.
  2. $0 in the replacement means the full match.
  3. hi and bye become [hi] and [bye].
  4. 42 is left alone because it is not matched by [a-z]+.

Frequently Asked Questions

It searches a string (or array of strings) for a regular expression and replaces each match with the given replacement.
Both replace matches. preg_replace() always returns every subject. preg_filter() returns only subjects that matched (or null for a non-matching string).
Use preg_replace_callback() or preg_replace_callback_array(). Those pass each match to your callable.
It caps how many replacements happen for each subject. -1 means no limit.
Only after careful escaping with preg_quote() for literal parts. Prefer fixed patterns. Untrusted patterns risk errors and ReDoS.

Next: preg_replace_callback()

preg_replace_callback() replaces each regex match by calling your function to build the re.

preg_replace_callback() 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