Comprendiendo la función preg_filter de PHP

La función preg_filter en PHP busca en una cadena (o array de cadenas) texto que coincida con una expresión regular y lo reemplaza. Su característica distintiva es que solo devuelve las entradas donde se produjo una coincidencia — las entradas sin coincidencia se descartan. Esto la hace ideal para tareas donde se desea buscar, reemplazar y filtrar en un solo paso.

Si has utilizado preg_replace, preg_filter te resultará familiar: la sintaxis es idéntica. La única diferencia de comportamiento — lo que ocurre con los sujetos que no coinciden — es lo que hace que preg_filter sea la opción adecuada, y es el enfoque de esta página.

En este artículo, cubriremos la sintaxis, los parámetros, cómo preg_filter difiere de preg_replace, y los casos de uso más comunes, cada uno con un ejemplo ejecutable.

Sintaxis y Parámetros

La sintaxis de la función preg_filter es la siguiente:

Sintaxis de PHP preg_filter

preg_filter(pattern, replacement, subject [, limit [, count]])

Los parámetros son los siguientes:

• pattern: Es el patrón de expresión regular que especifica el texto que deseas buscar.
• replacement: Es el texto que reemplazará el texto coincidente en el sujeto.
• subject: Es la cadena en la que deseas buscar y reemplazar texto.
• limit (opcional): El número máximo de reemplazos por cadena sujeto. El valor predeterminado es -1 (sin límite).
• count (opcional): Una variable pasada por referencia que se llenará con el número total de reemplazos realizados.

Los argumentos pattern, replacement y subject pueden ser cada uno un valor único o un array, exactamente igual que con preg_replace. El valor de retorno es una cadena cuando subject es una cadena, y un array cuando subject es un array.

preg_filter vs. preg_replace

Las dos funciones reciben los mismos argumentos y realizan el mismo trabajo de búsqueda y reemplazo. La diferencia está en lo que devuelven cuando un sujeto no coincide con el patrón:

• preg_replace devuelve el sujeto sin cambios.
• preg_filter devuelve null para un sujeto de tipo cadena, y omite la entrada por completo para un sujeto de tipo array.

<?php
$input = ["123", "abc", "456"];

// preg_replace keeps every element, matched or not.
print_r(preg_replace("/\d+/", "[num]", $input));
// Array ( [0] => [num] [1] => abc [2] => [num] )

// preg_filter drops the non-matching "abc".
print_r(preg_filter("/\d+/", "[num]", $input));
// Array ( [0] => [num] [2] => [num] )
?>

Observa que preg_filter preserva las claves originales (0 y 2) — no reindexará el array.

Casos de Uso

preg_filter es más útil cuando necesitas buscar, reemplazar y filtrar al mismo tiempo. Los casos de uso más comunes incluyen:

• Filtrar arrays: Pasa un array de cadenas y obtén de vuelta solo los elementos que coincidieron con el patrón.
• Eliminar etiquetas HTML: Quita etiquetas de cadenas o arrays de cadenas.
• Extraer y reformatear: Reemplaza el texto coincidente descartando las entradas que no contienen nada de interés.

Ejemplo: Eliminar etiquetas HTML

En este ejemplo, usaremos preg_filter para eliminar etiquetas HTML de una cadena:

Ejemplo de PHP preg_filter

En este ejemplo, usamos el patrón de expresión regular /<[^>]+>/ para coincidir con todas las etiquetas HTML en la cadena $html. El parámetro replacement se establece en una cadena vacía, por lo que el texto coincidente se elimina. El texto resultante se almacena en la variable $text y se muestra en pantalla.

Ejemplo: Filtrar elementos de un array

preg_filter destaca al trabajar con arrays porque elimina los elementos que no coinciden:

<?php
$items = ["apple", "banana", "apricot", "cherry"];
$filtered = preg_filter("/^a/", "A", $items);
print_r($filtered);
// Outputs:
// Array
// (
//     [0] => Apple
//     [2] => Apricot
// )
?>

En este ejemplo, preg_filter reemplaza la "a" inicial con "A" pero elimina automáticamente "banana" y "cherry" porque no coinciden con el patrón. Los elementos conservados mantienen sus claves originales (0 y 2).

Contar reemplazos con el parámetro count

El quinto parámetro opcional se rellena por referencia con el número de reemplazos realizados, lo que es útil para reportes o para ramificar según si hubo coincidencias:

<?php
$subject = "Order #42 and order #7";
$result = preg_filter("/#(\d+)/", "[$1]", $subject, -1, $count);
echo $result . "\n";   // Order [42] and order [7]
echo $count . "\n";    // 2
?>

Aquí $1 en el reemplazo es una referencia retroactiva al primer grupo de captura. Se realizaron dos coincidencias, por lo que $count es 2.

Conclusión

preg_filter realiza una búsqueda y reemplazo con expresiones regulares igual que preg_replace, pero descarta los sujetos que no coinciden — devolviendo null para cadenas y eliminando los elementos sin coincidencia de los arrays. Eso la convierte en la opción correcta cuando filtrar y reemplazar deben hacerse juntos en un solo paso.

Para profundizar en el conjunto de herramientas de expresiones regulares de PHP, consulta preg_match para probar una sola coincidencia, preg_match_all para encontrar todas las coincidencias, preg_split para dividir cadenas, y preg_replace_callback cuando el reemplazo necesita calcularse en código.

Práctica