First occurrence

Matching a first occurrence in a string is the most common use-case.

Return from first()

You can get the first occurrence of a pattern in a subject by calling first().

pattern('[0-9]+')->match("I'm 19 years old")->first();
'19'

If a match is not found in a subject, SubjectNotMatchedException is thrown. This is done to relieve you from the brain strain. It's much easier to develop an application and just assume that this method has to return a value and go on. No more bothers about empty arrays and empty strings, or a possible null/false hiding somewhere.

If you would like to control the subject that isn't matched with your pattern though; you can do it explicitly with forFirst() (and orReturn(), orElse(), orThrow()).

Use first() with callback

You can call an anonymous function for the first matched occurrence. In this example, we'll print the matched text to the standard output.

pattern('\w+')->match("Apples are cool")->first(function (string $match) {
    echo 'I matched ' . $match;
});
I matched Apples

Casting Match to a string is the same as calling a text() method.

Match details

With Match details, you can gain access to useful information about the matched occurrence. 

pattern('\w+')->match("Apples are cool")->first(function (Match $match) {
    $subject = $match->subject();
    echo "Match '$match' was matched inside '$subject'.";
});
Match 'Apples' was matched inside 'Apples are cool'.

You can learn more about Match on Match details page.

Groups in match

Retrieving capturing groups from a match is really simple.

pattern('(?<capital>[A-Z])[a-z]+')->match('hello there, General Kenobi')->first(function (Match $match) {
    $capital = $match->group('capital')->text();
    
    return $capital;
});
'G'

Of course, first() callback will only be invoked if your pattern matches the subject.

You can learn more about groups on Capturing Group page.

Even more, you can visit Inline groups and use familiar all(), first(), only() and offsets() methods on groups.

Return value

It's also possible to return your custom value from within first() callback. This custom value will be then returned from first() function.

$first = pattern('\w+')->match('Apples are cool')->first(function (Match $match) {
    return [
        $match->text(), 
        strtoupper($match->text()),
        lcfirst($match->text())
    ];
});
return $first;
['Apples', 'APPLES', 'apples']

Variable callbacks

You can call first() for any valid PHP callable which accepts one string parameter (or no parameters).

return pattern('\w+')->match('Apples are cool')->first('strtoupper');
'APPLES'

In this example, Match will be cast to string, which is the same as calling Match.text() method.

Of course, strtoupper (or any other callback) is only invoked if your subject is matched with the pattern.

Arbitrary return types

From within first() callback, you can return any value:

return pattern('\w+')->match('Apples are cool')->first('str_split');
['A', 'p', 'p', 'l', 'e', 's']

The first() callback accepts all return types, including: numbers, objects, arrays, booleans and null:

$p = '(?<value>\d+)(?<unit>cm|mm)';
$s = '192mm and 168cm or 18mm and 12cm';
pattern($p)->match($s)->first();                 // '192mm'
pattern($p)->match($s)->first('str_split');      // ['1', '9', '2', 'm', 'm']
pattern($p)->match($s)->first('strlen')          // 5

forFirst()

This method allows you to explicitly specify how to handle an unmatched subject. Just chain forFirst() with one of the following orReturn(), orElse() or orThrow().

echo pattern('\w+')->match('Dog')
         ->forFirst(function (Match $match) {
             return "Yay $match";
         })
         ->orReturn('Aw, man :/');
Yay Dog

Read on to learn more about forFirst().

Last updated on