apply_filters_ref_array()

apply_filters_ref_array() は WordPress のフィルター処理において、引数を参照渡しで渡す必要があるケースや、配列形式でまとめて引数を処理したい場合に利用されます。

可変引数よりも制御しやすく、パフォーマンスや柔軟性の点でも有用です。

機能の説明

この関数は、通常の apply_filters() の代わりに使うことで、複数の引数を1つの配列としてまとめて渡し、それらを参照渡しで変更可能にする機能を提供します。

主な用途

• 引数をフィルター処理内で変更し、呼び出し元に反映させたい場合
• 引数の数が多くなることが想定される場合

シンプルなコード例

$data = [ 'key' => 'value' ];
apply_filters_ref_array( 'my_filter', [ &$data ] );

この例では $data をフィルターで変更でき、その変更が元の $data に反映されます。

使い方の説明

基本構文

apply_filters_ref_array(
  string $hook_name,
  array  $args
): mixed

引数解説

使用例

function modify_data( &$data ) {
  $data['key'] = 'filtered';
  return $data;
}
add_filter( 'my_filter', 'modify_data' );

$data = [ 'key' => 'original' ];
$data = apply_filters_ref_array( 'my_filter', [ &$data ] );

echo $data['key']; // 結果: filtered

一緒に使うことが多い関連タグ

add_filter()

add_filter( 'my_filter', function( &$data ) {
  $data['updated'] = true;
  return $data;
} );

• 通常の add_filter() と組み合わせて使えます。
• コールバック関数では必ず参照渡しで受け取るようにすること。

追加情報で取得したい場合

apply_filters() との比較

// 引数を参照ではなく値渡しで渡す
$data = apply_filters( 'my_filter', $data );

• apply_filters() では $data の変更が元の変数に反映されない
• apply_filters_ref_array() では参照で渡せる

複数引数を使う

function update_values( &$value1, &$value2 ) {
  $value1 .= ' changed';
  $value2 += 10;
}
add_filter( 'multi_ref_filter', function( $args ) {
  update_values( $args[0], $args[1] );
  return $args;
} );

$var1 = 'text';
$var2 = 5;
apply_filters_ref_array( 'multi_ref_filter', [ &$var1, &$var2 ] );

// $var1 = 'text changed'
// $var2 = 15

このテンプレートタグを利用してのカスタマイズ

多次元配列やオブジェクトの操作に強い

$post_data = [
  'title' => '初期タイトル',
  'content' => '初期コンテンツ'
];

apply_filters_ref_array( 'filter_post_data', [ &$post_data ] );

• 大きな配列やオブジェクトを処理する場合、値渡しよりも高速かつ柔軟
• WP_REST_Request などと組み合わせても有効

想定されるトラブル

参照渡しになっていない

引数に & を付けずに渡すと、フィルター内で変更しても元に反映されません。

解決方法

apply_filters_ref_array() の第2引数の配列に渡す変数に必ず & を付けて参照渡しにしてください。

コールバック関数内で直接参照渡しされていない

解決方法

function( $args ) のままだと $args 内の配列の参照は保証されません。必要に応じて function( &$args ) や &$args[0] など明示的に参照指定が必要です。

Q＆A

まとめ

apply_filters_ref_array() は、複数の引数を配列形式で参照渡しできる特殊なフィルター適用関数です。

通常の apply_filters() では実現しづらい引数の柔軟な操作が可能になり、特に配列やオブジェクトのフィルタリング処理、高機能なコールバック処理で威力を発揮します。

参照渡しが必要な場面だけに限定して使い、構文ミスを避けることで、堅牢で柔軟なコードが書けるようになります。