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 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).
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 |.
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.
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 (andnullis easy to test with??). - Duplicate names are an error unless the
Jmodifier or a branch reset(?|โฆ)is used. - The numeric keys are still there.
count($m)is twice the number of named groups plus one. Usearray_filter($m, 'is_string', ARRAY_FILTER_USE_KEY)to keep only names. preg_match()acceptsPREG_OFFSET_CAPTUREandPREG_UNMATCHED_AS_NULL, but not the order flags. Inpreg_match_all()the default order is the pattern order.- Offsets are in bytes, even with
/u. Convert withmb_strlen(substr($s, 0, $offset))if you need characters. - With
PREG_SET_ORDERand no match,$matchesis an empty array and the function returns0. - Rows with
array_column(). A set-ordered result plugs straight intoarray_column()for lookup tables. - Callbacks in
preg_replace_callback()receive the same shape aspreg_match().