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|false
Code language: PHP (php)
The preg_match()
function accepts the following parameters:
$pattern
a string that specifies a pattern to search.$subject
is an input string.$matches
is an array that stores the search results. The$matches
array 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.$flags
is a combination of the following flags:PREG_OFFSET_CAPTURE
andPREG_UNMATCHED_AS_NULL
. More on these flags in the example below.$offset
is the position that the function will start searching. By default, thepreg_match()
starts searching from the beginning of the string. Note that the$offset
is 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 1995
Code 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.