wp_parse_args() │ WP 2.2.0

Combines two arrays so that the parameters of the first array (passed) replace the parameters of the second array (default) when they match. Parameters can be specified as a string.

Typically, an array with new parameters and an array with default parameters are passed to the function, and the function combines them. The first argument can accept parameters in the form of a string: text=текст&foo=нечто, which will be converted into an array.

This function is often used in other WordPress functions where default parameters and passed parameters are implied; such functions include get_posts(), wp_list_comments(), get_terms().

It is recommended to use this function in created functions where a list of parameters is passed. If each parameter is defined separately as is customary when registering a function, the list of parameters can become very long and inconvenient. In such cases, it is more convenient to specify one parameter $args for the function and within the function to specify the default parameters in an array. Then process the passed parameter using wp_parse_args(), thereby combining the passed parameters with the defaults (see the first example).

Uses: wp_parse_str()
Used By: register_rest_field()
1 time — 0.000018 sec (very fast) | 50000 times — 0.08 sec (speed of light) | PHP 7.1.5, WP 4.8.2

No Hooks.

Returns

Array.

Usage

$args = wp_parse_args( $args, $defaults );
$args(string/array/object) (required)

An array of parameters or a string of parameters that will overwrite the default parameters when they match.

A string is passed in the URL query string format:

$args = 'type=post&posts_per_page=5&cat=1';

An array is passed as usual:

$args = array( 'type'=>'post', 'posts_per_page'=>5, 'cat'=>'1' )

If an object is passed, the function will receive all its properties. The properties will become an array of parameters.

$args = (object) array( 'type'=>'post', 'posts_per_page'=>5, 'cat'=>'1' )
$defaults(array)

An array of default parameters that will be replaced by the parameters passed in $args.

Default: array()

Examples

0

#1 Demonstration of parameter transmission as a string 

$args = wp_parse_args( 'foo=val & bar=222' );

/*
$args = array {
  foo => string(4) "val "
  bar => string(2) "222"
}
*/

$args = wp_parse_args( 'foo=val & bar=222', [ 'bar' => 555, 'baz' => 999 ] );
var_dump( $args );
/*
$args = array {
  bar => string(3) "222"
  baz => int(999)
  foo => string(4) "val "
}
*/
0

#2 Passing function parameters and setting defaults

This example shows how to use this function to specify default function parameters and replace them if a parameter with the same key is passed.

function foo( $args ){

	// define the default parameters
	$defaults = array(
		'param1' => 'value',
		'param2' => true,
		'param3' => 3,
	);

	$args = wp_parse_args( $args, $defaults );

	print_r( $args );
}

foo( 'param1=value&param2=0' );

/* we get
Array(
	[param1] => value
	[param2] => 0
	[param3] => 3
)
*/

foo( [
	'param1' => 'something',
	'param2' => 0,
] );

/* we get
Array(
	[param1] => something
	[param2] => 0
	[param3] => 3
)
*/
0

#3 Usage Example

This function is used inside the function to define the parameters passed to the function. This example shows how passed parameters are combined with default parameters:

// define the default parameters
$defaults = array(
	'type'   => 'post',
	'before' => "<p>",
	'after'  => "</p> \n",
	'echo'   => TRUE
);

// merge the passed parameters into $args with the default parameters
$args = wp_parse_args( $args, $defaults );
0

#4 Demonstration of work

In this example, let's create a function that uses wp_parse_args(). And call main function with all allowed ways:

/**
 * Define a new function
 */
function explain_parse_args( $args ) {

	$defaults = array(
		'text' => 'wp_parse_args() combine $args and $defaults',
		'before' => "<p>",
		'after'  => "</p> \n",
		'echo'   => TRUE
	);

	// Get the incoming parameters and compare them with the base parameters
	$args = wp_parse_args( $args, $defaults );

	$output = $args['before'] . $args['text'] . $args['after'];

	if ( $echo ) {
		echo $output;
	}

	return $output;
}

/**
 * Call a function without parameters
 * The result is:
 * <p>wp_parse_args() combine $args and $defaults</p> \n
 */
explain_parse_args();

/**
 * Let's call the function and specify the parameters as an array
 * We get:
 *<p class='specialclass'>Best offer</p> \n
 */
explain_parse_args( array (
	'text' => 'Best Offer',
	'before' => "<p class='specialclass'>"
) );

/**
 * Let's call the functions and pass the parameters with a string
 * We get:
 * <p></p> \n
 */
explain_parse_args( 'echo=1&text=0' );

Changelog

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

wp_parse_args() code WP 6.9.1

wp-includes/functions.php 
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;
}

Helper Functions