PHP preg_replace_callback() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Regex

Definition

In PHP, preg_replace_callback() replaces each regex match by calling your function to build the replacement text.

The callback receives an array like preg_match() would put in $matches: [0] is the full match, [1] is group 1, and so on. Return the string that should replace that match.

Syntax

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

PHP
$out = preg_replace_callback('/\d+/', $fn, $text);
CallWhat it does
preg_replace_callback('/\d+/', fn($m) => $m[0] * 2, 'a2b3')Returns "a4b6" by doubling each number.
preg_replace_callback('/[a-z]+/', 'strtoupper', 'Hi')Can use a named function; returns "HI" for the letters.
preg_replace_callback('/\d+/', $fn, $text, 1)Replaces only the first match when limit is 1.

Use a callback when the replacement depends on PHP logic (math, lookup tables, conditional text). For a fixed replacement string, preg_replace() is enough.

Library declarations
PHP
preg_replace_callback(string|array $pattern, callable $callback, string|array $subject, int $limit = -1, int &$count = null, int $flags = 0): string|array|null

Parameters

ParameterDescription
patternRequired. PCRE pattern (or array of patterns) with delimiters.
callbackRequired. Callable that receives the match array and returns the replacement string.
subjectRequired. String or array of strings to process.
limitOptional. Max replacements per subject. Default -1.
countOptional. Receives how many replacements were made.
flagsOptional. For example PREG_OFFSET_CAPTURE. Default 0.

Return Value

Return ValueDescription
string|array|nullThe subject after callback replacements, or null on error.

PHP Examples

Example 1 — Double Every Number

Replace each digit run with twice its value.

PHP
<?php
$result = preg_replace_callback('/\d+/', function ($m) {
    return (string) ((int) $m[0] * 2);
}, 'a2b3');

echo $result, PHP_EOL;

How It Works

  1. The pattern /\d+/ finds 2 and then 3.
  2. For each match, the callback receives $m[0] as the matched text.
  3. The callback multiplies the number by 2 and returns it as a string.
  4. The final text is a4b6.

Example 2 — Uppercase Only Letters

Use a callback to transform letter runs and leave digits alone.

PHP
<?php
echo preg_replace_callback('/[a-z]+/', function ($m) {
    return strtoupper($m[0]);
}, 'ab12cd'), PHP_EOL;

How It Works

  1. The pattern matches ab and cd.
  2. Each match is passed to strtoupper via the callback.
  3. Digits 12 are not matched, so they stay as they are.
  4. The result is AB12CD.

Example 3 — Limit to the First Match

Show that limit still works with callbacks.

PHP
<?php
$text = '1 and 2 and 3';
$out = preg_replace_callback('/\d/', function ($m) {
    return '[' . $m[0] . ']';
}, $text, 1);

echo $out, PHP_EOL;

How It Works

  1. The callback wraps a digit in brackets.
  2. limit 1 means only the first digit is replaced.
  3. 1 becomes [1], while 2 and 3 stay plain.
  4. Use a limit when you only want the first hit changed.

Frequently Asked Questions

It finds each regex match and asks your callback for the replacement string, then builds the final subject from those returns.
An array of match pieces: index 0 is the full match, index 1 is the first capturing group, and so on — the same shape as preg_match() $matches.
When the replacement is a fixed string or simple $1-style backreferences. Use a callback when you need PHP code per match.
Use preg_replace_callback_array(), which takes an array of pattern => callback pairs.
PHP will cast it to a string. Returning an explicit string keeps intent clear, especially for 0.

Next: preg_replace_callback_array()

preg_replace_callback_array() runs several pattern-to-callback replacements from one assoc.

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