Argumentos WP_Query: Fecha

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

En esta serie sobre WP_Query, has aprendido cómo usar la clase WP_Query para crear consultas personalizadas en los archivos de tu tema o de tus plugins.

Esta parte de la serie nos llevará a través de los argumentos que puedes usar para crear consultas tanto simples como complejas, para mostrar entradas publicadas en, con anterioridad, con posterioridad o entre unas fechas dadas.

Te mostraré qué parámetros tienes a tu disposición y cómo usarlos para escribir tus consultas. Pero en primer lugar, recordaremos cómo funcionan los argumentos en WP_Query.

Una recapitulación sobre cómo funcionan los argumentos en WP_Query

Antes de empezar, recordemos brevemente cómo funcionan los argumentos en WP_Query. Cuando codificas WP_Query en tus temas o plugins, necesitas incluir cuatro elementos principales:

los argumentos para la consulta, usando parámetros que veremos en este tutorial
la consulta en sí
el bucle
Finalizar: etiquetas de cierre if o while y restablecer los datos de entrada

En la práctica esto tendrá un aspecto similar a lo siguiente:

<?php

$args = array(
    // Arguments for your query.
);

// Custom query.
$query = new WP_Query( $args );

// Check that we have query results.
if ( $query->have_posts() ) {

    // Start looping over the query results.
    while ( $query->have_posts() ) {

        $query->the_post();

        // Contents of the queried post results go here.

    }

}

// Restore original post data.
wp_reset_postdata();

?>

Los argumentos son lo que le indica a WordPress qué datos extraer de la base de datos y esos son los que vamos a cubrir aquí. De modo que aquí solo nos centraremos en la primera parte del código:

1	$args = array(
2	// Arguments for your query.
3	);

Como puedes ver, estos argumentos están contenidos en una matriz. Aprenderás a codificarlos conforme avancemos en este tutorial.

Codificar tus argumentos

Existe una forma concreta de codificar los argumentos en la cadena, es como sigue:

$args = array(
    'parameter1' => 'value',
    'parameter2' => 'value',
    'parameter3' => 'value'
);

Debes envolver los parámetros y sus valores entre comillas simples, usar => entre ellos, y separarlos mediante comas. Si lo haces mal, WordPress podría no añadir todos tus argumentos a la consulta o podrías obtener una pantalla en blanco.

Parámetros de fecha

También puedes usar parámetros para consultar entradas con una fecha de publicación. Puedes ser tan específico como desees con las fechas, usando años y meses por ejemplo para extraer una cierta cantidad de entradas.

Puedes escribir un conjunto sencillo de argumentos o puedes usar date_query para crear matrices anidadas y ejecutar consultas más complejas. Empecemos con los argumentos más simples.

Sencillos argumentos de fecha

Los parámetros que puedes usar para consultar en base a fechas son:

year (int): El año especificado con cuatro dígitos (por ej. 2015).
monthnum (int): Número de mes (del 1 a 12).
w (int): Semana del año (del 0 a 53). El modo depende de la opción "start_of_week" que puedes editar en tu página de Ajustes del escritorio de WordPress.
day (int): Día del mes (del 1 a 31).
hour (int): La hora (del 0 a 23).
minute (int): Minuto (del 0 a 60).
second (int): Segundos (0 a 60).
m (int): AñoMes (por ej. 201502).

Así que imagina que estás administrando un sitio de eventos que usa la fecha de publicación de cada evento para indicar la fecha de inicio del evento. Para mostrar todos los eventos, pasados y futuros, del 2015, aquí tienes los argumentos que necesitas:

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'year' => '2015'
);

Observa que he usado future y publish para el estado de las entradas, ya que las entradas programadas para fechas futuras no son consultadas por defecto.

O si quieres mostrar automáticamente eventos que tengan lugar este año, y no actualizar tu consulta cada año, podrías obtener primero el año actual y después pasar esto a los argumentos de tu consulta:

$current_year = the_date( 'Y' );

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'year' => $current_year
);

Argumentos complejos de fecha

Para utilizar varios parámetros de fecha para crear consultas más complejas, utiliza el parámetro date_query. Esto te da acceso a más parámetros:

year (int): Año de cuatro dígitos (por ej. 2015).
month (int): Número de mes (del 1 al 12).
week (int): Semana del año (del 0 al 53).
day (int): Día del mes (del 1 al 31).
hour (int): Hora (de 0 a 23).
minute (int): Minuto (de 0 a 59).
second (int): Segundo (0 a 59).
after (cadena/matriz): Fecha para recuperar entradas posteriores.
before (cadena/matriz): Fecha para recuperar entradas anteriores.
inclusive (booleano): Para posterior/anterior, indica si el valor exacto debe coincidir o no.
compare (cadena): Operador que se utiliza para comparar los datos de la base de datos con los argumentos. Los valores posibles son '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NO BETWEEN', 'EXISTS' Y 'NOT EXISTS'.
column (cadena): Columna de la base de datos con la que consultar: el valor predeterminado es 'post_date'.
relation (cadena): OR o AND, la manera en la que se deben comparar las submatrizes. El valor predeterminado es AND.

El parámetro date_query tiene el siguiente formato:

$args = array(
    'date_query' => array(
        array(
            // Arguments go here.        
        )
    )
);

También puedes crear varias matrices y definir cómo se compararán mediante el parámetro de relación. El ejemplo siguiente devolverá consultas que coincidan con los argumentos de ambas matrices:

$args = array(
    'date_query' => array(
        'relation' => 'AND',
        array(
            // Arguments go here.
        ),
        array(
            // Arguments go here.
        )
    )
);

Mientras que el código siguiente capturará las entradas que coinciden con los argumentos de cualquiera de las matrices (o con los de ambas):

$args = array(
    'date_query' => array(
        'relation' => 'OR',
        array(
            // Arguments go here.
        ),
        array(
            // Arguments go here.
        )
    )
);

Vamos a ilustrar esto con un ejemplo. Supongamos que estás trabajando en un sitio web de la universidad y deseas mostrar entradas de este año académico. El año académico se extiende del 1 de septiembre de 2014 al 31 de agosto de 2015, por lo que deberás encontrar entradas en los meses y años relevantes:

1	$args = array(
2	'date_query' => array(
3	'relation' => 'OR',
4	array(
5	'year' => '2014',
6	'month' => ( '9, 10, 11, 12' )
7	),
8	array(
9	'year' => '2015',
10	'month' => ( '1, 2, 3, 4, 5, 6, 7, 8' )
11	)
12	)
13	);

Ten en cuenta que el parámetro month toma una cadena para sus argumentos, no una matriz.

Los parámetros before y after

Una alternativa al ejemplo anterior es definir las fechas anteriores y/o posteriores de las cuales deseas mostrar las entradas, utilizando los parámetros before y after. Estos toman tres argumentos:

year (cadena): Acepta cualquier año de cuatro dígitos: vacío por defecto.
month (cadena): El mes del año (de 1 a 12). El valor predeterminado es 12.
day (cadena): El día del mes (de 1 a 31). El valor predeterminado es el último día del mes.

También puedes usar una cadena para la fecha, siempre y cuando sea compatible con el formato php strtotime.

Así que volviendo a mi ejemplo de mostrar entradas para este año académico, tengo dos opciones más. En primer lugar, podrías usar una matriz anidada con los parámetros year y month:

$args = array(
    'date_query' => array(
        'relation' => 'AND',
        array(
            'after' => array(
                'year' => '2014',
                'month' => '9'
            ),
            'inclusive' => true
        ),
        array(
            'before' => array(
                'year' => '2015',
                'month' => '8'
            ),
            'inclusive' => true
        )
    )
);

Aquí existen un par de cosas a tener en cuenta:

He utilizado 'relation' => 'AND' por que las entradas deben haber sido publicadas después de mi fecha de inicio y antes de mi fecha de finalización.
Para cada una de las matrices anidadas, he utilizado 'inclusive' => true para asegurarse de que WordPress recupera las entradas publicadas durante septiembre de 2014 y agosto de 2015.

También podría escribir esta consulta usando una cadena para las fechas:

$args = array(
    'date_query' => array(
        array(
            'after' => 'August 31st, 2014',
            'before' => 'September 1st, 2015',
            'inclusive' => false,
        )
    )
);

Ten en cuenta que debido a la forma en que funcionan las cadenas de fecha, es más confiable usar fechas exclusivas. Esto se debe a que si usas una cadena de fecha, se convertirá a 00:00 en esa fecha. Así que para que funcione, usa también la hora en tu cadena, o haz lo que he hecho y usa el día anterior a la fecha desde la que quieres mostrar las entradas (y posterior a la fecha en la que quieres mostrar las entradas hasta).

Algo más que puedes hacer con los parámetros de fecha es mostrar las entradas publicadas hoy mismo. Volviendo a mi sitio de eventos, supongamos que quiero mostrar un gran banner en mi página de inicio el día en que se está produciendo un evento. Puedo escribir una consulta para esto y luego mostrar detalles del evento si es que se encuentra uno. Estos son los argumentos:

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'date_query' => array(
        array(
            'year' => date( 'Y' ),
            'month' => date( 'M' ),
            'day' => date( 'D' )
        )
    )
);

El uso de la función date() devuelve la fecha actual: he usado esto tres veces para asegurarme de obtener el día, el mes y el año correctos. Ten en cuenta que también he incluido el argumento post_status para asegurar que se incluya un evento que se produce hoy más adelante.

Resumen

A veces no solo deseas consultar todas las entradas publicadas. Mediante el uso de la clase WP_Query puedes crear consultas mucho más específicas para mostrar entradas por fecha, incluidas las entradas que publicaste en una fecha determinada, antes de una fecha, después de una fecha o entre un par de fechas.

Los argumentos date_query se combinan con otros parámetros como post_status, que se tratan con más detalle en otras partes de esta serie.