# preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

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

### Descripción

preg_match(
string `$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`.

### 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`.

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

### 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 comprobar si una cadena está contenida en otra cadena. Use strpos() en su lugar ya que será más rápida.

### Ver también

- Patrones de PCRE
- preg_quote() - Escapar caracteres en una expresión regular
- preg_match_all() - Realiza una comparación global de una expresión regular
- preg_replace() - Realiza una búsqueda y sustitución de una expresión regular
- preg_split() - Divide un string mediante una expresión regular
- preg_last_error() - Devuelve el código de error de la última ejecución de expresión regular de PCRE