• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/wp parse args

提供: WordPress Codex 日本語版
移動先: 案内検索

この項目「関数リファレンス/wp parse args」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

wp_parse_args は、引数の配列とデフォルト値の配列を結合するための汎用の関数です。 URL クエリ形式の文字列(例えば "id=5&status=draft")を与えて配列形式へ変換することもできます。

これはデフォルトや入力値の処理に気を揉まずに、渡された引数を一定のパターンに整えることができるよう、WordPress 全体で使われます。 query_posts wp_list_comments get_terms のような関数が、wp_parse_args の「シンプルにするパワー」を利用した一般的な例です。

とても多くの引数を持つ関数は、良いデフォルト値が用意されていて稀にしか変更しなくて済む場合でも(すべての引数を指定しなければならないので)関数の呼び出しが非常に長くなって面倒です。 しかし $args (配列)形式のパラメータを持つ関数は、受け取れる引数を(仕組みの上では)無限に増やすことができるので、シンプルに呼び出すことができます。

使い方

wp_parse_args() は、あなたが定義する関数の中で、与えられた引数を処理するために使います。 下記の例は、どのように wp_parse_args() を使って、デフォルト値の配列と値が混在した引数の配列を結合できるかを示します。

/**
 * デフォルト値の配列を定義
 */ 
$defaults = array(
	'type' => 'post',
	'before' => "<p>",
	'after' => "</p> \n",
	'echo' => TRUE
);

/**
 * 与えられた $args を解析して配列に入れ、$defaults と結合
 */ 
$args = wp_parse_args( $args, $defaults );

/**
 * オプション:$args の要素を変数として宣言。例えば $type, $before のように。
 */ 
extract( $args, EXTR_SKIP );

パラメータ

$args
配列|文字列) (必須) クエリ形式の文字列、または値が混在した引数の配列。$defaults 内の値を上書きする。
初期値: なし
  • URL クエリ形式の例
type=post&posts_per_page=5&cat=1
  • 配列形式の例
array( 'type' => 'post', 'posts_per_page' => 5, 'cat' => '1' )
$defaults
配列) (必須) デフォルト値の配列。$args で上書きされる。
初期値: なし

用例

下記は、一つの $args 引数を使って好きな値を何でも指定できるように wp_parse_args を利用する関数の例です。 この例では、多くの WordPress 関数で見られるような、デフォルトの表示内容を変更する文字列を $args に入れます。

/**
 * $args と wp_parse_args() を使う新しい関数を定義
 */
function explain_parse_args( $args ) {
	$defaults = array (
 		'text' => 'wp_parse_args() が $args を $defaults に結合します',
 		'before' => "<p>",
 		'after' => "</p> \n",
 		'echo' => TRUE
	);
	
	// 与えられた $args を解析して配列に入れ、$defaults と結合
	$args = wp_parse_args( $args, $defaults );
	
	// $args の要素を変数として宣言:$text, $before, $after, $echo
	extract( $args, EXTR_SKIP );

	$output = $before . $text . $after;
	
	if (!$echo) 
		return $output;
	
	echo $output;
}

/**
 * 定義した関数をデフォルトのまま使う($args を指定しない)
 * このように表示される:
 * 	<p>wp_parse_args() が $args を $defaults に結合します</p>
 */
explain_parse_args();

/**
 * 幾つかのオプションを配列で上書きして同じ関数を実行
 * $text と $before が変更されて表示される:
 * 	<p class='specialclass'>もっと良い説明</p>
 */
explain_parse_args( array (
	'text' => "もっと良い説明",
	'before' => "<p class='specialclass'>"
) );

/**
 * URL 形式のクエリ文字列として引数を与えることもできる
 * 変換されて $args['echo'] が 1, $args['text'] が 0 になる
 */
explain_parse_args( 'echo=1&text=0' );

変更履歴

2.2.0 にて導入されました。

ソースファイル

wp_parse_args()wp-includes/functions.php にあります。

shortcode_atts() / en


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/wp_parse_args最新版との差分