(PHP 4, PHP 5, PHP 7)
preg_match — Realiza una comparación con una expresión regular
$pattern
, string $subject
[, array &$matches
[, int $flags
= 0
[, int $offset
= 0
]]] ) : int
Busca en subject
una coincidencia con la expresión regular
dada en pattern
.
pattern
El patrón de búsqueda, como cadena.
subject
La cadena de entrada.
matches
Si se proporciona matches
, entonces éste se llena con
los resultados de la búsqueda. $matches[0] contendrá el
texto que coincidió con el patrón completo, $matches[1]
tendrá el texto que coincidió con el primer sub-patrón entre paréntesis capturado,
y así sucesivamente.
flags
flags
puede estar seguido de la siguiente bandera:
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 una matriz donde cada elemento es una
matriz consistente en la cadena coincidente en el índice 0
y su índice dentro de la cadena subject
en el índice
1.
<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>
El resultado del ejemplo sería:
Array ( [0] => Array ( [0] => foobarbaz [1] => 0 ) [1] => Array ( [0] => foo [1] => 0 ) [2] => Array ( [0] => bar [1] => 3 ) [3] => Array ( [0] => baz [1] => 6 ) )
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). Compare:<?php
$sujeto = "abcdef";
$patrón = '/^def/';
preg_match($patrón, $sujeto, $coincidencias, PREG_OFFSET_CAPTURE, 3);
print_r($coincidencias);
?>El resultado del ejemplo sería:
Array ( )mientras que este ejemplo
<?php
$sujeto = "abcdef";
$patrón = '/^def/';
preg_match($patrón, substr($sujeto,3), $coincidencias, PREG_OFFSET_CAPTURE);
print_r($coincidencias);
?>producirá
Array ( [0] => Array ( [0] => def [1] => 0 ) )
preg_match() devuelve 1 si pattern
coincide con el subject
dado, 0 si no, o FALSE
si ocurrió un error.
Esta función puede
devolver el valor booleano FALSE
, pero también puede devolver un valor no booleano que se
evalúa como FALSE
. Por favor lea la sección sobre Booleanos para más
información. Use el operador
=== para comprobar el valor devuelto por esta
función.
Versión | Descripción |
---|---|
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>). Las versiones anteriores sólo aceptaban (?P<nombre>). |
Ejemplo #1 Busca la cadena de texto "php"
<?php
// La "i" después del delimitador de patrón indica una búsqueda
// sin tener en cuenta mayúsculas/minúsculas
if (preg_match("/php/i", "PHP es el lenguaje de secuencias de comandos web preferido.")) {
echo "Se encontró una coincidencia.";
} else {
echo "No se encontró ninguna coincidencia.";
}
?>
Ejemplo #2 Busca la palabra "web"
<?php
/* El \b en el patrón indica un límite de palabra, por lo que sólo la palabra
* definida "web" se compara, y no una palabra parcial como "webbing" o "cobweb" */
if (preg_match("/\bweb\b/i", "PHP es el lenguaje de secuencias de comandos web preferido.")) {
echo "Se encontró una coincidencia.";
} else {
echo "No se encontró ninguna coincidencia.";
}
if (preg_match("/\bweb\b/i", "PHP es el lenguaje de secuencias de comandos website preferido.")) {
echo "Se encontró una coincidencia.";
} else {
echo "No se encontró ninguna coincidencia.";
}
?>
Ejemplo #3 Obtener el nombre de dominio de una URL
<?php
// obtiene el nombre del host de la URL
preg_match('@^(?:http://)?([^/]+)@i',
"http://www.php.net/index.html", $coincidencias);
$host = $coincidencias[1];
// obtiene los dos últimos segmentos del nombre del host
preg_match('/[^.]+\.[^.]+$/', $host, $coincidencias);
echo "El nombre de dominio es: {$coincidencias[0]}\n";
?>
El resultado del ejemplo sería:
El nombre de dominio es: php.net
Ejemplo #4 Usar sub-patrones nominados
<?php
$cadena = 'foobar: 2008';
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] => foobar: 2008 [name] => foobar [1] => foobar [digit] => 2008 [2] => 2008 )
No use preg_match() si solo quiere comprobar si una cadena está contenida en otra cadena. Use strpos() en su lugar ya que será más rápida.