PHP preg_replace_callback_array() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Regex

Definition

In PHP, preg_replace_callback_array() runs several pattern-to-callback replacements from one associative array.

Each key is a PCRE pattern; each value is the callback for that pattern. Patterns are applied in array order, each to the whole subject as it stands after earlier replacements.

Syntax

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

PHP
$out = preg_replace_callback_array($map, $text);
CallWhat it does
preg_replace_callback_array(['/\d+/' => $fn], 'a12')Runs $fn for each digit run in the string.
preg_replace_callback_array($map, $text)Applies every pattern => callback pair in order.
preg_replace_callback_array($map, $text, 1)Limits replacements per pattern application.

Think of it as a tidy list of preg_replace_callback() calls. Order matters: later patterns see the text produced by earlier ones.

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

Parameters

ParameterDescription
patternRequired. Associative array of pattern => callable. Each pattern needs delimiters.
subjectRequired. String or array of strings to process.
limitOptional. Max replacements for each pattern. Default -1.
countOptional. Receives the total number of replacements across patterns.
flagsOptional. Extra flags such as PREG_OFFSET_CAPTURE. Default 0.

Return Value

Return ValueDescription
string|array|nullThe subject after all callbacks run, or null on error.

PHP Examples

Example 1 — Two Patterns, Two Callbacks

Map digit runs and letter runs to different callbacks.

PHP
<?php
$out = preg_replace_callback_array([
    '/\d+/' => function ($m) {
        return '[' . $m[0] . ']';
    },
    '/[a-z]+/' => function ($m) {
        return strtoupper($m[0]);
    },
], 'ab12cd');

echo $out, PHP_EOL;

How It Works

  1. First, /\d+/ turns 12 into [12], so the text becomes ab[12]cd.
  2. Next, /[a-z]+/ uppercases letter runs ab and cd.
  3. The digits inside [12] are not letters, so they stay.
  4. The final string is AB[12]CD.

Example 2 — Order Changes the Result

Show how a later pattern can match text inserted by an earlier callback.

PHP
<?php
$firstDigits = preg_replace_callback_array([
    '/\d+/' => function ($m) {
        return 'x' . $m[0];
    },
    '/x\d+/' => function ($m) {
        return strtoupper($m[0]);
    },
], 'a12');

$firstX = preg_replace_callback_array([
    '/x\d+/' => function ($m) {
        return strtoupper($m[0]);
    },
    '/\d+/' => function ($m) {
        return 'x' . $m[0];
    },
], 'a12');

echo $firstDigits, PHP_EOL;
echo $firstX, PHP_EOL;

How It Works

  1. In the first map, digits become x12, then /x\d+/ matches and uppercases to X12.
  2. The first result is therefore aX12.
  3. In the second map, /x\d+/ finds nothing in a12, then digits become x12.
  4. The second result stays ax12. Same callbacks, different order, different output.

Example 3 — Normalize Spaces and Mark Numbers

Chain two cleanup rules on one line of text.

PHP
<?php
$line = 'id  7   ready';
$out = preg_replace_callback_array([
    '/\s+/' => function ($m) {
        return ' ';
    },
    '/\d+/' => function ($m) {
        return '#' . $m[0];
    },
], $line);

echo $out, PHP_EOL;

How It Works

  1. The first callback collapses every whitespace run to a single space.
  2. The string becomes id 7 ready.
  3. The second callback prefixes each number with #.
  4. The final text is id #7 ready.

Frequently Asked Questions

It takes an array of pattern => callback pairs and applies each replacement in order to the subject.
preg_replace_callback() uses one pattern (or a list of patterns with one shared callback style). preg_replace_callback_array() maps each pattern to its own callback in one call.
Yes. Each pattern runs on the result of the previous ones. Later patterns can match text inserted by earlier callbacks.
The total number of replacements performed across all patterns in the map.
Yes. Any callable works: closures, functions, or [$object, 'method'] style callables.

Next: preg_split()

preg_split() splits a string into an array using a regular expression as the delimiter.

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