wp_parse_args( string|array|object $args, array $defaults = array() ): array

Merges user defined arguments into defaults array.

Description

This function is used throughout WordPress to allow for both string or array to be merged into another array.

Parameters

$argsstring|array|objectrequired
Value to merge with $defaults.
$defaultsarrayoptional
Array that serves as the defaults.

Default:array()

Return

array Merged user defined values with defaults.

More Information

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.

Source

function wp_parse_args( $args, $defaults = array() ) {
	if ( is_object( $args ) ) {
		$parsed_args = get_object_vars( $args );
	} elseif ( is_array( $args ) ) {
		$parsed_args =& $args;
	} else {
		wp_parse_str( $args, $parsed_args );
	}

	if ( is_array( $defaults ) && $defaults ) {
		return array_merge( $defaults, $parsed_args );
	}
	return $parsed_args;
}

Changelog

VersionDescription
2.3.0$args can now also be an object.
2.2.0Introduced.

User Contributed Notes

  1. Skip to note 5 content

    Basic usage:

    function wpdocs_my_function( $args ) {
    
      $defaults = array(
        'name' => 'Mr. nobody',
        'favorite_color' => 'unknown',
        'age' => 'unknown',
      );
    
      $args = wp_parse_args( $args, $defaults );
    
      print_r( $args );
    
    }
    
    $args = array( 'age' => 36 );
    wpdocs_my_function( $args );
    
    // Output:
    // 
    // Array(
    //   'name' => 'Mr. nobody',
    //   'favorite_color' => 'unknown',
    //   'age' => 36,
    // )
  2. Skip to note 7 content

    Below is an example function using the wp_parse_args system to manage its single $args argument, which could be given whatever values you wanted.
    In this case $args stores detailed display overrides, a pattern found in many WordPress functions.

    /**
     * Define a new function that uses $args and wp_parse_args()
     */
    function wpdocs_explain_parse_args( $args ) {
    	$defaults = array (
    		'text' => 'wp_parse_args() merges $args into $defaults',
    		'before' => "<p>",
    		'after' => "</p> \n",
     		'echo' => TRUE
    	);
    	
    	// Parse incoming $args into an array and merge it with $defaults
    	$args = wp_parse_args( $args, $defaults );
    	
    	$output = $args['before'] . $args['text'] . $args['after'];
    	
    	if (!$echo) 
    		return $output;
    	
    	echo $output;
    }
    
    /**
     * Run our new function using the defaults (no $args)
     * This would print out: 
     * 	<p>wp_parse_args() merges $args into $defaults</p>
     */
    wpdocs_explain_parse_args();
    
    /**
     * Run the function with some options overridden with an array
     * This would echo the output with the modified text and before arguments:
     * 	<p class='specialclass'>A better explanation</p>
     */
    wpdocs_explain_parse_args( array (
    	'text' => "A better explanation",
    	'before' => "<p class='specialclass'>"
    ) );
    
    /**
     * We can also pass in URL-style string-query and it will be converted
     * This would set $args['echo'] to 1 and $args['text'] to 0	
     */
    wpdocs_explain_parse_args( 'echo=1&text=0' );
  3. Skip to note 8 content

    If you are looking to recursively merge two arrays, here is the function:

    if ( ! function_exists( 'wpdocs_recursive_parse_args' ) ) {
    	function wpdocs_recursive_parse_args( $args, $defaults ) {
    		$new_args = (array) $defaults;
    
    		foreach ( $args as $key => $value ) {
    			if ( is_array( $value ) && isset( $new_args[ $key ] ) ) {
    				$new_args[ $key ] = wpdocs_recursive_parse_args( $value, $new_args[ $key ] );
    			}
    			else {
    				$new_args[ $key ] = $value;
    			}
    		}
    
    		return $new_args;
    	}
    }

    Test case:

    $defaults = [
    	'x1' => 'level1',
    	'x2' => [
    		'a1' => 'level1',
    		'a2' => 'level1',
    	],
    	'x4' => [
    		'b1' => [
    			'c1' => 'level1',
    		],
    		'b2' => 'level1',
    	],
    	'x3' => 'level1',
    ];
    $args     = [
    	'x3' => 'level2',
    	'x2' => [
    		'a2' => 'level2',
    	],
    	'x4' => [
    		'b1' => [
    			'c1' => 'level2',
    			'c2' => 'leve2',
    			'c3' => [
    				'd1' => [
    					'e1' => 'ok',
    				],
    			],
    		],
    	],
    ];
    
    print_r( awps_recursive_parse_args( $args, $defaults );
    
    /**
     * Result
     */
    /*
    [
    	'x1' => 'level1',
    	'x2' => [
    		'a1' => 'level1',
    		'a2' => 'level2',
    	],
    	'x4' => [
    		'b1' => [
    			'c1' => 'level2',
    			'c2' => 'leve2',
    			'c3' => [
    				'd1' => [
    					'e1' => 'ok',
    				],
    			],
    		],
    		'b2' => 'level1',
    	],
    	'x3' => 'level2',
    ];
    */

You must log in before being able to contribute a note or feedback.