preg_match

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

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

Descripción

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 chaîne de caractères.

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

)

PREG_UNMATCHED_AS_NULL

Si este flag es pasado, los subpatrones no coincidentes son reportados como null; de lo contrario son reportados como chaîne de caractères vacío.

<?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 resultado del ejemplo sería:

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

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

El resultado del ejemplo sería:

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 proporcionado coincide, 0 si no coincide, o false en caso de 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.

Errores/Excepciones

If the regex pattern passed does not compile to a valid regex, an E_WARNING is emitted.

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 resultado del ejemplo sería:

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 resultado del ejemplo sería:

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