wp_parse_args() │ WP 2.2.0

Объединяет два массива, так что параметры первого массива (передаваемые) заменяют при совпадении параметры второго массива (по умолчанию). Параметры можно указать строкой.

Обычно в функцию передается массив с новыми параметрами и массив с параметрами по умолчанию и функция их объединяет. В первом аргументе можно передать параметры в виде строки: text=текст&foo=нечто, они будут преобразованы в массив.

Эта функция часто используется в других функция WordPress, в которых подразумеваются параметры по умолчанию и передаваемые параметры, к таким функциям можно отнести get_posts(), wp_list_comments(), get_terms().

Функцию рекомендуется использовать в создаваемых функциях, в которые передается список параметров. Если определять каждый параметр отдельно как это принято при регистрации функции, то список параметров может быть очень длинным и неудобным. В таких случаях удобнее указать для функции один параметр $args и внутри функции в массиве указать параметры по-умолчанию. Затем обработать передаваемый параметр с помощью wp_parse_args(), тем самым объединив передаваемые параметры с дефолтными (см. первый пример).

Работает на основе: wp_parse_str()
Основа для: register_rest_field()
1 раз — 0.000018 сек (очень быстро) | 50000 раз — 0.08 сек (скорость света) | PHP 7.1.5, WP 4.8.2

Хуков нет.

Возвращает

Массив.

Использование

$args = wp_parse_args( $args, $defaults );
$args(строка/массив/объект) (обязательный)

Массив параметров или строка параметров, которые перезапишут при совпадении параметры по умолчанию.

Строка передается в формате строки запроса УРЛ:

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

Массив передается как обычно:

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

Если передать какой-то объект, то функция получит все его свойства. Свойства станут массивом параметров.

$args = (object) array( 'type'=>'post', 'posts_per_page'=>5, 'cat'=>'1' )
$defaults(массив)

Массив параметров по умолчанию, которые будут заменены на параметры передаваемые в $args.

По умолчанию: array()'

Примеры

1

#1 Демонстрация передачи параметров в виде строки 

$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 Передача параметров функции и установка дефолтных

Этот пример показывает как с помощью функции wp_parse_args() указать параметры функции по умолчанию и заменять их если передан параметр с таким же ключом.

function foo( $args ){
	// определим параметры по умолчанию
	$defaults = array(
		'param1' => 'значение',
		'param2' => true,
		'param3' => 3,
	);

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

	print_r( $args );
}

foo( 'param1=значение&param2=0' );

/* получим
Array(
	[param1] => значение
	[param2] => 0
	[param3] => 3
)
*/

foo( [
	'param1' => 'нечто',
	'param2' => 0,
] );
/* получим
Array(
	[param1] => нечто
	[param2] => 0
	[param3] => 3
)
*/
0

#3 Пример использования wp_parse_args

wp_parse_args() используется внутри функции, для определения передаваемые в функцию параметров. Этот пример показывает как передаваемые параметры объединяются с параметрами по умолчанию:

// определим параметры по умолчанию
$defaults = array(
	'type' => 'post',
	'before' => "<p>",
	'after' => "</p> \n",
	'echo' => TRUE
);

// объединим переданные параметры в $args с параметрами по умолчанию
$args = wp_parse_args( $args, $defaults );
0

#4 Демонстрация работы

В этом примере создадим функцию, которая использует wp_parse_args() и вызовем её в разных вариантах:

/**
 * Определим новую функцию
 */
function explain_parse_args( $args ) {

	$defaults = array(
		'text'   => 'wp_parse_args() объединим $args и $defaults',
		'before' => "<p>",
		'after'  => "</p> \n",
		'echo'   => TRUE
	);

	// Получим входящие параметры и сравним их с базовыми
	$args = wp_parse_args( $args, $defaults );

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

	if ( ! $echo )
		return $output;

	echo $output;
}

/**
 * Вызовем функцию без параметров
 * В результате получим:
 * <p>wp_parse_args() объединим $args и $defaults</p> \n
 */
explain_parse_args();

/**
 * Вызовем функцию и укажем параметры в виде массива
 * Получим:
 * <p class='specialclass'>Лучшее предложение</p> \n
 */
explain_parse_args( array (
	'text' => "Лучшее предложение",
	'before' => "<p class='specialclass'>"
) );

/**
 * Вызовем функции и передадим параметры строкой
 * Получим:
 * <p></p> \n
 */
explain_parse_args( 'echo=1&text=0' );

Список изменений

С версии 2.2.0 Введена.
С версии 2.3.0 $args can now also be an object.

Код wp_parse_args() WP 6.5.2

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

Вспомогательные