# preg_match_all

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

preg_match_all — Realiza una comparación global de una expresión regular

### Descripción

preg_match_all(
string `$pattern`,
string `$subject`,
array `&$matches` = ?,
int `$flags` = `PREG_PATTERN_ORDER`,
int `$offset` = 0
): int

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 continuarán desde el final de la dicha coincidencia.

### Parámetros

`pattern`

  El patrón de búsqueda, dado como string.

`subject`

  La cadena de entrada.

`matches`

  Un array con todas las coincidencias en un array 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 un array de coincidencias del patrón completo, $matches[1] es un array 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>",
    $salida, PREG_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 un array de cadenas que coinciden con el patrón completo, y $salida[1] contiene un array de cadenas encerradas entre etiquetas.

    Si el patrón contiene subpatrones con nombre, $matches contendrá además entradas para claves con el nombre del subpatrón.

    Si el subpatrón contiene subpatrones con nombres duplicados, solamente se almacenará en $matches[NAME] el último subpatrón de la derecha.

    `<?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`

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

    `<?php
    preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>ejemplo: </b><div align=\"left\">esto 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 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á devuelto. Observe que esto cambia el valor de `matches` dentro de un array de arrays donde cada elemento es un array consistente en la cadena coincidente en el índice `0` y su índice de cadena dentro de `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
                        )

                )

        )

  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).

  > Nota:

  > 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 coincidencias del patrón completo (el cual puede ser cero), o `false` si se produjo un error.

### Historial de cambios

Versión | Descripción
--- | ---
5.4.0 | El parámetro `matches` ahora es opcional.
5.3.6 | Devuelve `false` si `offset` es mayor que la longitud de `subject`.
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>)`.

### Ejemplos

Ejemplo #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);
?>`

Ejemplo #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, $coincidencias, PREG_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>

Ejemplo #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

- Patrones de PCRE
- preg_quote() - Escapar caracteres en una expresión regular
- preg_match() - Realiza una comparación con una expresión regular
- preg_replace() - Realiza una búsqueda y sustitución de una expresión regular
- preg_split() - Divide un string mediante una expresión regular
- preg_last_error() - Devuelve el código de error de la última ejecución de expresión regular de PCRE