PHP preg_match
Summary: in this tutorial, you’ll learn about the PHP preg_match() function to match a regular expression.
Introduction to the PHP preg_match() function
The preg_match() finds the string for a match to a regular expression. The preg_match() function stops searching as long as it finds the first match.
Here’s the syntax of the preg_match() function:
preg_match(
string $pattern,
string $subject,
array &$matches = null,
int $flags = 0,
int $offset = 0
): int|falseCode language: PHP (php)
The preg_match() function accepts the following parameters:
$patterna string that specifies a pattern to search.$subjectis an input string.$matchesis an array that stores the search results. The$matchesarray is optional. If there is a match, the$matches[0]will contain the text that matches the whole pattern,$matches[1]will contain the text that matches the first capturing group, and so on.$flagsis a combination of the following flags:PREG_OFFSET_CAPTUREandPREG_UNMATCHED_AS_NULL. More on these flags in the example below.$offsetis the position that the function will start searching. By default, thepreg_match()starts searching from the beginning of the string. Note that the$offsetis in bytes.
The preg_match() function returns 1 if it finds a match,0 if it doesn’t, or false on failure.
PHP preg_match() function examples
Let’s take some examples of using the preg_match() function.
1) Using the PHP preg_match() to match a number
The following example uses the preg_match() to match a number with one or more digits using the \d+ character class:
$pattern = '/\d+/';
$str = 'PHP first released in 8 June 1995';
if (preg_match($pattern, $str, $matches)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => 8
)Code language: PHP (php)
Note that the preg_match() stops searching as soon as it finds a match. In this example, 1995 also matches the pattern \d+. However, the preg_match() already finds a match with the number 8.
To find all the matches, you need to use the preg_match_all() function.
2) Using the PHP preg_match() to match a word character
The following example uses the preg_match() function to match one or more word characters:
$pattern = '/\w+/';
$str = 'PHP first released in 8 June 1995';
if (preg_match($pattern, $str, $matches)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => PHP
)Code language: PHP (php)
3) Using the PHP preg_match() with a capturing group example
The following example uses the preg_match() function to match a number that starts with 19 and is followed by exactly two digits. The pattern also has a capturing group that captures the last two digits:
$pattern = '/19(\d{2})/';
$str = 'PHP first released in 8 June 1995';
if (preg_match($pattern, $str, $matches)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => 1995
[1] => 95
)Code language: PHP (php)
The $matches array contains two elements. The first element contains the text that matches the whole pattern, while the second element contains the first capturing group (\d{2}).
The following example uses the same pattern with the additional named capturing group:
$pattern = '/19(?<year>\d{2})/';
$str = 'PHP first released in 8 June 1995';
if (preg_match($pattern, $str, $matches)) {
print_r($matches);
}
Code language: PHP (php)
Output:
(
[0] => 1995
[year] => 95
[1] => 95
)Code language: PHP (php)
4) Using the PHP preg_match() function with the PREG_OFFSET_CAPTURE flag
Sometimes, you want to find a match in a string and the starting position of the match. To do that, you use the PREG_OFFSET_CAPTURE flag. For example:
$pattern = '/[A-Z]{3}/';
$str = 'Hello PHP';
if (preg_match($pattern, $str, $matches, PREG_OFFSET_CAPTURE)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => Array
(
[0] => PHP
[1] => 6
)
)Code language: PHP (php)
In this example, the [A-Z]{3} pattern matches any text with three letters in uppercase. Since we use the PREG_OFFSET_CAPTURE flag, it returns the match (PHP) and the starting position (or offset) of the text PHP in the string.
5) Using the preg_match() function with the PREG_UNMATCHED_AS_NULL flag
By default, the preg_match() function returns an empty string for the unmatched capturing group (or subpattern).
If you want the preg_match() function to return null instead, you can use the PREG_UNMATCHED_AS_NULL flag.
The following example uses the preg_match() function without the PREG_UNMATCHED_AS_NULL flag.
$pattern = '/[A-Z]{3}(\s*)(\d+.\d*.\d*)*/';
$str = 'Hello PHP 8.0.1';
if (preg_match($pattern, $str, $matches)) {
var_dump($matches);
}
Code language: PHP (php)
Output:
array(3) {
[0]=> string(9) "PHP 8.0.1"
[1]=> string(1) " "
[2]=> string(5) "8.0.1"
}Code language: PHP (php)
In this example, the string has the text that matches the subpatterns (\s*)(\d+.\d*.\d\*).
However, in the following example, the string doesn’t have a text that matches the subpattern:
$pattern = '/[A-Z]{3}(\s*)(\d+.\d*.\d*)*/';
$str = 'Hello PHP';
if (preg_match($pattern, $str, $matches)) {
var_dump($matches);
}
Code language: PHP (php)
Output:
array(2) {
[0]=> string(3) "PHP"
[1]=> string(0) ""
}Code language: PHP (php)
The string doesn’t have any text that matches the (\s\*) subpattern, the preg_match() returns an empty string.
Since we use the PREG_UNMATCHED_AS_NULL flag, the preg_match() function returns null for the unmatched subpattern instead.
The following example uses the PREG_UNMATCHED_AS_NULL flag. So it returns NULL instead of an empty string for the unmatched subpattern:
$pattern = '/[A-Z]{3}(\s*)(\d+.\d*.\d*)*/';
$str = 'Hello PHP';
if (preg_match($pattern, $str, $matches, PREG_UNMATCHED_AS_NULL)) {
var_dump($matches);
}
Code language: PHP (php)
Output:
array(2) {
[0]=> string(3) "PHP"
[1]=> NULL
}Code language: PHP (php)
6) Using the php preg_match() with the offset parameter
Suppose that you have the following string:
PHP 1.0 released in 1995Code language: PHP (php)
If you use the \d+, it’ll match the first number, which is 1.
However, if you pass an offset parameter that specifies the starting position to search, it’ll match the second number 1995:
$pattern = '/\d+/';
$str = ' PHP 1.0 released in 1995';
if(preg_match($pattern, $str,$matches, PREG_OFFSET_CAPTURE, 10)) {
print_r($matches);
}
Code language: PHP (php)
Output:
Array
(
[0] => Array
(
[0] => 1995
[1] => 21
)
)Code language: PHP (php)
In this example, the preg_match() function starts searching for matches from position ten instead of 0.
Notice that the pattern may contain assertions like ^, $, or (?<=A). Therefore, the offset is not equivalent to passing the substring to the preg_match() function.
Summary
- Use the PHP
preg_match()function to search for a match with a pattern in a string.