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

Merge user defined arguments into defaults array.


Description Description

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


Parameters Parameters

$args

(string|array|object) (Required) Value to merge with $defaults.

$defaults

(array) (Optional) Array that serves as the defaults.

Default value: ''


Top ↑

Return Return

(array) Merged user defined values with defaults.


Top ↑

Source Source

File: wp-includes/functions.php

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;
}

Top ↑

Changelog Changelog

Changelog
Version Description
2.3.0 $args can now also be an object.
2.2.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note content
    Contributed by Codex

    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' );
    
    

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