Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Regular Expressions

PHP regex named groups and match flags

Reference for PHP regex named groups and the PREG_PATTERN_ORDER, PREG_SET_ORDER, PREG_OFFSET_CAPTURE and PREG_UNMATCHED_AS_NULL flags, with the shape of each result.

A named group (?<name>โ€ฆ) captures text under a readable key, and the $matches array of preg_match() and preg_match_all() then contains both the name and the numeric index. Together with a handful of flags, named groups let you decide what the result array looks like, which is what this page is about.

PHP
<?php
preg_match('/(?<year>\d{4})-(?<month>\d{2})/', '2026-03', $m);
echo $m['year'], '/', $m['month'];

Named groups

Three spellings are accepted and mean the same: (?<name>โ€ฆ), (?P<name>โ€ฆ) and (?'name'โ€ฆ). Names start with a letter or underscore and contain letters, digits and underscores. In the result, the name key comes first, immediately followed by the numeric key of the same group. Refer back to a named group in the pattern with \k<name> or (?P=name).

PHP Named groups in the result

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.

Flags that shape the result

Flag Applies to Effect
PREG_PATTERN_ORDER preg_match_all Default. $m[0] holds all full matches, $m[1] all first groups, and so on.
PREG_SET_ORDER preg_match_all One array per match: $m[0] is the first match with all its groups. Best for looping.
PREG_OFFSET_CAPTURE preg_match, preg_match_all, callbacks Every entry becomes [text, byte offset]; unmatched groups give ["", -1].
PREG_UNMATCHED_AS_NULL all matching functions Groups that did not take part are null instead of "" or missing.

PREG_PATTERN_ORDER and PREG_SET_ORDER are mutually exclusive. You can combine the other flags with |.

PHP PREG_SET_ORDER and PREG_PATTERN_ORDER

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 PREG_OFFSET_CAPTURE and PREG_UNMATCHED_AS_NULL

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.

Usage notes

  • Trailing unmatched groups vanish. Without PREG_UNMATCHED_AS_NULL, an optional group at the end of the pattern that did not participate is missing from $matches, while one in the middle is an empty string. The flag makes the array shape predictable (and null is easy to test with ??).
  • Duplicate names are an error unless the J modifier or a branch reset (?|โ€ฆ) is used.
  • The numeric keys are still there. count($m) is twice the number of named groups plus one. Use array_filter($m, 'is_string', ARRAY_FILTER_USE_KEY) to keep only names.
  • preg_match() accepts PREG_OFFSET_CAPTURE and PREG_UNMATCHED_AS_NULL, but not the order flags. In preg_match_all() the default order is the pattern order.
  • Offsets are in bytes, even with /u. Convert with mb_strlen(substr($s, 0, $offset)) if you need characters.
  • With PREG_SET_ORDER and no match, $matches is an empty array and the function returns 0.
  • Rows with array_column(). A set-ordered result plugs straight into array_column() for lookup tables.
  • Callbacks in preg_replace_callback() receive the same shape as preg_match().