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 echo preg_replace_callback('/\d+/', fn (array $m): string => (string) ($m[0] * 2), 'a1 b20 c300');
Try it
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.
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
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$1or 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 apattern => callbackmap 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 callpreg_last_error()to learn why. - Static callbacks (
static fn) avoid capturing$thiswhen you do not need the object. - Not matching returns the subject unchanged and never calls the callback.