preg_match()

Introducción

preg_match() realiza una coincidencia de expresión regular contra una cadena. Indica si un patrón PCRE aparece en un sujeto y, opcionalmente, captura qué coincidió. Se detiene en la primera coincidencia — si necesitas todas las ocurrencias, usa preg_match_all() en su lugar.

Este capítulo cubre la firma y los valores de retorno, cómo se rellena el array $matches, los indicadores más útiles y los errores comunes (la trampa de 0 vs false, el anclaje, los delimitadores) que suelen confundir a la gente.

Sintaxis

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

Valor de retorno: 1 si el patrón coincidió, 0 si no lo hizo, o false en caso de error (un patrón inválido). Dado que preg_match() devuelve como máximo 1, nunca indica cuántas coincidencias existen — solo que hubo una.

Ejemplo básico

El patrón captura una palabra alfabética seguida de un espacio en blanco y otra palabra. Cuando hay coincidencia, $matches[0] contiene la coincidencia completa (This is), y $matches[1] / $matches[2] contienen los dos grupos capturados (This e is).

La trampa de 0 vs false

Un error muy común es usar == para comprobar el resultado. preg_match() devuelve 0 para "sin coincidencia" y false solo en caso de error, y 0 == false es true en PHP. Compara siempre con el operador estricto:

<?php

$result = preg_match('/[0-9]+/', 'abc');

// Wrong: treats "no match" and "error" the same
if ($result == false) {
  echo "ambiguous\n";
}

// Right: distinguish the three outcomes
if ($result === false) {
  echo "Error in the pattern\n";
} elseif ($result === 0) {
  echo "No match\n";
} else {
  echo "Matched\n";
}

Esto imprime ambiguous y luego No match.

Grupos con nombre

Añade (?<name>...) a tu patrón y $matches contendrá las capturas bajo el índice numérico y el nombre, lo que hace el código más legible cuando el orden de los grupos cambia:

<?php

$date = '2026-06-21';
preg_match('/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/', $date, $m);

echo $m['year'] . "\n";  // 2026
echo $m['month'] . "\n"; // 06
echo $m['day'];          // 21

Capturar posiciones con PREG_OFFSET_CAPTURE

Pasa el indicador PREG_OFFSET_CAPTURE y cada entrada en $matches se convierte en un par [texto_coincidente, desplazamiento_en_bytes], para que puedas saber dónde ocurrió la coincidencia:

<?php

preg_match('/world/', 'hello world', $m, PREG_OFFSET_CAPTURE);

echo $m[0][0] . "\n"; // world
echo $m[0][1];        // 6

Patrones sin distinción de mayúsculas y anclados

Los modificadores van después del delimitador de cierre. El modificador i ignora las mayúsculas; ^ y $ anclan la coincidencia al inicio y al final de la cadena, por lo que todo el sujeto debe coincidir con el patrón:

<?php

var_dump(preg_match('/^hello$/i', 'HELLO')); // int(1)
var_dump(preg_match('/^hello$/i', 'hello!')); // int(0)

Cuándo usar otra función

• Todas las ocurrencias, no solo la primera → preg_match_all().
• Buscar y reemplazar → preg_replace().
• Dividir una cadena por un patrón → preg_split(); para un delimitador fijo, el simple explode() es más rápido.
• Escapar la entrada del usuario antes de incluirla en un patrón → preg_quote().
• Un repaso a la sintaxis PCRE → el capítulo de expresiones regulares en PHP.

Conclusión

preg_match() es la función principal para comprobar si una cadena coincide con un patrón y extraer grupos capturados. Recuerda sus tres valores de retorno, compara con === para evitar la trampa de 0/false, y usa preg_match_all() cuando una sola coincidencia no sea suficiente.

Práctica