While developing my plugin, I came across many API of new WordPress 3. WordPress 3 really gives a new set of APIs for developers to work with. Okay, so coming straight to the point, there are many occasions where, you need to take input of comma separated values of IDs from the user for the backend of your plugin.
While, we can use PHP’s simple explode method to convert the CSV into an array, but it relies extensively on the users input for any possible error. For example, user is expected to list down some IDs like this:
But, if he enters in the form of say
then there will be lots of error while passing through explode and then directly using the array.
As of WordPress 3, it gives a nice and handy API to pass such user input and get a nicely sanitized array of unique ids. The function is called wp_parse_id_list. Lets see how it works…
#1: Working with wp_parse_id_list:
The usage is very straight forward. Say, we took a CSV of IDs from a form using POST method, through the settings page of our plugin. We just pass the user input like this:
<?php
if( $_SERVER['REQUEST_METHOD'] == 'POST' ) {
$id_csv = $_POST['id_csv']; //Get the list of ID from the user
$id_csv = wp_parse_id_list( $id_csv );
}
?>
As easy as that. For a practical example, I am using this on my new widget (which is coming really soon) plugin like this…
function widget( $args, $instance ) {
extract($args);
/**
* Get the CSV sticky and exclude post from the instance
*/
$wp_cpl_sticky = wp_parse_id_list($instance['sticky_post']);
$wp_cpl_exclude = wp_parse_id_list($instance['exclude_post']);
/**
* Other codes
*/
}
#2: Adding support of wp_parse_id_list to WP version prior to 3:
The function was introduced to wordpress 3.0. What if you want to make your plugin compatible with versions prior to 3? It is really a bad idea to make your plugin depend extensively on WordPress 3 only, just because of one single function.
So, what we do is, we define the function, in case it is not already defined. Just add the following code, to your plugin php file.
if( ! function_exists( 'wp_parse_id_list' ) ) {
function wp_parse_id_list( $list ) {
if ( !is_array($list) )
$list = preg_split('/[\s,]+/', $list);
return array_unique(array_map('absint', $list));
}
}
Pretty easy!
#3: Actual location, source and concept of the wp_parse_id_list:
The function is located at /wp-includes/functions.php file. The source code is as follows:
/**
* Clean up an array, comma- or space-separated list of IDs
*
* @since 3.0.0
*
* @param array|string $list
* @return array Sanitized array of IDs
*/
function wp_parse_id_list( $list ) {
if ( !is_array($list) )
$list = preg_split('/[\s,]+/', $list);
return array_unique(array_map('absint', $list));
}
What it does it, splits string on occurrence of space or comma, and returns a sorted array with unique integer values. It therefore, strips off any duplicate id, and properly fetch ids from improperly written ID list as well. So, if you user writes
Then also, 12, 44, 56, 57, 69 IDs will be fetched as an array.
Array
(
[0] => 12
[1] => 44
[2] => 56
[4] => 57
[6] => 69
)
Also, note that it uses another function absint, which was first introduced on WordPress 2.5.0 and located on the same /wp-includes/functions.php file. It is also a simple API and the source code is something like this:
/**
* Converts value to nonnegative integer.
*
* @since 2.5.0
*
* @param mixed $maybeint Data you wish to have convered to an nonnegative integer
* @return int An nonnegative integer
*/
function absint( $maybeint ) {
return abs( intval( $maybeint ) );
}
So, that was all about this new API. Hope it was useful to you. Do give your feedback and if you have any doubt, feel free to drop in.
