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:

• $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 and PREG_UNMATCHED_AS_NULL. More on these flags in the example below.
• $offset is the position that the function will start searching. By default, the preg_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:

<?php

$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:

<?php

$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:

<?php

$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:

<?php

$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:

<?php

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

<?php

$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:

<?php

$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:

<?php

$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:

<?php

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