Tema 2 · Búsqueda

Función preg_match(): Validación Booleana y Captura Básica

Aprende a usar preg_match() para validar cadenas de texto, interpretar su valor de retorno (1, 0, false) y capturar coincidencias en el array $matches.

1. ¿Qué son las Regex? Motor PCRE, Delimitadores y Anatomía 3. Caracteres Literales, Metacaracteres y preg_quote()

Firma y Comportamiento de preg_match()

La función preg_match() es la herramienta principal en PHP para buscar si una cadena de texto coincide con un patrón determinado. Se detiene en la primera coincidencia que encuentra, lo que la hace sumamente eficiente para validaciones booleanas. 

int|false preg_match(string $pattern, string $subject, array &$matches = null, int $flags = 0, int $offset = 0)
Valor de Retorno Significado Técnico Cómo Evaluarse Correctamente
1 (entero) Hubo una coincidencia exitosa con el patrón. if (preg_match(...) === 1)
0 (entero) El texto fue analizado pero no coincidió con el patrón. if (preg_match(...) === 0)
false (booleano) Ocurrió un error de compilación o ejecución en el motor PCRE (ej: sintaxis corrupta, desbordamiento de memoria o backtracking). if (preg_match(...) === false)
⚠️
¡Cuidado con la evaluación débil en PHP!
Si evalúas if (preg_match($patron, $texto)), tanto 0 como false son evaluados como falsos. Si el patrón tiene un error de sintaxis grave, tu código podría asumir silenciosamente que el usuario introdujo un dato inválido en lugar de detectar que tu Regex está rota. Siempre que sea crítico, usa la comparación estricta === 1.

El Parámetro por Referencia $matches

Si pasas una variable como tercer parámetro, PHP la inicializará como un array conteniendo los resultados de la búsqueda:

  • $matches[0]: Contiene siempre el fragmento de texto completo que coincidió con toda la expresión regular.
  • $matches[1]: Contiene el texto capturado por el primer grupo entre paréntesis (...).
  • $matches[2]: Contiene el texto capturado por el segundo grupo, y así sucesivamente.

La Bandera PREG_OFFSET_CAPTURE

Si necesitas conocer la posición en bytes dentro de la cadena donde ocurrió la coincidencia, puedes pasar la constante PREG_OFFSET_CAPTURE en el cuarto argumento. Cada elemento del array $matches se convertirá en un array de dos elementos: [0 => $texto, 1 => $posicionOffset].

⚡ Extracción de Información de Factura con preg_match()

Ejemplo interactivo ejecutable. Extraemos el código de factura, la moneda y el monto total utilizando grupos de captura:

extraccion_factura.php
Solo lectura 
<?php
// Cadena de texto recibida desde un sistema contable o correo
$textoFactura = "Orden procesada exitosamente. Factura N° FAC-98421 por un total de USD 4,850.50 con tarjeta de crédito.";

// Patrón con 3 grupos de captura: (Código Factura), (Moneda) y (Monto)
$patron = '/Factura N° (FAC-\d+) por un total de ([A-Z]{3})\s+([\d,]+\.\d{2})/';

echo "<div style='font-family:system-ui; max-width:620px; padding:15px;'>";
echo "<h3 style='color:#0f172a; margin-top:0;'>🧾 Procesamiento de Factura con preg_match()</h3>";

$resultado = preg_match($patron, $textoFactura, $coincidencias);

if ($resultado === 1) {
    echo "<div style='background:#ecfdf5; border:1px solid #a7f3d0; border-radius:8px; padding:15px; margin-bottom:15px;'>";
    echo "  <p style='margin:0 0 8px 0; color:#065f46; font-weight:bold;'>✅ Coincidencia encontrada con éxito:</p>";
    echo "  <p style='margin:4px 0; color:#1e293b;'><strong>Coincidencia Completa (\$matches[0]):</strong> <code style='background:#fff; padding:2px 6px; border-radius:4px;'>{$coincidencias[0]}</code></p>";
    echo "  <hr style='border:none; border-top:1px solid #d1fae5; margin:10px 0;'>";
    echo "  <ul style='margin:0; padding-left:20px; color:#1e293b;'>";
    echo "    <li><strong>Número de Factura (\$matches[1]):</strong> <span style='color:#0284c7; font-weight:bold;'>{$coincidencias[1]}</span></li>";
    echo "    <li><strong>Divisa Monetaria (\$matches[2]):</strong> <span style='color:#7c3aed; font-weight:bold;'>{$coincidencias[2]}</span></li>";
    echo "    <li><strong>Importe Total (\$matches[3]):</strong> <span style='color:#059669; font-weight:bold;'>\${$coincidencias[3]}</span></li>";
    echo "  </ul>";
    echo "</div>";

    // Convertir el monto a flotante nativo de PHP para cálculos
    $montoLimpio = (float)str_replace(',', '', $coincidencias[3]);
    echo "<p style='color:#64748b; font-size:13px;'>💡 Monto casteado a float para operaciones matemáticas: <strong>" . var_export($montoLimpio, true) . "</strong></p>";
} elseif ($resultado === 0) {
    echo "<p style='color:#dc2626;'>❌ El texto no contiene el formato de factura esperado.</p>";
} else {
    echo "<p style='color:#dc2626;'>⚠️ Ocurrió un error en la compilación del patrón PCRE.</p>";
}

echo "</div>";
Pruébalo tú mismo » Se abre en una nueva pestaña con ejecución en vivo
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué valor exacto devuelve preg_match() si la expresión regular no contiene errores pero el texto evaluado NO coincide con el patrón?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Regex en PHP: Expresiones Regulares & PCRE y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

Conocer el Bootcamp

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de David Amador para Kilopolis Academia (Solucionáticos), estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.