WordPress get_posts es una poderosa función que permite a los desarrolladores recuperar piezas de contenido de la base de datos de WordPress. Puede especificar hasta el último detalle qué mensajes, páginas y tipos de mensajes personalizados está buscando, obtener su conjunto de resultados personalizado y, a continuación, filtrar y ordenar los elementos como un ninja PHP/MySQL.

Pero no se asuste si no es un profesional de PHP, existen innumerables tutoriales de PHP que puedes ver o leer y aprender el lenguaje. Sólo necesita un poco de conocimiento de PHP para crear listas personalizadas de mensajes para mostrar en su sitio web, ya que la función get_posts mantiene una serie de parámetros que permiten crear consultas simples o avanzadas.

El uso de get_posts de WordPress es un proceso de dos pasos:

  • Primero, tiene que crear su consulta personalizada. En realidad, no parecerá una consulta MySQL, y no escribirá ninguna instrucción SELECT. Sólo necesita definir una matriz de parámetros y pasarla a la función get_posts. WordPress convierte esa matriz en una consulta MySQL real y segura, la ejecuta contra la base de datos y devuelve una matriz de mensajes.
  • Segundo, tiene que recorrer el conjunto de resultados devuelto por get_posts con un ciclo de foreach.

Dicho esto, en este post, primero nos adentraremos en los conceptos clave mencionados anteriormente, específicamente cómo funciona get_posts, cómo construir una consulta personalizada, y cómo mostrar los datos en el sitio principal.
Luego, le proporcionaré un ejemplo del mundo real con un fragmento de código que puede obtener, editar y usar en su entorno de preparación para sus pruebas y desarrollo.

Nota: Normalmente diferenciamos entre mensajes, páginas y tipos de mensajes personalizados. En este artículo, utilizamos el término `posts’ para los blogs regulares, así como para las páginas y los tipos de post personalizados. Todos estos tipos de mensajes se almacenan en la tabla ‘wp_posts’ de la base de datos. La principal diferencia entre los tipos de puestos está en el valor del campo ‘post_type’. Desde la perspectiva de un desarrollador, los mensajes, las páginas y los tipos de mensajes personalizados son todos mensajes.

Introducción a la Función get_posts de WordPress

El Codex describe la función get_posts de la siguiente manera:

Recupera una matriz de los últimos mensajes, o mensajes que corresponden a los criterios dados.

Podemos usar get_posts de esta manera:

$args = array(
	'numberposts'	=> 20,
	'category'		=> 4
);
$my_posts = get_posts( $args );

if( ! empty( $my_posts ) ){
	$output = '<ul>';
	foreach ( $my_posts as $p ){
		$output .= '<li><a href="' . get_permalink( $p->ID ) . '">' 
		. $p->post_title . '</a></li>';
	}
	$output .= '<ul>';
}

La función anterior recupera las últimas 20 entradas de blog en la categoría especificada (por defecto el 'post_type' es 'post') y devuelve una matriz de objetos $post. Puede iterar sobre la matriz para mostrar los mensajes en la pantalla. Es bastante fácil, ¿verdad?

get_posts usa WP_Query para recuperar los elementos del mensaje, y mantiene una matriz de los mismos parámetros disponibles en WP_Query (con pocas excepciones). Así que tenemos una lista enorme de variables que podemos usar para construir nuestras consultas personalizadas. Estos parámetros se agrupan en las siguientes 15 categorías:

  • Parámetros de autor
  • Categoría Parámetros
  • Parámetros de la etiqueta
  • Parámetros de Taxonomía
  • Parámetros de búsqueda
  • Parámetros de publicación y página
  • Parámetros de la contraseña
  • Parámetros del tipo de puesto
  • Orden y parámetros Orderby
  • Parámetros de fecha
  • Parámetros de campo personalizado (post meta)
  • Parámetros de permiso
  • Parámetros del tipo de mímica
  • Parámetros de almacenamiento en caché
  • Parámetro de campos de retorno

Un rápido vistazo a la lista anterior le puede dar una idea de la variedad de consultas personalizadas que puede crear y ejecutar contra la base de datos de WordPress. Por lo tanto, vamos a profundizar en los parámetros de consulta y empezar a construir nuestras listas de mensajes.

¿Cómo Crear Consultas con WordPress get_posts?

Cada categoría de parámetros se refiere a la misma información. Por ejemplo, podemos construir una consulta para recuperar mensajes de los autores especificados o excluir a los autores especificados, definiendo el autor por ID o nombre de usuario. De la misma manera, podemos construir consultas que obtengan entradas por categoría, etiqueta, taxonomía, fecha, campos personalizados e incluso más.

¿Cómo Utilizar los Parámetros para Crear Consultas Simples?

Muchos parámetros se pueden utilizar de forma muy similar, independientemente de la categoría a la que pertenezcan. Por ejemplo, los siguientes parámetros permiten consultar la base de datos por autor(es) del mensaje:

  • author (int) – ID del autor
  • author_name (string) – user_nicename del autor
  • author__in (array) – una serie de IDs de múltiples autores
  • author__not_in (array) – una matriz de múltiples IDs de autores que se excluirán del conjunto de resultados

¿Cómo podemos utilizar estos parámetros?

En el siguiente ejemplo, el parámetro 'author' especifica que queremos que las entradas de blog más recientes sean escritas por el autor con ID = 1:

$my_posts = get_posts( array( 'author' => 1 ) );

El mismo parámetro ‘author’ permite consultar la base de datos de diferentes maneras:

// return an array of posts from specific authors
$my_posts = get_posts( array( 'author' => '1,5,12' ) );
// return an array of posts excluding the specified author
$my_posts = get_posts( array( 'author' => -1 ) );

Así, dependiendo del valor del parámetro, tendrá un conjunto de resultados con mensajes de un solo autor (entero), de varios autores (una lista de valores separados por comas) o excluyendo a un autor (valores negativos).

Otros parámetros proporcionan flexibilidad adicional. Por ejemplo, la siguiente llamada a get_posts devuelve una matriz de las últimas entradas de múltiples autores:

// return an array of posts from multiple authors
$my_posts = get_posts( array( 'author__in' => array( 1, 5, 12 ) ) );

Y también podemos excluir a múltiples autores:

// return an array of posts from multiple authors
$my_posts = get_posts( array( 'author__not_in' => array( 1, 5, 12 ) ) );

Del mismo modo, podemos usar parámetros de categoría, parámetros de etiquetas, parámetros de tipo post, con algunas diferencias específicas. Véase, a modo de ejemplo, los parámetros de categoría:

  • cat (int)
  • category_name (string)
  • category__and (array)
  • category__in (array)
  • category__not_in (array)

De todos modos, no todos los parámetros son tan fáciles de usar como estos parámetros. Además, podemos utilizar parámetros de categoría, parámetros de tipo post, parámetros de tipo mime, etc. todo en una sola consulta. Esto significa que tenemos un control granular sobre los elementos del conjunto de resultados, y podemos crear consultas más avanzadas basadas en tipos de mensajes, taxonomías personalizadas y campos personalizados en conjunto.

Así que, profundicemos más.

¿Cómo Crear Consultas Avanzadas en WordPress?

Vamos a dar un paso adelante con una consulta más avanzada basada en tipos de mensajes personalizados y taxonomías personalizadas. Digamos que tiene el siguiente tipo de puesto:

nombre: book
nombre de la taxonomía: book_category, book_author
soporte para: title, editor, thumbnail, excerpt, custom-fields

Tipos de Postes Personalizados y Taxonomías Personalizadas

Suponga que desea una lista de los libros más recientes en la taxonomía personalizada book_category especificada. Aquí está el conjunto de argumentos:

$args = array(
	'post_type'		=> 'book',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug',
			'terms'		=> 'sci-fi'
		)
	),
);

Los argumentos anteriores simplemente le dicen a WordPress que recupere todos los libros en 'sci-fi' 'book_category'.

El parámetro 'tax_query' toma una matriz de matrices de argumentos (es decir, una matriz de matrices). Estas matrices anidadas permiten construir consultas muy complejas basadas en múltiples taxonomías, como se muestra en el siguiente ejemplo:

$args = array(
	'numberposts'	=> 10,
	'post_type'		=> 'book',
	'relation'		=> 'AND',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug',
			'terms'		=> 'sci-fi'
		),
		array(
			'taxonomy'	=> 'book_author',
			'field'		=> 'term_id',
			'terms'		=> 22
		)
	)
);

Estos parámetros nos permiten recuperar una lista de los últimos 10 'book' en la 'sci-fi' 'book_category', escrita por el 'book_author' con ID #22. El parámetro 'relation' establece la relación lógica entre cada taxonomía listada en 'tax_query'. Arriba fijamos su valor en AND porque necesitamos recuperar todos los libros que pertenecen a la categoría de 'sci-fi' AND escritos por el autor #22.

¿Cómo Crear Metaconsultas Utilizando Parámetros de Campo Personalizados?

Ocasionalmente, es posible que necesite crear listas de mensajes basadas en una clave y/o valor de campo personalizado específico.

$args = array(
	'meta_key'		=> 'cover',
	'meta_value'	=> 'paperback',
	'meta_compare'	=> '='
);

Estos parámetros nos permiten recuperar todos los mensajes por clave y valor de campo personalizado. 'meta_compare' establece el operador requerido para probar el valor del parámetro 'meta_value'. Aqui 'meta_value' es '=', que es también el valor por defecto.

Los valores disponibles son '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' o 'RLIKE'.

Este es un ejemplo bastante fácil, pero podemos construir consultas más avanzadas. En el siguiente ejemplo, buscamos en la base de datos de libros de fantasía publicados después de 2010:

$args = array(
	'post_type'		=> 'book',
	'meta_key'		=> 'year_published',
	'meta_value_num'	=> 2010,
	'meta_compare'	=> '>',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug'
			'terms'		=> 'fantasy'
		)
	)
);

Y podemos ir aún más lejos. En el siguiente ejemplo estamos mezclando un tipo de mensaje con una taxonomía personalizada y dos campos personalizados:

$args = array(
	'post_type'		=> 'book',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug'
			'terms'		=> array( 'fantasy' )
		)
	),
	'meta_query'	=> array(
		'relation'		=> 'AND',
		array(
			'key'		=> 'year_published',
			'value'		=> 2010,
			'type'		=> 'numeric',
			'compare'	=> '>',
		),
		array(
			'key'		=> 'price',
			'value'		=> array( 10, 25 ),
			'type'		=> 'numeric',
			'compare'	=> 'BETWEEN',
		)
	)
);

Aquí establecemos una serie de parámetros para recuperar una lista de libros de fantasía publicados después de 2010 que cuestan BETWEEN 10 y 25 dólares.

Puede ver que el parámetro 'meta_query' funciona de forma muy parecida al parámetro 'tax_query'. Mantiene una serie de matrices, lo que nos permite crear consultas avanzadas basadas en múltiples pares meta clave/valor. Para una lista completa de parámetros de consulta y un buen número de ejemplos, véase la documentación WP_Query.

¿Por Qué get_posts está Limitado a 5 Mensajes de WordPress?

La función get_posts toma los mismos argumentos que WP_Query::parse_query() (ver el Codex), pero algunos parámetros específicos hacen que funcione ligeramente diferente de un objeto WP_Query.

Tal vez no usó el parámetro 'numberposts' en sus consultas y le estás preguntando por qué sólo ve 5 ítems en su lista.

De forma predeterminada, el número de mensajes que configure en la página de administración de Lectura de → Determina el número de mensajes que se recuperarán mediante una consulta de WordPress. De todas formas, si no especifica un valor personalizado para 'numberposts' o 'posts_per_page', get_posts devuelve un número diferente de mensajes.

  • Se entenderá por 'numberposts' el número total de posts que deben recuperarse. Es un alias de 'posts_per_page' en WP_Query, pero hay una diferencia entre los dos: por defecto, el número de mensajes a recuperar al usar get_posts es 5, mientras que `posts_per_page' en WP_Query propone por defecto el número de mensajes por página de su blog de WordPress. Puede redefinir el valor predeterminado estableciendo un valor personalizado para 'numberposts' o 'posts_per_page' en la matriz de argumentos.

Además de 'numberposts', los siguientes parámetros son específicos de get_posts:

  • La'category' es una lista de ID de categoría separada por comas. Es un alias del parámetro 'cat' en WP_Query.
  • 'include' es una lista de IDs separados por comas. Este es un alias del parámetro 'post__in' en WP_Query.
  • 'exclude' es una lista de ID de mensajes separada por comas.
  • 'suppress_filters' especifica si se deben suprimir los filtros. Este parámetro por defecto es true en get_posts, mientras que por defecto es false en WP_Query (ver en Track).

La función get_posts está definida en wp-includes/post.php. Puede profundizar en cómo funciona get_posts revisando el código fuente en Track (WordPress 5.2) o en su instalación local de WordPress.

Pedidos de Artículos

'orderby' y 'order' clasifican los elementos del conjunto de resultados. Puede ordenar las entradas por 'ID', 'author', 'title', 'name', 'type', 'date', 'modified', 'parent', 'rand', 'comment_count' y de muchas otras maneras, en orden ascendente o descendente.

Si tiene una consulta simple, sólo necesita establecer un valor para 'order' y 'orderby'. En el siguiente ejemplo, los mensajes se clasifican por nombre de mensaje en orden ascendente:

$args = array(
	'author'	=> '1,5,12',
	'orderby'	=> 'name',
	'order'		=> 'ASC'
);

Eso es bastante sencillo. Pero, ¿y si tuviera una consulta avanzada? Es decir, ¿podemos ordenar los elementos por uno o más valores de campo personalizados en una metaconsulta avanzada?

WordPress 4.0 y WordPress 4.2 han aportado importantes mejoras a los parámetros ‘orderby’ y ‘meta_query’. Ahora tenemos una nueva sintaxis para ordenar por cláusulas específicas de una metaconsulta. Gracias a la nueva sintaxis, podemos utilizar índices para crear referencias a cláusulas específicas de la metaconsulta desde el parámetro `ordenby’.

Gracias a estas mejoras, la meta consulta del ejemplo anterior se puede escribir de la siguiente manera:

$args = array(
	'meta_query'	=> array(
		'relation'		=> 'AND',
		'year_clause' => array(
			'key'		=> 'year_published',
			'value'		=> 2010,
			'type'		=> 'numeric',
			'compare'	=> '>',
		),
		'price_clause' => array(
			'key'		=> 'price',
			'value'		=> array( 10, 25 ),
			'type'		=> 'numeric',
			'compare'	=> 'BETWEEN',
		)
	),
	'orderby' => 'price_clause',
);

En el ejemplo anterior hemos ordenado los elementos por 'price_clause'.

Y podemos hacer aún más. A partir de WordPress 4.0, podemos pasar a get_posts una matriz de meta índices de consulta en lugar de un único índice, como se ve en el ejemplo de abajo:

$args = array(
	'meta_query'	=> array(
		'relation'		=> 'AND',
		'year_clause' => array(
			'key'		=> 'year_published',
			'value'		=> 2010,
			'type'		=> 'numeric',
			'compare'	=> '>',
		),
		'price_clause' => array(
			'key'		=> 'price',
			'value'		=> array( 10, 25 ),
			'type'		=> 'numeric',
			'compare'	=> 'BETWEEN',
		)
	),
	'orderby' => array( 'price_clause' => 'ASC', 'year_clause' => 'DESC' ),
);

Enhorabuena, ha creado una metaconsulta avanzada, y ordenado los resultados primero por 'price_clause' en orden ascendente, luego por 'year_clause' en orden descendente.

Véase la lista completa de opciones de clasificación en el Codex.

Es hora de mostrar los datos en la primera página.

Lectura sugerida: ¿Cómo Crear y Usar Fácilmente una Página phpinfo?.

¿Cómo Mostrar los Datos Devueltos de get_posts?

WordPress get_posts devuelve una matriz de objetos WP_Post que nos da acceso a un número de variables para cada mensaje seleccionado almacenado en la tabla de base de datos wp_posts:

  • ID
  • post_author
  • post_name
  • post_type
  • post_title
  • post_date
  • post_date_gmt
  • post_content
  • post_excerpt
  • post_status
  • comment_status
  • ping_status
  • post_password
  • post_parent
  • post_modified
  • post_modified_gmt
  • comment_count
  • menu_order
Estructura de la tabla wp_posts en phpMyAdmin
Estructura de la tabla wp_posts en phpMyAdmin

Usted puede acceder fácilmente a estos datos con un ciclo de foreach como el siguiente:

$custom_posts = get_posts( $args );

if( ! empty( $custom_posts ) ){
	$output = '<ul>';
	foreach ( $custom_posts as $p ){

		$output .= '<li><a href="' 
		. get_permalink( $p->ID ) . '">' 
		. $p->post_title . '</a></li>';
	}

	$output .= '</ul>';
}

return $output ?? '<strong>Sorry. No posts matching your criteria!</strong>';

Si get_posts encontró al menos una entrada, devuelva una matriz de elementos que podemos atravesar para mostrar el título de la entrada y un enlace a la entrada original. Usamos la función get_permalink para recuperar el permalink del post, ya que no tenemos una variable WP_Post correspondiente.

Eso es bastante fácil, pero ¿cómo podemos implementar ese código y construir nuestras listas personalizadas de mensajes usando WordPress get_posts?

Puede mostrar listas de mensajes en sus páginas de varias maneras.

Ejemplo del Mundo Real: ¿Cómo Mostrar una Lista Personalizada de Elementos con un Código Abreviado?

Le mostraré cómo construir un atajo rápido y fácil que puede incluir en Su contenido. De todos modos, no voy a profundizar en los códigos abreviados, ya que ya cubrimos ese tema en una entrada anterior del blog.

En primer lugar, cree un nuevo directorio en la carpeta wp-content/plugins de su instalación local de WordPress o en un entorno de preparación. En este ejemplo, he nombrado el directorio kinsta-shortcodes.

En wp-content/plugins/kinsta-shortcodes/ crear un archivo.php con el mismo nombre que el nuevo directorio: kinsta-shortcodes.php.

Abra el nuevo archivo en su editor de texto favorito e incluya el siguiente encabezado:

<?php
/**
 * @package Kinsta_shortcodes
 * @version 1.0
 */
/*
Plugin Name: Kinsta shortcodes
Plugin URI: http://wordpress.org/extend/plugins/#
Description: This is an example plugin 
Author: Your Name
Version: 1.0
Author URI: https://yourwebsite.com/
*/

Ahora tenemos un nuevo plugin, pero sigue sin hacer nada. Busque la pantalla de administración de plugins en el panel de control de WordPress y active el nuevo plugin asegurándose de que WP_DEBUG está configurado como verdadero en su archivo wp-config.php.

Su sandbox está ahora listo para sus guardias. El siguiente paso es registrar un gancho para un código abreviado personalizado:

/**
 * Add a hook for a shortcode tag
 */
function kinsta_shortcodes_init(){
	add_shortcode( 'kinsta_get_posts', 'kinsta_get_posts_cb' );
}
add_action('init', 'kinsta_shortcodes_init');

kinsta_get_posts es el nombre del código abreviado y kinsta_get_posts_cb es la llamada de retorno definida a continuación:

/**
 * Register a shortcode
 *
 * @param array $atts Array of shortcode attributes
 */
function kinsta_get_posts_cb( $atts ){

	// safely extract custom arguments and set default values
	extract( shortcode_atts(
			array(
				'numberposts'		=> 3,
				'post_type'			=> 'post',
				'book_category'		=> 'fantasy',
				'year_published'	=> 1900,
				'price_min'			=> 0,
				'price_max'			=> 50
			),
			$atts,
			'kinsta_get_posts'
		) );

	// define the array of query arguments
	$args = array(
		'numberposts'	=> $numberposts,
		'post_type'		=> $post_type,
		'tax_query'		=> array(
			array(
				'taxonomy'	=> 'book_category',
				'field'		=> 'slug',
				'terms'		=> $book_category,
			)
		),
		'meta_query'	=> array(
			'relation'		=> 'AND',
			'year_clause'	=> array(
				'key'		=> 'year_published',
				'value'		=> $year_published,
				'type'		=> 'numeric',
				'compare'	=> '>',
			),
			'price_clause'	=> array(
				'key'		=> 'price',
				'value'		=> array( $price_min, $price_max ),
				'type'		=> 'numeric',
				'compare'	=> 'BETWEEN',
			)
		),
		'orderby' => array( 'price_clause' => 'ASC' )
	);

	$custom_posts = get_posts( $args );

	if( ! empty( $custom_posts ) ){
		$output = '<ul>';
		foreach ( $custom_posts as $p ){

			$output .= '<li><a href="' 
			. get_permalink( $p->ID ) . '">' 
			. $p->post_title . '</a> (' 
			. get_post_meta( $p->ID, 'year_published', true ) 
			. ') - Price: ' . get_post_meta( $p->ID, 'price', true ) . '</li>';
		}

		$output .= '</ul>';
	}

return $output ?? '<strong>Sorry. No posts matching your criteria!</strong>';

Establecemos seis atributos de código abreviado que usamos para definir una matriz de parámetros, que finalmente se pasa a la función WordPress get_posts. Si $custom_posts no está vacío, entonces un ciclo foreach genera el HTML de una lista desordenada de elementos.

Ahora usted y los autores de su blog pueden incluir listas de mensajes utilizando un código abreviado como el siguiente:

[kinsta_get_posts post_type="book" book_category="sci-fi" numberposts="4" price_min=1 price_max=250]

Por supuesto, puede cambiar el conjunto de argumentos a su gusto y ejecutar sus pruebas en cualquier puesto o página de su sitio web de desarrollo.

Una lista avanzada de mensajes creados con la función get_posts
Una lista avanzada de mensajes creados con la función get_posts

Resumen

get_posts de WordPress es una potente función que permite a los desarrolladores incluir listas de mensajes en cualquier parte de la interfaz de su sitio web de WordPress. Utiliza WP_Query pero es más fácil de usar y es preferible a WP_Query cuando sólo necesita listas de mensajes. De todos modos, se recomienda una referencia directa a WP_Query cuando necesite mostrar posts en un Loop.

Así que, construya sus listas, pruebe su código, y cuando esté seguro de que funciona bien, entonces (y sólo entonces) empújelo a su sitio web en vivo (pero primero haga una copia de seguridad).

Ahora nos gustaría saber de usted. ¿Cuál es su experiencia con la función get_posts de WordPress? ¿Tiene algún caso de uso para compartir con nosotros? Hágalo en los comentarios de abajo!

Carlo Daniele Kinsta

Carlo es un diseñador y desarrollador de front-end freelance. Cuando escribe artículos y tutoriales, Carlo se ocupa principalmente de los estándares web, pero cuando juega con sitios web, su mejor compañero de trabajo es WordPress.