(PHP 4, PHP 5, PHP 7)
preg_match_all — Realiza una comparación global de una expresión regular
$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.
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 quepattern
puede contener declaraciones como ^, $ o (?<=x). Véase preg_match() para los ejemplos.
Devuelve el número de coincidencias del patrón completo (el cual puede ser cero),
o FALSE
si se produjo un error.
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>). |
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 ) )