Pattern Matching with preg_match and preg_match_all in PHP

preg_match()

<?php
 //Syntax
 preg_match(
  string $pattern, string $subject, array &$matches = null,
  int $flags = 0, int $offset = 0
 ): int|false

The preg_match() function takes five parameters:

$pattern: The regular expression to search for.
$subject: The input string to search through.
&$matches (optional): An array to store any matched text in. The first element of the array will contain the text that matched the full pattern, the second element will have the text that matched the first subpattern (if captured), and so on. See example.
$flags (optional):
- PREG_OFFSET_CAPTURE: return the position of any match in the $matches array as well as the text matched. See example.
- PREG_UNMATCHED_AS_NULL: return NULL instead of empty string in the $matches array for any unmatched subpattern.
$offset (optional): Specify an offset number to start the search from that position in the $subject string instead of the first character. The first character has an offset of zero, the second character has an offset of 1, and so on. See example.

The preg_match() function only finds the first match within the string, it returns 1 if the pattern matches the given subject, 0 if it does not, or FALSE on failure. This function may return Boolean false, so always use the === operator for testing the return value of this function.

Example: Find if a word exists (anywhere) in the string:

Note: Use regular expressions for complex pattern matching only, for a simple match like this, use str_contains() or str_pos() function.

<?php
 $string = 'Free PHP tutorials on BrainBell.com';
 $match = preg_match ('/tutorials/', $string);
 if ($match === false)
  die ('Failed');
 if ($match === 1)
  echo 'Match found';
 else
  echo 'Match not found';

Example: Find if a string starts or ends with a specified word:

The anchors ^ and $ match the start and end of the string respectively.

<?php
 $string = 'Free PHP tutorials on BrainBell.com';
 //String does not starts with 'tuttorial'
 echo preg_match ('/^tutorials/', $string);
 #Prints: 0

 //String starts with 'Free'
 echo preg_match ('/^Free/', $string);
 #Prints: 1

 //String ends with 'com'
 echo preg_match ('/com$/', $string);
 #Prints: 1

Example: Using the third parameter ($matches) to store matched text

<?php
 $string = 'Words: force, file, fake, fire';
 $m = preg_match ('/f.*?e/', $string, $matches);
 echo $matches[0]; //Prints: force
 print_r($matches);
 /* Array (
    [0] => force
) */

Note: The preg_match() function finds only the first match, use the preg_match_all() function if you need to find all the matches in a string.

Example: Capture subpatterns

The $matches[0] contains the text that matched the full pattern, and $matches[1] contains the text that matched the first captured parenthesized subpattern.

<?php
 $string = 'Words: force, file, fake, fire';
 $m = preg_match ('/f(.*?)e/', $string, $matches);
 echo $matches[0]; //Prints: force
 print_r($matches);
 /* Array (
    [0] => force #Whole pattern
    [1] => orc   #Subpattern
) */

Example: Using the fourth parameter ($flags) to find the position of matched text in the string

To find out the position of the match in the string, pass PREG_OFFSET_CAPTURE flag in the fourth parameter.

<?php
 #          01234567
 $string = 'Words: force, file, fake, fire';
 $m = preg_match ('/f.*?e/', $string, $matches, PREG_OFFSET_CAPTURE);
 echo $matches[0][0]; //Prints: force
 print_r($matches);
 /*Array (
  [0] => Array (
        [0] => force
        [1] => 7
     )
)*/

Example: Using the fifth ($offset) parameter to start the search from a specific position in the input string

<?php
 $string = 'Words: force, file, fake, fire';
 $m = preg_match ('/f.*?e/', $string, $matches,
                  PREG_OFFSET_CAPTURE, 15);
 echo $matches[0][0]; //Prints: fake
 print_r($matches);
 /*Array (
  [0] => Array (
        [0] => fake
        [1] => 20
     )
  )*/

 # use 0 to disable the flag parameter
 $m = preg_match ('/f.*?e/', $string, $matches,
                  0, 15);
 print_r($matches);
/* Array(
    [0] => fake
) */

preg_match_all()

<?php
 //Syntax
 preg_match_all(
  string $pattern, string $subject, array &$matches = null,
  int $flags = 0, int $offset = 0
 ): int|false

The preg_match_all() function takes five parameters:

$pattern: The regular expression to search for.
$subject: The input string to search through.
&$matches (optional): A multi-dimensional array to store all matched text based on the $flags parameter value.
$flags (optional): This parameter controls the structure of $matches array. default flag is PREG_PATTERN_ORDER
- PREG_PATTERN_ORDER: This flag set the order of results so that $matches[0] is an array of full pattern matches, $matches[1] is an array of strings matched by the first subpattern, and so on.
- PREG_SET_ORDER: This flag set the order of results so that $matches[0] is an array of the first set of matches, $matches[1] is an array of the second set of matches, and so on.
- PREG_OFFSET_CAPTURE: return the position of any match in the $matches array as well as the text matched.
- PREG_UNMATCHED_AS_NULL: return NULL instead of empty string in the $matches array for any unmatched subpattern.
$offset (optional): Specify an offset number to start the search from that position in the $subject string instead of the first character. The first character has an offset of zero, the second character has an offset of 1, and so on.

The preg_match_all() function finds all the matches in the input string and returns the number of matches as an integer or false on failure. This function works similar to the preg_match().

Example: Finding Multiple Matches with preg_match_all()

By default preg_match_all() uses the PREG_PATTERN_ORDER flag:

<?php
 $string = 'Words: force, file, fake, fire';
 $m = preg_match_all ('/f.*?e/', $string, $matches);
 echo $m; // Prints: 4
 print_r($matches);
 /*Array (
    [0] => Array (
         [0] => force
         [1] => file
         [2] => fake
         [3] => fire)
 )*/

Example: Using PREG_SET_ORDER flag

<?php
 $string = 'Words: force, file, fake, fire';
 $m = preg_match_all ('/f.*?e/', $string, $matches, PREG_SET_ORDER);
 echo $m; // Prints: 4
 print_r($matches);
 /*Array(
    [0] => Array(
            [0] => force
        )
    [1] => Array(
            [0] => file
        )
    [2] => Array(
            [0] => fake
        )
    [3] => Array(
            [0] => fire
        )
  )*/

More Regular Expressions Tutorials: