preg_match_all
preg_quote
PCRE Functions
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, $coincidencias, PREG_OFFSET_CAPTURE, 3);
  > print_r($coincidencias);
  > ?>`

  > El resultado del ejemplo seria:

  >     Array
  >     (
  >     )

  > mientras que el siguiente ejemplo

  > `<?php
  > $asunto = "abcdef";
  > $patron = '/^def/';
  > preg_match($patron, substr($asunto,3), $coincidencias, PREG_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

- preg_match_all() - Realizar una comparación global con una expresión regular
- preg_replace() - Realizar una operación de búsqueda y reemplazo con expresiones regulares
- preg_split() - Separar una cadena por una expresión regular

preg_match_all
preg_quote
PCRE Functions
PHP Manual