mb_ereg_search_getregs()

Purpose

mb_ereg_search_getregs() reads the result of the most recent multibyte regular expression search. It belongs to the stateful mb_ereg_search* family: you give PHP a subject string and a pattern once, then step through the string match by match. After a successful search, this function returns the full matched text together with every captured group.

It is useful when you ran a search with mb_ereg_search() (which only reports success or failure) or mb_ereg_search_pos() (which reports positions) and now also want the matched substrings. mb_ereg_search_regs() returns the same kind of array directly, so getregs is the "fetch it again later" companion.

Signature

Parameters and defaults

The function takes no parameters. Everything it needs comes from internal state set up by earlier calls:

• the subject string and pattern from mb_ereg_search_init();
• the current search position, which advances after each successful search;
• the regex encoding, which is the internal encoding unless you changed it with mb_regex_encoding().

Because the state is global to the request, set the encoding explicitly in code you want to be predictable.

Return value and failure cases

On success you get a list array. Index 0 holds the whole matched substring, index 1 the first parenthesized group, index 2 the second, and so on.

The function returns false when there is no usable result, for example when no search string has been set up yet. A group that did not take part in the match (such as an optional group that was skipped) appears as false in its slot rather than an empty string.

Note that a failed search does not give you a meaningful "last match" to inspect. Check the return value of the search call itself before fetching registers.

Example 1: matched text and groups

Set up the string and pattern, run one search, then read the registers.

<?php
mb_regex_encoding('UTF-8');
mb_ereg_search_init('order abc-123 and def-456', '([a-z]+)-([0-9]+)');
if (mb_ereg_search()) {
    echo json_encode(mb_ereg_search_getregs(), JSON_UNESCAPED_SLASHES), "\n";
}

["abc-123","abc","123"]

Only the first match is reported, because the search runs once. Index 0 is the whole match and the next two entries are the groups.

Example 2: walking through multibyte matches

Each successful mb_ereg_search() moves the position forward, so a while loop visits every match. Fetching the registers inside the loop gives you the groups for the current match.

<?php
mb_regex_encoding('UTF-8');
mb_ereg_search_init('größe=12;höhe=7', '(\w+)=(\d+)');
$pairs = [];
while (mb_ereg_search()) {
    $regs = mb_ereg_search_getregs();
    $pairs[$regs[1]] = (int) $regs[2];
}
echo json_encode($pairs, JSON_UNESCAPED_UNICODE), "\n";

{"größe":12,"höhe":7}

The words contain non-ASCII letters, and the multibyte engine treats them as word characters, so the keys come out intact.

Example 3: no result yet, and unmatched groups

Before any search has been prepared there is nothing to return, so the function gives false. After a search, an optional group that did not participate shows up as false.

<?php
mb_regex_encoding('UTF-8');
var_dump(mb_ereg_search_getregs());
mb_ereg_search_init('ab', '(a)(x)?b');
if (mb_ereg_search()) {
    echo json_encode(mb_ereg_search_getregs()), "\n";
}

bool(false)
["ab","a",false]

Edge cases

• Skipped groups: a non-participating group yields false, not "". If you concatenate or compare results, handle that explicitly.
• State is shared: another mb_ereg_search_init() call replaces the subject and resets the position, so read the registers before starting a different search.
• Position advances: calling the search function again moves on to the next match; getregs itself never moves the position.
• Encoding: the regex encoding decides how bytes are interpreted. A mismatch between the string's real encoding and the configured one can give wrong or failed matches.

Common mistakes

1. Calling it after a failed search. When mb_ereg_search() returns false, stop; do not rely on the registers.
2. Expecting arguments. The function takes none. Pass the pattern to mb_ereg_search_init() or to the search call.
3. Assuming empty strings for optional groups. Test with === false when a group may be skipped.
4. Mixing it with the non-stateful mb_ereg(). That function fills its own output array and does not need getregs.
5. Forgetting to set the encoding. Relying on whatever the environment has configured makes behavior harder to reason about.

Related functions

• mb_ereg_search_init() sets the subject string and optional pattern.
• mb_ereg_search() runs a search and returns a boolean.
• mb_ereg_search_pos() returns the byte position and length of a match.
• mb_ereg_search_regs() searches and returns the registers in one call.
• mb_regex_encoding() gets or sets the regex character encoding.

Recap

mb_ereg_search_getregs() is a parameterless accessor for the last multibyte regex search: an array of the full match followed by each captured group, or false when there is no result. Use it inside a search loop, check the search call first, and remember that skipped groups appear as false.