Skip to main content

First occurrence

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

About 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.

note

If you would like to control the subject that isn't matched with your pattern though; you can do it explicitly with findFirst() (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
note

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

Match details#

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

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

You can read more extensively about it on Detail page.

Groups in match#

Retrieving capturing groups from a match is really simple.

pattern('(?<capital>[A-Z])')->match('hello there, General Kenobi')->first(function (Detail $detail) {
return $detail->get('capital');
});
'G'

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

note

You can learn more about groups on Capturing Group page.

note

Even more, you can visit Inline groups and use 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 (Detail $detail) {
return [
$detail->text(),
strtoupper($detail->text()),
lcfirst($detail->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, Detail will be cast to string, which is the same as calling Detail.text() method.

note

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:

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

findFirst()#

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

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

Read on to learn more about findFirst().

Last updated on