preg_match_all

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match_allExpresión regular global

Descripción

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

Analiza subject para encontrar la expresión pattern y almacena los resultados en matches, en el orden especificado por flags.

Tras encontrar un primer resultado, la búsqueda continúa hasta el final de la cadena.

Parámetros

pattern

La máscara a buscar, en forma de chaîne de caractères.

subject

La cadena de entrada.

matches

Array que contiene todos los resultados, en un array multidimensional ordenado según el parámetro flags.

flags

Puede ser una combinación de los siguientes valores (señalando que es incoherente usar PREG_PATTERN_ORDER con PREG_SET_ORDER ) :

PREG_PATTERN_ORDER

El orden es tal que $matches[0] es un array que contiene los resultados que satisfacen la máscara completa, $matches[1] es un array que contiene los resultados que satisfacen la primera subexpresión capturante, etc.

<?php
preg_match_all
("|<[^>]+>(.*)</[^>]+>|U",
"<b>ejemplo : </b><div align=left>esto es una prueba</div>",
$out, PREG_PATTERN_ORDER);
echo
$out[0][0] . ", " . $out[0][1] . "\n";
echo
$out[1][0] . ", " . $out[1][1] . "\n";
?>

El resultado del ejemplo sería:

<b>ejemplo : </b>, <div align=left>esto es una prueba</div>
ejemplo : , esto es una prueba

Así, $out[0] es un array que contiene los resultados que satisfacen la máscara completa, y $out[1] es un array que contiene las etiquetas entre > y <.

Si la máscara contiene submáscaras nombradas, $matches contendrá además entradas que tendrán como claves los nombres de las submáscaras.

Si la máscara contiene submáscaras nombradas duplicadas, solo la submáscara más a la derecha será registrada en $matches[NAME].

<?php
preg_match_all
(
'/(?J)(?<match>foo)|(?<match>bar)/',
'foo bar',
$matches,
PREG_PATTERN_ORDER
);
print_r($matches['match']);
?>

El resultado del ejemplo sería:

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

PREG_SET_ORDER

Los resultados se ordenan de tal forma que $matches[0] contiene la primera serie de resultados, $matches[1] contiene la segunda, etc.

<?php
preg_match_all
("|<[^>]+>(.*)</[^>]+>|U",
"<b>ejemplo : </b><div align=\"left\">esto es una prueba</div>",
$out, PREG_SET_ORDER);
echo
$out[0][0] . ", " . $out[0][1] . "\n";
echo
$out[1][0] . ", " . $out[1][1] . "\n";
?>

El resultado del ejemplo sería:

<b>ejemplo : </b>, ejemplo :
<div align="left">esto es una prueba</div>, esto es una prueba

PREG_OFFSET_CAPTURE

Si este flag es pasado, todas las subcadenas que satisfacen la máscara también serán identificadas por su offset (en bytes). Tenga en cuenta que esto modifica el valor de matches en un array de arrays donde cada elemento es un array que contiene la subcadena satisfecha en el índice 0 y el índice de esta en la cadena subject en el índice 1.

<?php
preg_match_all
('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

El resultado del ejemplo sería:

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

        )

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

        )

    [2] => Array
        (
            [0] => Array
                (
                    [0] => bar
                    [1] => 3
                )

        )

    [3] => Array
        (
            [0] => Array
                (
                    [0] => baz
                    [1] => 6
                )

        )

)

PREG_UNMATCHED_AS_NULL

Si este flag es pasado, las subexpresiones no satisfechas son reportadas como null ; de lo contrario, son reportadas como chaîne de caractères vacía.

Si order es omitido, PREG_PATTERN_ORDER es usado por defecto.

offset

Normalmente, la búsqueda comienza al inicio de la cadena subject. El parámetro opcional offset puede ser usado para especificar una posición para el inicio de la búsqueda (en bytes).

Nota:

Usar el parámetro offset no equivale a pasar substr($subject, $offset) a preg_match_all() en lugar de la cadena subject, ya que pattern puede contener aserciones como ^, $ o (?<=x). Consulte la documentación sobre la función preg_match() para ejemplos.

Valores devueltos

Devuelve el número de resultados que satisfacen la máscara completa, o false en caso de error.

Errores/Excepciones

If the regex pattern passed does not compile to a valid regex, an E_WARNING is emitted.

Historial de cambios

Versión Descripción
7.2.0 PREG_UNMATCHED_AS_NULL es ahora soportado para el parámetro $flags.

Ejemplos

Ejemplo #1 Extracción de todos los números de teléfono de un texto

<?php
preg_match_all
("/\(? (\d{3})? \)? (?(1) [\-\s] ) \d{3}-\d{4}/x",
"Llamar al 555-1212 o 1-800-555-1212", $phones);
?>

Ejemplo #2 Buscar pares de etiquetas HTML (voraz)

<?php
// Este ejemplo utiliza referencias hacia atrás (\\2).
// Indican al analizador que debe encontrar algo que ya ha identificado antes
// el número 2 indica que es el segundo juego de paréntesis
// capturante que debe ser usado (en este caso, ([\w]+)).
// La barra invertida es necesaria aquí, ya que la cadena está entre comillas dobles

$html = "<b>texto en negrita</b><a href=howdy.html>haz clic aquí</a>";

preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);

foreach (
$matches as $val) {
echo
"coincidencia: " . $val[0] . "\n";
echo
"parte 1: " . $val[1] . "\n";
echo
"parte 2: " . $val[2] . "\n";
echo
"parte 3: " . $val[3] . "\n";
echo
"parte 4: " . $val[4] . "\n\n";
}
?>

El resultado del ejemplo sería:

coincidencia: <b>texto en negrita</b>
parte 2: b
parte 3: texto en negrita
parte 4: </b>

coincidencia: <a href=howdy.html>haz clic aquí</a>
parte 1: <a href=howdy.html>
parte 2: a
parte 3: haz clic aquí
parte 4: </a>

Ejemplo #3 Uso de una subexpresión nombrada

<?php

$str
= <<<FOO
a: 1
b: 2
c: 3
FOO;

preg_match_all('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

/* Alternativa */
// preg_match_all('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

El resultado del ejemplo sería:

Array
(
    [0] => Array
        (
            [0] => a: 1
            [1] => b: 2
            [2] => c: 3
        )

    [name] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [1] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [digit] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

    [2] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

)

Ver también

  • Máscaras PCRE
  • preg_quote() - Protección de caracteres especiales de expresiones regulares
  • preg_match() - Realiza una búsqueda de coincidencia con una expresión regular estándar
  • preg_replace() - Buscar y reemplazar mediante expresión regular estándar
  • preg_split() - Divide una cadena mediante expresión regular
  • preg_last_error() - Devuelve el código de error de la última expresión PCRE ejecutada