PHP preg_match (original) (raw)

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,str, 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,str, 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,str, 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(?\d{2})/'; $str = 'PHP first released in 8 June 1995';

if (preg_match($pattern, str,str, 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,str, 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,str, 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,str, 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,str, 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,str,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.

Did you find this tutorial useful?