Using the wp_parse_id_list() WordPress Function

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.