(PHP 4, PHP 5, PHP 7, PHP 8)
preg_match — Realiza una búsqueda de coincidencia con una expresión regular estándar
$pattern
,$subject
,&$matches
= null
,$flags
= 0,$offset
= 0
Analiza subject
para encontrar la expresión que
coincide con pattern
.
pattern
El patrón a buscar, en forma de chaîne de caractères.
subject
La cadena de entrada.
matches
Si matches
es proporcionado, será llenado con
los resultados de la búsqueda. $matches[0] contendrá el
texto que satisface el patrón completo, $matches[1] contendrá
el texto que satisface la primera subexpresión capturante,
etc.
flags
El parámetro flags
puede ser una combinación de los siguientes flags:
PREG_OFFSET_CAPTURE
Si esta opción está activada, todas las subcadenas que satisfacen
el patrón también serán identificadas por su offset (en bytes). Tenga en cuenta que esto
modifica el valor de matches
que se convierte en
un array donde cada elemento es un array que contiene la cadena
que coincide con el patrón en el offset 0
así
como el offset de la cadena en subject
en el offset 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 ) )
PREG_UNMATCHED_AS_NULL
Si este flag es pasado, los subpatrones no coincidentes son reportados como null
;
de lo contrario son reportados como chaîne de caractères vacío.
<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>
El resultado del ejemplo sería:
array(4) { [0]=> string(2) "ac" [1]=> string(1) "a" [2]=> string(0) "" [3]=> string(1) "c" } array(4) { [0]=> string(2) "ac" [1]=> string(1) "a" [2]=> NULL [3]=> string(1) "c" }
offset
Normalmente, la búsqueda comienza al inicio de la cadena
subject
. El parámetro opcional
offset
puede ser utilizado para especificar
una posición para el inicio de la búsqueda (en bytes).
Nota:
Utilizar el parámetro
offset
no es equivalente a pasarsubstr($subject, $offset)
a preg_match_all() en lugar de la cadenasubject
, ya quepattern
puede contener aserciones como ^, $ o (?<=x). Compare:<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);
?>El resultado del ejemplo sería:
Array ( )con este ejemplo:
<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>producirá:
Array ( [0] => Array ( [0] => def [1] => 0 ) )Por lo tanto, para evitar el uso de substr(), utilizar la aserción
\G
en lugar del ancla^
, o el modificadorA
, ambos funcionan con el parámetrooffset
.
preg_match() devuelve 1 si el pattern
proporcionado coincide, 0 si no coincide, o false
en caso de 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.
If the regex pattern passed does not compile to a valid regex, an E_WARNING
is emitted.
Versión | Descripción |
---|---|
7.2.0 |
PREG_UNMATCHED_AS_NULL ahora es soportado para el
parámetro $flags .
|
Ejemplo #1 Encontrar la cadena "php"
<?php
// El "i" después del delimitador del patrón indica que la búsqueda no será sensible a mayúsculas/minúsculas
if (preg_match("/php/i", "PHP es el mejor lenguaje de script del web.")) {
echo "Se encontró un resultado.";
} else {
echo "No se encontró ningún resultado.";
}
?>
Ejemplo #2 Encontrar la palabra "web"
<?php
/* \b, en el patrón, indica un límite de palabra, de forma que la palabra
"web" sea detectada, y no solo partes de palabras como
en "webbing" o "cobweb" */
if (preg_match("/\bweb\b/i", "PHP es el mejor lenguaje de script del web.")) {
echo "La palabra fue encontrada.";
} else {
echo "La palabra no fue encontrada.";
}
echo "\n";
if (preg_match("/\bweb\b/i", "PHP es el mejor lenguaje de script del web.")) {
echo "La palabra fue encontrada.";
} else {
echo "La palabra no fue encontrada.";
}
?>
Ejemplo #3 Leer un nombre de dominio en una URL
<?php
// detectar el nombre del host en la URL
preg_match('@^(?:http://)?([^/]+)@i',
"http://www.php.net/index.html", $matches);
$host = $matches[1];
// detectar los dos últimos segmentos del nombre del host
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "El nombre de dominio es: {$matches[0]}\n";
?>
El resultado del ejemplo sería:
El nombre de dominio es: php.net
Ejemplo #4 Uso de subpatrones nombrados
<?php
$str = 'foobar: 2008';
preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
/* Alternativa */
// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);
print_r($matches);
?>
El resultado del ejemplo sería:
Array ( [0] => foobar: 2008 [name] => foobar [1] => foobar [digit] => 2008 [2] => 2008 )
No utilice preg_match() si solo desea saber si una cadena está contenida en otra. Utilice strpos() en su lugar, ya que será más rápido.