preg_match()

preg_match() — Perform a regular expression match.

Built-in function of PHP 8.5. The manual lists it as available in PHP 4, PHP 5, PHP 7, PHP 8. This page is the reference card: signature, parameters and return value, plus the changelog and the example the manual provides.

What it does

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

Signature

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

Parameters

Parameter	Type	What it takes
$pattern	string	The pattern to search for, as a string.
$subject	string	The input string.
&$matches	array	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	int	flags can be a combination of the following flags: PREG_OFFSET_CAPTURE If this flag is passed, for every occurring match the appendant string offset (in bytes) 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. <?php preg_match('/(foo)(bar)(baz)/', 'foobarbaz' ...
$offset	int	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).

Return value

preg_match() returns 1 if the pattern matches given subject, 0 if it does not, or false on failure. Matching also fails, and false is returned, when the pcre.backtrack_limit or pcre.recursion_limit is reached, which can happen with a long subject. Use preg_last_error() to find out the reason. 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.

Example

A runnable snippet:

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

Changelog

Version	Change
7.4.0	When the PREG_UNMATCHED_AS_NULL flag is used, trailing unmatched capturing groups are now also included in the result with the value null (or [null, -1] when PREG_OFFSET_CAPTURE is also used), so that $matches always has the same size. Previously, they were omitted.
7.2.0	The PREG_UNMATCHED_AS_NULL is now supported for the flags parameter.