Filtros

El otro tipo de eventos que nos ofrece WordPress son los Filters, o filtros. Este tipo de eventos ya no pone tanto el foco en la ejecución de procesos, como pasa con las acciones, sino en la manipulación de datos internos de la aplicación. Por ejemplo, un filtro puede ser utilizado para cambiar el valor de una variable, o modificar el valor de retorno de una función. Usos típicos de los filtros pueden ser: activar o desactivar ciertas características de la aplicación, modificar alguna parte del HTML que se va a imprimir, cambiar valores de configuración, o alterar consultas a la base de datos.

Una característica importante de los filtros es que siempre tienen un valor de retorno, a diferencia de las acciones. Debido a esto, los filtros siempre están asignados a una variable, a una evaluación o a un valor de retorno de una función o método.

Teniendo en cuenta esta diferencia, su uso es muy similar al de las acciones. En algún punto de nuestro código vamos a tener un llamado a la función apply_filters(), que es equivalente a do_action(). Los parámetros que va a recibir esta función son el nombre del evento y el valor que va a tener por defecto.

<?php
$comensales = apply_filters( 'cantidad_de_comensales', 10 );

Ahora bien, antes de que ese código se ejecute, necesitamos definir cuáles van a ser los filtros que se asignen al evento. Esto podemos hacerlo a través de la función add_filter().

<?php
add_filter( 'cantidad_de_comensales', 'nueva_cantidad_de_comensales' );

function nueva_cantidad_de_comensales( $comensales ) {
    if ( viene_ramon() ) {
        $comensales++;
    }

    return $comensales;
}

$comensales = apply_filters( 'cantidad_de_comensales', 10 );

De esta manera, al momento de definirse la variable $comensales, el valor por defecto (10) se le va a pasar a la función nueva_cantidad_de_comensales(), y va a sumar 1 en caso de que Ramón venga (dando por resultado 11). Noten que antes de finalizar la función que opera como filtro siempre necesitamos devolver un valor; de lo contrario el valor que estemos filtrando va a terminar siendo null.

Los filtros, al igual que las acciones, pueden recibir una prioridad de ejecución ($priority) y un número de argumentos ($accepted_args) como tercer y cuarto parámetro, respectivamente.

<?php
add_filter( 'cantidad_de_comensales', 'descartar_vegetarianos', 20, 2 );

function descartar_vegetarianos( $comensales, $comida ) {
    if ( 'asado' == $comida && viene_jose() ) {
        $comensales--;
    }

    return $comensales;
}

add_filter( 'cantidad_de_comensales', 'nueva_cantidad_de_comensales', 10 );

function nueva_cantidad_de_comensales( $comensales ) {
    if ( viene_ramon() ) {
        $comensales++;
    }

    return $comensales;
}

$comida = 'asado';
$comensales = apply_filters( 'cantidad_de_comensales', 10, $comida );

De esta forma, el primer filtro a ejecutarse va a ser nueva_cantidad_de_comensales(), por más que se haya declarado en segundo lugar. No necesitamos especificar la cantidad de argumentos para ese filtro, porque el valor por defecto es 1, y solamente necesitamos la primera variable, $comensales. En segundo lugar se va a ejecutar la función descartar_vegetarianos(), que va a restar un comensal en caso de que la comida sea asado y venga José. Al asignar este filtro sí especificamos que vamos a recibir dos parámetros, ya que necesitamos las variables $comensales y $comida, que se están pasando al filtro por medio de apply_filters().

Al igual que pasa con las acciones, también tenemos muchos filtros que vienen con WordPress por defecto. Uno de ellos es the_content, que se aplica al contenido de cada post o página antes de ser impreso. Supongamos que queremos crear un nuevo plugin que modifique levemente este contenido. Para eso necesitamos crearlo, con su correspondiente encabezado, activarlo desde la sección de administración, y tener dentro de nuestro código algo como esto:

<?php
/*
Plugin Name: Modify Content
*/

add_filter( 'the_content', 'modify_post_content' );

function modify_post_content( $content ) {
    if ( is_single() ) {
        $content = '<p>Esto es un post.</p>' . $content;
    }

    return $content;
}

Una vez que guardemos este código en nuestro plugin y refresquemos cualquier página correspondiente a un post, vamos a ver el texto que agregamos en nuestra función inmediatamente arriba del resto del contenido.

De la misma forma que cuando usamos acciones predefinidas por WordPress, no estamos haciendo en ningún momento el llamado a apply_filters() con the_content como primer parámetro, ya que WordPress mismo se encarga de hacer ese llamado en algún punto de su ejecución. Y también al igual que con las acciones, podemos definir nuestros propios eventos en los que se van a aplicar filtros.

<?php
/*
Plugin Name: Modify Content
*/

add_filter( 'additional_post_content', 'show_thumbnail_message' );

function show_thumbnail_message( $additional_post_content ) {
    if ( ! has_post_thumbnail() ) {
        $additional_post_content .= '<p>Este post no tiene una imagen destacada.</p>';
    }

    return $additional_post_content;
}

add_filter( 'the_content', 'modify_post_content' );

function modify_post_content( $content ) {
    if ( is_single() ) {
        $content = apply_filters( 'additional_post_content', '<p>Esto es un post.</p>' ) . $content;
    }

    return $content;
}

Con este agregado, es decir definiendo un evento al modificar el contenido, y asignando un filtro a ese nuevo evento, podemos hacer que se muestre el mensaje "Este post no tiene una imagen destacada" antes del post, en el caso de que efectivamente no tenga una imagen. De lo contrario, el texto va a ser "Esto es un post". Podemos ver ese cambio reflejado al refrescar la página de cualquier post sin imagen destacada.

También para los filtros hay disponible una lista muy grande de aquellos que WordPress ofrece por defecto en su documentación oficial, con un detalle del momento en el que se aplica cada uno de estos eventos.

Ahora que ya manejamos los conceptos principales de la programación orientada a eventos, podemos continuar viendo algunas prácticas un poco más avanzadas al usar la Plugin API.