Perform a regular expression match

preg_match_all
preg_quote
PCRE Functions
PHP Manual

# preg_match

(PHP 4, PHP 5)

preg_match — Perform a regular expression match

### Description

int preg_match ( string `$pattern` , string `$subject` [, array `&$matches` [, int `$flags` [, int `$offset` ]]] )

Searches `subject` for a match to the regular expression given in `pattern`.

### Parameters

`pattern`

  The pattern to search for, as a string.

`subject`

  The input string.

`matches`

  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`

  `flags` can be the following flag:

  `PREG_OFFSET_CAPTURE`
    If this flag is passed, for every occurring match the appendant string offset will also be returned. Note that this changes the value of `matches` into 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.
`offset`

  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 (in bytes).

  > Note: Using `offset` is not equivalent to passing substr($subject, $offset) to preg_match() in place of the subject string, because `pattern` 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
  >             )

  >     )

### Return Values

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.

### Changelog

Version | Description
--- | ---
5.2.2 | Named subpatterns now accept the syntax (?<name>) and (?'name') as well as (?P<name>). Previous versions accepted only (?P<name>).
4.3.3 | The `offset` parameter was added
4.3.0 | The `PREG_OFFSET_CAPTURE` flag was added
4.3.0 | The `flags` parameter was added

### Examples

Example #1 Find the string of text "php"

`<?php
// The "i" after the pattern delimiter indicates a case-insensitive search
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
echo "A match was found.";
} else {
echo "A match was not found.";
}
?>`

Example #2 Find the word "web"

`<?php
/* The \b in the pattern indicates a word boundary, so only the distinct
* word "web" is matched, and not a word partial like "webbing" or "cobweb" */
if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
echo "A match was found.";
} else {
echo "A match was not found.";
}
if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
echo "A match was found.";
} else {
echo "A match was not found.";
}
?>`

Example #3 Getting the domain name out of a URL

`<?php
// get host name from URL
preg_match('@^(?:http://)?([^/]+)@i',
"http://www.php.net/index.html", $matches);
$host = $matches[1];
// get last two segments of host name
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "domain name is: {$matches[0]}\n";
?>`

The above example will output:

    domain name is: php.net

Example #4 Using named subpattern

`<?php
$str = 'foobar: 2008';
preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
/* This also works in PHP 5.2.2 (PCRE 7.0) and later, however
* the above form is recommended for backwards compatibility */
// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);
print_r($matches);
?>`

The above example will output:

    Array
    (
        [0] => foobar: 2008
        [name] => foobar
        [1] => foobar
        [digit] => 2008
        [2] => 2008
    )

### Notes

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.

### See Also

- preg_match_all() - Perform a global regular expression match
- preg_replace() - Perform a regular expression search and replace
- preg_split() - Split string by a regular expression
- preg_last_error() - Returns the error code of the last PCRE regex execution

preg_match_all
preg_quote
PCRE Functions
PHP Manual