Searches subject
for a match to the regular
expression given in pattern
.
If matches
is provided, then it is filled with the
results of search. $matches[0]
will contain the text
that matched the full pattern, $matches[1]
will have
the text that matched the first captured parenthesized subpattern, and so
on.
flags
can be the following flag:
If this flag is passed, for every occurring match the appendant string
offset will also be returned. Note that this changes the return value
in an array where every element is an array consisting of the matched
string at offset 0 and its string offset into
subject
at offset 1. This
flag is available since PHP 4.3.0 .
flags
parameter is available since
PHP 4.3.0.
Normally, the search starts from the beginning of the subject string. The
optional parameter offset
can be used to specify
the alternate place from which to start the search.
The offset
parameter is available since
PHP 4.3.3.
Note: Using
offset
is not equivalent to passing substr($subject, $offset) to preg_match() in place of the subject string, becausepattern
can contain assertions such as ^, $ or (?<=x). Compare:
<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);
?>The above example will output:
Array ( )while this example
<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>will produce
Array ( [0] => Array ( [0] => def [1] => 0 ) )
preg_match() returns the number of times
pattern
matches. That will be either 0 times
(no match) or 1 time because preg_match() will stop
searching after the first match. preg_match_all()
on the contrary will continue until it reaches the end of
subject
.
preg_match() returns FALSE if an error occurred.
Tip: Do not use preg_match() if you only want to check if one string is contained in another string. Use strpos() or strstr() instead as they will be faster.
Example 3. Getting the domain name out of a URL
The above example will output:
|
See also preg_match_all(), preg_replace(), and preg_split().