PHP preg_match_all() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Regex

Definition

In PHP, preg_match_all() finds every match of a regular expression in a string and stores them in $matches.

It returns the number of full matches, or false on error. By default (PREG_PATTERN_ORDER) $matches[0] holds all full matches, $matches[1] all of group 1, and so on. With PREG_SET_ORDER, each $matches[n] is one match with its groups.

Syntax

Call preg_match_all() with the values you need. Start with this line.

PHP
$n = preg_match_all('/\w+/', $text, $matches);
CallWhat it does
preg_match_all('/\d+/', 'a1 b22')Returns 2 and can fill $matches with "1" and "22".
preg_match_all('/(\w+)@(\w+)/', $s, $m)Fills full matches and each capturing group for every hit.
preg_match_all($p, $s, $m, PREG_SET_ORDER)Groups each match as its own array row.

PREG_PATTERN_ORDER (default) is handy when you want one column per group. PREG_SET_ORDER is handy when you loop match-by-match as a set of fields.

Library declarations
PHP
preg_match_all(string $pattern, string $subject, array &$matches = null, int $flags = 0, int $offset = 0): int|false

Parameters

ParameterDescription
patternRequired. PCRE pattern with delimiters and optional flags.
subjectRequired. The string to search.
matchesOptional. Passed by reference. Receives all matches, shaped by $flags.
flagsOptional. PREG_PATTERN_ORDER (default), PREG_SET_ORDER, and/or PREG_OFFSET_CAPTURE.
offsetOptional. Byte offset to start searching. Default 0.

Return Value

Return ValueDescription
int|falseThe number of full matches found, or false on failure.

PHP Examples

Example 1 — Collect Every Digit Run

Find all numbers in a short string and print the count.

PHP
<?php
$count = preg_match_all('/\d+/', 'a1 b22 c3', $matches);
echo $count, PHP_EOL;
print_r($matches[0]);

How It Works

  1. The pattern /\d+/ matches one or more digits.
  2. preg_match_all() walks the whole string, not just the first hit.
  3. The return value 3 is the number of full matches.
  4. $matches[0] lists each full match: 1, 22 and 3.

Example 2 — PREG_PATTERN_ORDER Versus PREG_SET_ORDER

Compare how capturing groups are arranged with the two common flags.

PHP
<?php
$text = 'a@x b@y';

preg_match_all('/(\\w+)@(\\w+)/', $text, $byPattern);
print_r($byPattern);

preg_match_all('/(\\w+)@(\\w+)/', $text, $bySet, PREG_SET_ORDER);
print_r($bySet);

How It Works

  1. Default PREG_PATTERN_ORDER stores full matches in [0], all group 1 values in [1], and all group 2 values in [2].
  2. That layout is column-oriented: one array per group.
  3. PREG_SET_ORDER stores one array per match: full text, then group 1, then group 2.
  4. Use SET_ORDER when each match is a small record you want to loop over.

Example 3 — Count Words with a Simple Pattern

Use preg_match_all() as a counter for word-like tokens.

PHP
<?php
$line = 'red green blue';
$n = preg_match_all('/[a-z]+/', $line, $m);
echo 'words: ', $n, PHP_EOL;
echo implode(',', $m[0]), PHP_EOL;

How It Works

  1. The pattern /[a-z]+/ matches runs of lowercase letters.
  2. Three words are found in the line.
  3. $m[0] holds red, green and blue.
  4. implode() joins them for a quick display.

Frequently Asked Questions

It finds every match of a pattern in a string, stores them in $matches, and returns how many full matches were found.
The default layout. $matches[0] is all full matches, $matches[1] is every capture of group 1, and so on.
Each $matches[n] is one match: index 0 is the full match, index 1 is group 1, index 2 is group 2, and so on.
When you only need to know if something matches once, or you only need the first match. preg_match() is simpler and stops early.
An error occurred. That is not the same as 0 matches. Check preg_last_error() or preg_last_error_msg().

Next: preg_quote()

preg_quote() escapes special regular-expression characters so a string can be used safely .

preg_quote() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful