PHP Preg_Match() Function - Search A String For Pattern With Regular Expression Match

Let’s take a look at how we can use the preg_match() function to perform a regular expression pattern match on an input string. We’ll walk through various implementations and examples that show the extension of this php function. 

PHP Preg_Match Function Introduction & Syntax

The PHP preg_match() function is a built-in regex style function that is used to search a given string for regular expression pattern matches given in the $pattern variable. The function returns 1 or True if the pattern is found in the string or 0 if it does not. The function can also return false on failure. 

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

Parameters For Preg_Replace() Function:

The first two parameters are not optional and should be strings. $Matches is a useful optional variable that will return the matches found in the string. 

Pattern

The regex style string to search for in the given subject. This parameter is not optional. 

Subject

The input string to perform a regular expression search on. This parameter is not optional. 

Matches

The matches variable can be passed in as an optional parameter and filled with the results of the preg_match() search. The matches variable will be an array value where $matches[0] holds the text that matched the pattern, and $matches[i] will have text that matches any parenthesized subpatterns from the regex style search. The “i” itterates up as you have more parenthesized subpatterns. 

preg_match('/(mat)(noh)(lev)/', 
						'matnohlev', 
             $matches, 
             PREG_OFFSET_CAPTURE);
print_r($matches);

‍

The output from the above preg_match would look like this.

Array(    

			[0] => Array(
      		[0] => matnohlev
          [1] => 0
          )
      [1] => Array(
      		[0] => mat
          [1] => 0
          )
      [2] => Array(
      		[0] => noh
          [1] => 3
          )    
      [3] => Array(
      		[0] => lev
          [1] => 6
          )
)

Flags 

An optional fourth parameter that allows you to use a number of different flags to define function operation. 

PREG_OFFSET_CAPTURE

This flag allows you to also return the appendant string offset for each match alongside the given match in the $matches variable. This does mean we’ve now changed the return value of $matches to an array where every element is an array with the found match string at an offset value of 0 and its string offset into $subject at an offset value of 1. The above example shows what this looks like with the nested array return. 

PREG_UNMATCHED_AS_NULL

This flag allows you to return unmatched sub patterns as null instead of an empty string in the $matches variable. This is pretty useful as an empty string can lead to unstable workflows. 

preg_match('/(x)(y)*(z)/', 'xz', $matches);
print_r($matches);

preg_match('/(x)(y)*(z)/', 'xz', $matches, PREG_UNMATCHED_AS_NULL);
print_r($matches);

The result from these two preg_match() function runs looks like this:

array(4) {  
	[0]=>  string(2) "xz"  
	[1]=>  string(1) "x"  
	[2]=>  string(0) ""  
	[3]=>  string(1) "z"} 
      
array(4) {  
	[0]=>  string(2) "xz"  
	[1]=>  string(1) "x"  
	[2]=>  NULL  
	[3]=>  string(1) "z"}
     

Offset (Optional Parameter Offset)

The optional parameter offset allows you to start the search from a place other than the default beginning of the subject string. This variable is a byte value that lets you define this new starting location. 

Return Values For Preg_Match() Function:

The function returns either an integer 1 value if the pattern matches the passed in subject variable and a 0 if it does not. The function will also return False on a failure to run the function. 

While this function returns a boolean value false on failure, it may also return a non-boolean value that evaluates to false. It’s recommended that you use the === operator to test the return value you get from preg_match(). 

Errors & Exceptions

This function will produce an E_WARNING if the pattern used in $pattern is not a valid regex pattern. 

Quick Notes About The Preg_Match() Function:

The function was added in PHP 4.0.

PHP 5.3.6 the function returns false when the optional parameter $offset is longer than the length of the input.    

PHP version 7.2.0 added the PREG_UNMATCHED_AS_NULL to the $flags parameter. 

If you’re just looking to check if a string contains another string it’s much better to use strpos() instead given the runtimes. 

The optional offset parameter is not equivalent to passing the function substr($subject, $offset) as the subject string into this function. The reason is the $pattern parameter can contain regex characters such as “^, $ or (?<=x)”. Here’s a few examples to clear this up:

$subject = "cbcmat";
$pattern = '/^mat/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);

print_r($matches);

This sets the $matches variable to an empty array. You can see we’ve used 3 for our offset.

$subject = "cbcmat";
$pattern = '/^mat/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);print_r($matches);

This example that passes a substr in with the subject produces the following array:

Array(    
		[0] => Array (
		[0] => mat   
		[1] => 0
    )
)

PHP Preg_Match() Examples:

Let’s look at a number of examples of how we can use preg_match() to regex style search strings. 

Simple Preg_Match() PHP String Matching Examples:

This code example performs regex string matching on  

$biz = 'Widthdotai';
// Display matches
preg_match('/(Width)(dot)(ai)/', $biz, $matches, PREG_OFFSET_CAPTURE);
resultprint_r($matches);

‍

The result is an array with four elements. The first element is the entire string that is found “widthdotai” and the last three elements are each of the sub patterns we defined between parenthesis. You can get the matched string via [0] in each element and [1] gets you the character where the pattern starts via the flag PREG_OFFSET_CAPTURE. 

The following code snippet does not contain a $matches variable and just returns a 1 or a 0. 

$str = "Visit Width.ai";
$pattern = "/width.ai/i";
echo preg_match($pattern, $str);

PHP Preg_Match Case Insensitive Matching With Regex

This example below uses the preg_match() function with a case insensitive search pattern to find matches.  

$gfg = "SIMAL is the best GPT-3 Platform."; 

if (preg_match("/\bsimal\b/i", $gfg, $match))     
	echo "Found!";
else    
	echo "not found";      

Notice the pattern string contains “i” to allow for case insensitive.

The output from this code snippet is ‘Found!’.  

Deeper Examples Of Preg_Match() In PHP

Let’s look at some extremely effective ways to use the preg_match() function to search strings with regex patterns. 

Extract Domain Name From Url as Input String

This function extracts the main domain name from a url with lots of information around it. This is a pretty useful functionality for when you’re building data services in workflow pipelines or information extraction tools. 

 
preg_match('@^(?:https://)?([^/]+)@i', 
						"https://www.width.net/index.html", 
            $matches);
$host = $matches[1];

preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "domain name is: {$matches[0]}\n";

The result of this function is “domain name is: width.net”. The first section grabs the host name from the matched string and the second section gets the last two terms of the domain name. 

Validate Directories on Windows OS With Regular Expression

Pretty cool example taken from this comment on the php documentation. 

if( preg_match("#^([a-z]{1}\:{1})?[\\\/]?([\-\w]+[\\\/]?)*$#i",$_GET['path'],$matches) !== 1 ){    
	echo("Invalid value");}
  
else{    
	echo("Valid value");
}

Quite a bit of regex wrapped in an if statement that checks the integer return value. The input string can contain a slash “\” or “/” after the driver letter but it is not required. The driver letter and colon must be in the standard format (C:) and cannot contain multiple of either. The string directory can contain a slash at the end of the directory like “Documents/” but does not have to “Documents”. 

Is There A $Subject String Size Limit? 

There is a default subject string size limit and the function will raise a warning “[PhpWarning] preg_match(): Subject is too long”. You can set the string size limit to anything by adding 

More Preg_Match() PHP Information

Preg_Match() Vs Preg_Match_All()

The “all” version of this function performs a global regular expression match on an input $subject string. This function will also return the number of matches of a pattern that were found. 

PCRE Constraints

There are times where your function fails because of PCRE constraints. This can be caused by matching strings that are extremely large or with poor encoding. You can check if your preg_match() function call worked by calling preg_last_error(). This function returns a PREG_NO_ERROR code when your regular expressions work fine and an error code like PREG_INTERNAL_ERROR if an error occurred. 

Summary

The preg_match() php function is a great way to use regular expression style patterns on strings in php and extract the patterns with key information such as location and pattern existence. This function is also great to perform tasks like split strings and validate different input strings.