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


(string|array|object) (Required) Value to merge with $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;
		wp_parse_str( $args, $r );

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

Top ↑

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>
     * 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.