preg_match

Perform a regular expression match

&reftitle.description; `int` `preg_match` `string` `pattern` `string` `subject` `array` `matches` `int` `flags` 0 `int` `offset` 0

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

&reftitle.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).

  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);
      ?>

  &example.outputs;

      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
              )

      )

&reftitle.returnvalues;

`preg_match` returns 1 if the `pattern` matches given `subject`, 0 if it does not, or &false; if an error occurred.

&return.falseproblem;
&reftitle.changelog;

&Version; | &Description;
5.3.6 | Returns &false; if `offset` is higher than `subject` length.
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

&reftitle.examples;

### 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.";
    }
    ?>

### 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.";
    }
    ?>

### 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";
    ?>

&example.outputs;

    domain name is: php.net

### 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);

    ?>

&example.outputs;

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

&reftitle.notes;

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.

&reftitle.seealso;

- PCRE Patterns
- `preg_match_all`
- `preg_replace`
- `preg_split`
- `preg_last_error`