preg_last_error
preg_match
PCRE Functions
PHP Manual

# preg_match_all

(PHP 4, PHP 5)

preg_match_all — Realizar una comparación global con una expresión regular

### Descripción

int preg_match_all ( string `$patron` , string `$asunto` , array `&$coincidencias` [, int `$banderas` [, int `$desplazamiento` ]] )

Busca el `asunto` por todas las coincidencias con la expresión regular dada en `patron` , y las coloca en `coincidencias` en el orden especificado por `banderas` .

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

### Lista de parámetros

`patron`

  El patrón a buscar, como una cadena.

`asunto`

  La cadena de entrada.

`coincidencias`

  Una matriz multi-dimensional con todas las coincidencias ordenadas de acuerdo al parámetro `banderas` .

`banderas`

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

  `PREG_PATTERN_ORDER`

    Ordena los resultados de tal forma que $coincidencias[0] es una matriz con las coincidencias completas del patrón, $coincidencias[1] es una matriz con las cadenas que coinciden con el primer sub-patrón entre paréntesis, y así sucesivamente.

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

    El resultado del ejemplo seria:

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

    Así que $salida[0] contiene una matriz de cadenas que coincidieron con el patrón completo, y $salida[1] contiene una matriz de cadenas ubicadas entre etiquetas.

  `PREG_SET_ORDER`

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

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

    El resultado del ejemplo seria:

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

  `PREG_OFFSET_CAPTURE`

    Si es pasada esta bandera, para cada coincidencia que ocurre, será devuelto también el desplazamiento de la cadena adjunta. Note que esto modifica el valor de `coincidencias` , convirtiéndolo en una matriz en donde cada elemento es una matriz que consiste de la cadena que coincidió en la posición 0, y su desplazamiento de cadena al interior del `asunto` en la posición 1.

  Si no se indica bandera alguna, se asume el uso de `PREG_PATTERN_ORDER`.

`desplazamiento`

  Normalmente, la búsqueda comienza desde el inicio de la cadena de asunto. El parámetro opcional `desplazamiento` puede ser usado para especificar el lugar alternativo desde donde debe iniciar la búsqueda (en bytes).

  > Note: El uso de `desplazamiento` no es equivalente a pasar substr($asunto, $desplazamiento) a preg_match_all() en lugar de la cadena de asunto, ya que `patron` puede contener aserciones como ^, $ o (?<=x). Vea preg_match() para más ejemplos.

### Valores retornados

Devuelve el número de coincidencias con el patrón completo (que puede ser cero), o `FALSE` si ocurre un error.

### Registro de cambios

Versión | Descripción
--- | ---
4.3.3 | Fue agregado el parámetro `desplazamiento`
4.3.0 | Fue agregada la bandera `PREG_OFFSET_CAPTURE`

### Ejemplos

Example #1 Obtener todos los números telefónicos de un segmento de texto.

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

Example #2 Encontrar etiquetas HTML coincidentes (de forma ambiciosa)

`<?php
// El \\2 es un ejemplo de referencia hacia atrás. Este le dice a pcre
// que debe buscar el segundo conjunto de paréntesis en la expresión
// regular misma, que sería ([\w]+) en este caso. La barra invertida
// extra es requerida ya que la cadena se encuentra entre comillas
// dobles.
$html = "<b>texto en negrilla</b><a href=hola.html>haga clic aquí</a>";
preg_match_all("/(<([\w]+)[^>]*>)(.*)(<\/\\2>)/", $html, $coincidencias, PREG_SET_ORDER);
foreach ($coincidencias as $val) {
echo "coincidencia: " . $val[0] . "\n";
echo "parte 1: " . $val[1] . "\n";
echo "parte 2: " . $val[3] . "\n";
echo "parte 3: " . $val[4] . "\n\n";
}
?>`

El resultado del ejemplo seria:

    coincidencia: <b>texto en negrilla</b>
    parte 1: <b>
    parte 2: texto en negrilla
    parte 3: </b>

    coincidencia: <a href=hola.html>haga clic aquí</a>
    parte 1: <a href=hola.html>
    parte 2: haga clic aquí
    parte 3: </a>

### Ver también

- preg_match() - Realizar una comparación de expresión regular
- preg_replace() - Realizar una operación de búsqueda y reemplazo con expresiones regulares
- preg_split() - Separar una cadena por una expresión regular

preg_last_error
preg_match
PCRE Functions
PHP Manual