What does wp_parse_args do?

Question

I've been building Wordpress widgets for a while and have always used some code like this:

$instance = wp_parse_args( (array) $instance);

It's never caused problems and is recommended in several places (by Justin Tadlock, two Wordpress books I have, etc.), but none of these sources really explain why.

So, what does this actually do, and what would happen if it was omitted?

score 14 · Accepted Answer · answered Aug 21 '12 at 18:15

In layman's terms it's merging arrays.

It's used frequently because it allows a function to accept multiple arguments without making the code look messy. Then goes the next step by allowing the developer to set up default values.

That's where wp_parse_args comes in, it merges passed in values with defaults.

$args = wp_parse_args($passed_in_args, $default_values);

It also converts a URL query string into an array.

Hope this helps

score 8 · Answer 2 · edited Jul 20 '20 at 23:00

https://developer.wordpress.org/reference/functions/wp_parse_args/

wp_parse_args is a generic utility for merging together an array of arguments and an array of default values. It can also be given a URL query type string which will be converted into an array (i.e. "id=5&status=draft").

It is used throughout WordPress to avoid having to worry about the logic of defaults and input, and produces a stable pattern for passing arguments around. Functions like query_posts, wp_list_comments and get_terms are common examples of the simplifying power of wp_parse_args.

Functions that have an $args based setting are able to infinitely expand the number of values that can potentially be passed into them, avoiding the annoyance of super-long function calls because there are too many arguments to keep track of, many of whose only function is to override usually-good defaults on rare occasions.

In general it is simplifying function call, to avoid long code checking appearance/existence and default values of variables passed as arguments

score 5 · Answer 3 · edited Apr 16 '20 at 13:12

5

This is the code in wordpress's wp-includes/functions.php file:

/**
 * Merge user defined arguments into defaults array.
 *
 * This function is used throughout WordPress to allow for both string or array
 * to be merged into another array.
 *
 * @since 2.2.0
 *
 * @param string|array $args Value to merge with $defaults
 * @param array $defaults Array that serves as the defaults.
 * @return array Merged user defined values with defaults.
 */
function wp_parse_args( $args, $defaults = '' ) {
    if ( is_object( $args ) )
        $r = get_object_vars( $args );
    elseif ( is_array( $args ) )
        $r =& $args;
    else
        wp_parse_str( $args, $r );

    if ( is_array( $defaults ) )
        return array_merge( $defaults, $r );

    return $r;
}

edited Apr 16 '20 at 13:12

Eje

354
4
8

answered Sep 11 '11 at 15:03

steve

608
1
5
16

3

This isn't a true answer as it stands. The code might stand for itself, but nevertheless some explanation should be added. At least put something like the function comments above, which inexperienced developers might skim over. – SunnyRed Oct 01 '13 at 19:15
so this has no value to be pointed out, without explanations.. – Maxime Culea Jun 30 '21 at 15:33

What does wp_parse_args do?

3 Answers3