PCRE
PHP Manual

preg_match

(PHP 4, PHP 5)

preg_match — Realizar una comparación de expresión regular

Descripción

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

Busca en asunto por una coincidencia con la expresión regular dada en patron .

Lista de parámetros

patron

El patrón a buscar, como una cadena.

asunto

La cadena de entrada.

coincidencias

Si se entrega el parámetro coincidencias , entonces éste es llenado con los resultados de la búsqueda. $coincidencias[0] contendrá el texto que coincidió con el patrón completo, $coincidencias[1] tendrá el texto que coincidió con el primer sub-patrón en paréntesis capturado, y así sucesivamente.

banderas

banderas puede ser la siguiente bandera:

PREG_OFFSET_CAPTURE
Si es pasada esta bandera, entonces para cada coincidencia encontrada también será devuelto el desplazamiento de la cadena anexa. Note que esto modifica el valor de retorno a una matriz en donde cada elemento es una matriz que consiste de la cadena coincidente en el índice 0 y su desplazamiento de cadena al interior de asunto en el índice 1.

desplazamiento

Normalmente, la búsqueda comienza desde el principio de la cadena de asunto. El parámetro opcional desplazamiento puede ser usado para especificar el lugar alterno desde donde empezar la búsqueda (en bytes).

Note: El uso de desplazamiento no es equivalente a pasar substr($asunto, $desplazamiento) a preg_match() en lugar de la cadena de asunto, ya que patron puede contener aserciones tales como ^, $ o (?<=x). Compare:

<?php
$asunto 
"abcdef";
$patron '/^def/';
preg_match($patron$asunto$coincidenciasPREG_OFFSET_CAPTURE3);
print_r($coincidencias);
?>

El resultado del ejemplo seria:

Array
(
)

mientras que el siguiente ejemplo

<?php
$asunto 
"abcdef";
$patron '/^def/';
preg_match($patronsubstr($asunto,3), $coincidenciasPREG_OFFSET_CAPTURE);
print_r($coincidencias);
?>

producirá

Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )

)

Valores retornados

preg_match() devuelve el número de veces que patron coincide. Este número será 0 (no existe coincidencia) o 1, ya que preg_match() detendrá la búsqueda después de la primera coincidencia. Por el contrario, preg_match_all() continuará hasta llegar al final de asunto . preg_match() devuelve FALSE si ocurre un error.

Registro de cambios

Versión Descripción
4.3.3 El parámetro desplazamiento fue agregado
4.3.0 Se agregó la bandera PREG_OFFSET_CAPTURE
4.3.0 El parámetro banderas fue agregado

Ejemplos

Example#1 Buscar la cadena de texto "php"

<?php
// El caracter "i" después del delimitador del patrón indica una
// busqueda insensible a mayúsculas/minúsculas
if (preg_match("/php/i""PHP es el lenguaje de scripting web de moda.")) {
    echo 
"Se ha encontrado una coincidencia.";
} else {
    echo 
"No se ha encontrado una coincidencia.";
}
?>

Example#2 Buscar la palabra "web"

<?php
/* La secuencia \b en el patrón indica un límite de palabra, así que solo la
 * palabra única "web" coincide, y no una palabra parcial como "webbing" o
 * "cobweb" */
if (preg_match("/\bweb\b/i""PHP es el lenguaje de scripting web de moda.")) {
    echo 
"Se ha encontrado una coincidencia.";
} else {
    echo 
"No se ha encontrado una coincidencia.";
}

if (
preg_match("/\bweb\b/i""PHP es el website del lenguaje de scripting de moda.")) {
    echo 
"Se ha encontrado una coincidencia.";
} else {
    echo 
"No se ha encontrado una coincidencia.";
}
?>

Example#3 Obtener el nombre de dominio de una URL

<?php
// obtener el nombre de host de una URL
preg_match('@^(?:http://)?([^/]+)@i',
    
"http://www.php.net/index.html"$coincidencias);
$host $coincidencias[1];

// obtener los últimos dos segmentos del nombre de host
preg_match('/[^.]+\.[^.]+$/'$host$coincidencias);
echo 
"el nombre de dominio es: {$coincidencias[0]}\n";
?>

El resultado del ejemplo seria:

el nombre de dominio es: php.net

Notes

Tip

No use preg_match() si sólo desea verificiar si una cadena está contenida en otra. Use strpos() o strstr() en su lugar, ya que éstas son alternativas más rápidas.

Ver también


PCRE
PHP Manual