PREG_MATCH(3)								 1							     PREG_MATCH(3)

preg_match - Perform a regular expression match

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS

	      o $pattern
		- The pattern to search for, as a string.

	      o $subject
		- The input string.

	      o $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.

	      o $flags
		-$flags can be the following flag:

		     o 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.

	      o $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(3) 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(3) returns 1 if the $pattern matches given $subject, 0 if it does not, or FALSE if an error occurred.

       Warning

	      This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE. Please read the section on
	      Booleans for more information. Use the === operator for testing the return value of this function.

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>).	    |
       |	|						    |
       +--------+---------------------------------------------------+
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  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("/web/i", "PHP is the web scripting language of choice.")) {
		  echo "A match was found.";
	      } else {
		  echo "A match was not found.";
	      }

	      if (preg_match("/web/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]}
";
	      ?>

	      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(3) if you only want to check if one string is contained in another string. Use strpos(3) or strstr(3) instead
	      as they will be faster.

SEE ALSO

       PCRE Patterns, preg_quote(3), preg_match_all(3), preg_replace(3), preg_split(3), preg_last_error(3).

PHP Documentation Group 													     PREG_MATCH(3)