wp_parse_args() │ WP 2.2.0

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.

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.

Return

Array. Merged user defined values with defaults.

Usage

wp_parse_args( $args, $defaults );
$args(string|array|object) (required)
Value to merge with $defaults.
$defaults(array)
Array that serves as the defaults.
Default: empty 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.1.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