Funciones de PCRE
PHP Manual

preg_match

(PHP 4, PHP 5)

preg_match — Realiza una comparación con una expresión regular

Descripción

int preg_match ( string $pattern , string $subject [, array &$matches [, int $flags = 0 [, int $offset = 0 ]]] )

Busca en subject una coincidencia con la expresión regular dada en pattern.

Parámetros

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.

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

)

Valores devueltos

preg_match() devuelve 1 si pattern coincide con el subject dado, 0 si no, o FALSE si ocurrió un error.

Advertencia

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.

Historial de cambios

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>).
4.3.3 Se añadió el parámetro offset
4.3.0 Se añadió las bandera PREG_OFFSET_CAPTURE
4.3.0 Se añadió el parámetro flags

Ejemplos

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
)

Notas

Sugerencia

No use preg_match() si solo quiere verificar si una cadena está contenida en otra cadena. Use strpos() o strstr() en su lugar ya que éstas serán más rápidas.

Ver también

Funciones de PCRE
PHP Manual