Funciones PCRE
PHP Manual

preg_match_all

(PHP 4, PHP 5)

preg_match_allRealiza una comparación global de una expresión regular

Descripción

int preg_match_all ( string $pattern , string $subject , array &$matches [, int $flags [, int $offset ]] )

Busca en subject todas las coincidencias de la expresión regular dada en pattern y las introduce en matches en el orden especificado por flags.

Después haber encontrado la primera coincidencia, las búsquedas subsiguientes continúan desde el final de la última coincidencia.

Parámetros

pattern

El patrón de búsqueda, como cadena.

subject

La cadena de entrada.

matches

Matriz de todas las coincidencias en una matriz multi-dimensional ordenadas según flags.

flags

Puede ser una combinación de las siguientes banderas (observe que no tiene sentido usar PREG_PATTERN_ORDER junto con PREG_SET_ORDER):

PREG_PATTERN_ORDER

Ordena los resultados de forma que $matches[0] es una matriz de coincidencias del patrón completo, $matches[1] es una matriz de cadenas coincidentes por el primer subpatrón entre paréntesis, y así sucesivamente.

<?php
preg_match_all
("|<[^>]+>(.*)</[^>]+>|U",
    
"<b>ejemplo: </b><div align=left>esto es una prueba</div>",
    
$salidaPREG_PATTERN_ORDER);
echo 
$salida[0][0] . ", " $salida[0][1] . "\n";
echo 
$salida[1][0] . ", " $salida[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í, $salida[0] contiene una matriz de cadenas que coinciden con el patrón completo, y $salida[1] contiene una matriz de cadenas encerradas entre etiquetas.

PREG_SET_ORDER

Ordena los resultados de forma que $matches[0] es una matriz del primer conjunto de coincidencias, $matches[1] es una matriz del segundo conjunto de coincidencias, y así sucesivamente.

<?php
preg_match_all
("|<[^>]+>(.*)</[^>]+>|U",
    
"<b>ejemplo: </b><div align=\"left\">esto es una prueba</div>",
    
$salidaPREG_SET_ORDER);
echo 
$salida[0][0] . ", " $salida[0][1] . "\n";
echo 
$salida[1][0] . ", " $salida[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 se pasa esta bandera, por cada coincidencia producida, el índice de la cadena añadida también será devulto. Observe que esto cambia el valor de matches dentro de una matriz donde cada elemento es una matriz consistente en la cadena coincidente en el índice 0 y su índice de cadena dentro de subject en el índice 1.

Si no se da un orden de bandera, se asume PREG_PATTERN_ORDER.

offset

Normalmente, la búsqueda comienza por el principio de la cadena objetivo. El parámetro opcional offset se puede usar para especificar el lugar alternativo desde el cual comenzar la búsqueda (en bytes).

Note:

Usar offset no es equivalente a pasar substr($sujeto, $índice) a preg_match() en lugar de la cadena objetivo, ya que pattern puede contener declaraciones como ^, $ o (?<=x). Véase preg_match() para los ejemplos.

Valores devueltos

Devuelve el número de coincidendias del patrón completo (el cual puede ser cero), o FALSE si se produjo un error.

Historial de cambios

Versión Descripción
5.2.2 Los sub-patrones nominados ahora aceptan la sintaxis (?<nombre>) y (?'nombre') así como (?P<nombre>). Versiones anteriores sólo aceptaban (?P<nombre>).
4.3.3 Se añadió el parámetro offset
4.3.0 Se añadió la bandera PREG_OFFSET_CAPTURE

Ejemplos

Example #1 Obtener todos los números de teléfono de algún texto.

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

Example #2 Buscar coincidencias de etiquetas HTML (codicioso)

<?php
// El \\2 es un ejemplo de retro-referencia. Esto le dice a pcre que
// debe coincidir el segundo conjunto de paréntesis en la expresión regular
// misma, el cual sería el ([\w]+) en este caso. La barra invertida extra es
// necesaria ya que la cadena está entre comilla dobles.
$html "<b>texto en negrita</b><a href=hola.html>Haz clic sobre mí</a>";

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

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

El resultado del ejemplo sería:

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

coindicido: <a href=hola.html>Haz clic sobre mí</a>
parte 1: <a href=hola.html>
parte 2: a
parte 3: Haz clic sobre mí
parte 4: </a>

Example #3 Usar sub-patrones nominados

<?php

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

preg_match_all('/(?P<nombre>\w+): (?P<dígito>\d+)/'$cadena$coincidencias);

/* Esto también funciona en PHP 5.2.2 (PCRE 7.0) y posteriores, sin embargo
 * la forma de arriba es la recomendada por compatibilidad con versiones anteriores */
// preg_match_all('/(?<nombre>\w+): (?<dígito>\d+)/', $cadena, $coincidencias);

print_r($coincidencias);

?>

El resultado del ejemplo sería:

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

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

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

    [dígito] => Array
        (
            [0] => 1
            [1] => 2
            [2] => 3
        )

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

)

Ver también


Funciones PCRE
PHP Manual