Realiza una búsqueda de coincidencia con una expresión regular estándar

# preg_match

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

preg_match — Realiza una búsqueda de coincidencia con una expresión regular estándar

### Descripción

function preg_match(
string `$pattern`,
string `$subject`,
array `&$matches` = `null`,
int `$flags` = 0,
int `$offset` = 0
): int|false

Analiza `subject` para encontrar la expresión que coincide con `pattern`.

### Parámetros

`pattern`

  El patrón a buscar, en forma de cadena.

`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 ejemplo anterior mostrará:

        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 una string vacía.

        <?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 ejemplo anterior mostrará:

        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 pasar `substr($subject, $offset)` a preg_match_all() en lugar de la cadena subject, ya que `pattern` puede contener aserciones como ^, $ o (?<=x). Compárese:

  >     <?php
  >     $subject = "abcdef";
  >     $pattern = '/^def/';
  >     preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
  >     print_r($matches);
  >     ?>

  > El ejemplo anterior mostrará:

  >     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 modificador `A`, ambos funcionan con el parámetro `offset`.

### Valores devueltos

preg_match() devuelve 1 si el `pattern` coincide con el `subject` dado, 0 si no coincide, o `false` si ocurre un error.

Advertencia

Esta función puede retornar `false`, pero también puede retornar un valor equivalente a `false`. Por favor, lea la sección sobre los booleanos para más información. Utilice el operador === para probar el valor de retorno exacto de esta función.

### Errores/Excepciones

Si el patrón regex pasado no se compila a una regex válida, se emite una `E_WARNING`.

### Historial de cambios

Versión | Descripción
--- | ---
7.2.0 | `PREG_UNMATCHED_AS_NULL` ahora es soportado para el parámetro `flags`.

### Ejemplos

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 ejemplo anterior mostrará:

    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 ejemplo anterior mostrará:

    Array
    (
        [0] => foobar: 2008
        [name] => foobar
        [1] => foobar
        [digit] => 2008
        [2] => 2008
    )

### Notas

Sugerencia

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.

### Ver también

- Patrones PCRE
- preg_quote() - Protección de caracteres especiales de expresiones regulares
- preg_match_all() - Expresión regular global
- preg_replace() - Buscar y reemplazar mediante expresión regular estándar
- preg_split() - Divide una cadena mediante expresión regular
- preg_last_error() - Devuelve el código de error de la última expresión PCRE ejecutada
- preg_last_error_msg() - Devuelve el mensaje de error de la última ejecución de regex PCRE

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open