The wp_parse_id_list()
WordPress function will take an array or string containing post IDs and return a cleaned-up and sanitized array of post IDs.
Function Overview
wp_parse_id_list( array|string $list )
$list
(array) (Required) List of IDs.
Return: (array) Sanitized array of IDs.
Sample Usage
Let’s start with a simple array of post IDs:
$list = array( 1, 13, '11', 13 );
At first glance, you will notice that one of these IDs is a string and that 13 is duplicated. So, lets run the list through wp_parse_id_list()
:
wp_parse_id_list( $list );
The result of running our list through wp_parse_id_list()
is this:
array( 1, 13, 11 )
As you can see, the result is an array of integers with completely unique values.
Use Case: MySQL IN Clause
One great use for this function is in a MySQL IN clause. In fact, this is the primary usage within WordPress core.
Here is a sample pulled directly from WordPress core:
$where[] = 'post_author IN ( ' . implode( ',', wp_parse_id_list( $this->query_vars['post_author__in'] ) ) . ' )';
Note: This will work equally well with post IDs, user IDs, comment IDs, or anything where an array of unique integers is required.
Use Case: Shortcode ID List
One great use case for the wp_parse_id_list()
function is when you have a shortcode that accepts one or more post IDs. For example:
add_shortcode( 'my_shortcode', function ( $atts, $content ) {
$atts = shortcode_atts( array( 'post_ids' => '' ), $atts );
$query = new WP_Query( array(
'post__in' => array_filter( wp_parse_id_list( $atts['post_ids'] ) ),
'ignore_sticky_posts' => true,
) );
$output = '';;
if ( $query->have_posts() ) {
$output .= '<p>';
while ( $query->have_posts() ) {
$query->the_post();
$output .= esc_html( $query->post->post_title ) . '<br />';
}
$output .= '</p>';
}
return $output;
} );
Now, a user could use your shortcode like this:
[my_shortcode post_ids="1"]
or with multiple IDs, like this:
[my_shortcode post_ids="1,2,3"]
or, if a user failed to use commas and used spaces instead, that would work as well:
[my_shortcode post_ids="1 2 3"]
or, if a user mixed approaches or even added too many spaces, that would work as well:
[my_shortcode post_ids="1, 2 3 4"]
or, if a user duplicated an ID in the list, it would automatically be removed:
[my_shortcode post_ids="1 2 3 3"]
There are only two scenarios where wp_parse_id_list()
will fail to properly clean up an ID list. The first is when a user adds leading or trailing spaces to an ID list in string form:
[my_shortcode post_ids="1 2 3 "]
Doing this will add a 0 to the array, which obviously isn’t a valid post ID.
The second is when a user explicitly adds 0 to an ID list:
[my_shortcode post_ids="0 1 2 3"]
For this reason, I don’t use wp_parse_id_list()
on its own, but with array_filter()
, like this:
array_filter( wp_parse_id_list( $post_ids ) )
Doing so ensures that 0 will never make it into the list of IDs.