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|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:
`<?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 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
:
`<?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?