Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Regular Expressions

PHP preg_replace_callback() function

Reference for PHP preg_replace_callback(): replace regex matches with the result of a function, use named groups, flags, limits and preg_replace_callback_array().

The preg_replace_callback() function finds every match of a regular expression and replaces it with whatever your callback returns. PHP calls the function once per match and passes it an array of the captured text, so the new text can depend on real logic: a lookup table, arithmetic, formatting or validation.

Use it when preg_replace() cannot express the replacement with $1-style references. It is also the safe choice when the replacement comes from user input, because the text you return is inserted as-is and never parsed for references.

PHP
<?php
echo preg_replace_callback('/\d+/', fn (array $m): string => (string) ($m[0] * 2), 'a1 b20 c300');

Try it

PHP Computing each replacement

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Named groups, limits, counts and a callback array

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
preg_replace_callback(
    string|array $pattern,
    callable $callback,
    string|array $subject,
    int $limit = -1,
    int &$count = null,
    int $flags = 0
): string|array|null
Name Description
$pattern A pattern or an array of patterns.
$callback A callable that receives the matches array ($m[0] is the whole match, $m[1]... the groups, named groups under their names) and must return a string.
$subject A string, or an array of strings (the result is then an array with the same keys).
$limit Maximum replacements per pattern per subject. -1 means no limit.
$count Optional. Set to the total number of replacements.
$flags PREG_OFFSET_CAPTURE and/or PREG_UNMATCHED_AS_NULL.

Return value: the new string or array, or null if an error occurred (broken pattern, invalid UTF-8 with /u, backtrack limit).

Errors / Exceptions: a callback that returns an array or an object without __toString() cannot be turned into text and raises an error. An exception thrown by the callback propagates to the caller.

Usage notes

  • The callback gets one array, not many arguments. Trailing groups that did not take part in the match are left out unless you pass PREG_UNMATCHED_AS_NULL, so read optional groups with ??.
  • Return a string. Cast numbers yourself ((string) $n) so strict-types code stays clean.
  • No reference syntax in the result. Unlike preg_replace(), a returned $1 or backslash is literal text, which makes this function the right tool for untrusted replacement text.
  • Several patterns are applied in order, each one to the result of the previous one. preg_replace_callback_array() takes a pattern => callback map and is the tidier form.
  • Keep callbacks pure and fast. They run once per match, so a regex with thousands of matches calls your function thousands of times.
  • Check for null, and call preg_last_error() to learn why.
  • Static callbacks (static fn) avoid capturing $this when you do not need the object.
  • Not matching returns the subject unchanged and never calls the callback.