タグアーカイブ PHP

WordPressのdo_action()を見直す イベントをオブジェクト化し、フックをクラス名にする最新の開発パターン

WordPressの開発でdo_action()を一度も使ったことがない人はまずいないだろう。カスタムフックを定義して他のプラグインやテーマから振る舞いを拡張する手法は、バージョン1.2で導入されて以来変わらず愛用されている。

しかし長年の使い込みの中で、いくつかの「小さな摩擦」が無視されてきたのも事実だ。引数の順序を覚えきれない、フック名が大域空間で衝突する、戻り値の返し忘れでフィルターが壊れる、といった問題は大規模なコードベースになるほど開発者の時間を食う。

この記事では、do_action()に1つのオブジェクトを渡し、そのクラス名をフック名として使うことで、これらの問題を一掃するパターンを解説する。独自のライブラリもフレームワークも不要で、PHPの標準機能だけで実装できる。2026年8月にDeveloper WordPress Newsで公開された洞察をもとに、実装例と仕組みを詳しく見ていこう。

do_action()で起きていた4つの摩擦

従来のdo_action()は「フック名」と「任意の数の引数」を受け取るシンプルなAPIだ。会員登録をトリガーとするプラグインであれば、次のようにフックを発火させるのが一般的な書き方になる。

do_action( 'myplugin_member_registered', $userId, $plan );

これを受け取る側のコードは以下のようになる。

add_action( 'myplugin_member_registered', static function ( $userId, $plan ) {
    // ... 何らかの処理
}, 10, 2 );

動作自体に問題はない。だが、よく見ると運用上のストレスがいくつも潜んでいる。Developer WordPress Newsの記事が指摘する摩擦点は大きく次の4つだ。

• 引数が位置に依存する　$userIdと$planの順序を覚えておかなければならず、間違えた場合のエラーは追跡しにくい。
• フック名がグローバルな名前空間　'myplugin_member_registered'という文字列が他のプラグインと衝突しないよう、prefixをつけて管理する必要がある。
• 型情報が一切ない　$planは文字列かもしれないしIDかもしれない。コードエディタの補完も静的解析も効かず、ドキュメントを読まなければ正体がわからない。
• フィルターの戻り値忘れ　apply_filters()を使うと、どのリスナーも必ず値を返さなければならない。うっかりreturnを書き忘れると、後続のフィルターがすべて破綻する。

これらはフックの仕組みそのものの問題ではなく、ペイロード（運ぶデータ）の渡し方に起因する。そして、このペイロード設計を見直すだけで、すべてがきれいに解決する。

上の比較でわかるとおり、do_action()に渡す情報をオブジェクトにまとめるだけで多くの摩擦が消える。フック名の衝突リスクがなくなり、コードエディタの補完も効く。

イベントオブジェクトとクラス名フック　1行で変わる設計

解決策の核心は驚くほど単純だ。Developer WordPress Newsの記事の著者が試みたのは、「引数をバラバラに渡すのではなく、起こった出来事を表すオブジェクトを1つだけ渡す」というやり方である。

具体的には、次のように書く。

do_action( $event::class, $event );

$event::classが何が起きたかを示すフック名になり、$eventがその詳細を運ぶ。フック名にはそのクラスの完全修飾名が使われるため、名前空間が自動的に適用され、他のプラグインと衝突することはまずない。

フック名を::classで決めるか、あるいは固定の文字列にするかは選択できる。クラス名を使えば、IDEでクラスをリネームするとフックも追従する。文字列（例：'myplugin/member-registered'）を指定すれば、後からクラスを移動させてもフック名は変わらない。移行の危険を減らしたいなら固定文字列のほうが安全だが、どちらにせよペイロードは整ったオブジェクトになる。

また、このテクニックはapply_filters()を使わなくてもフィルター的な振る舞いを実現できる。オブジェクトのプロパティを書き換え可能にしておけば、リスナーが自由に値を変更し、ディスパッチャ側が後から読み取れるからだ。戻り値の管理に頭を悩ませる必要がなくなる。

具体例　会員登録のDispatcherとListener

ここでは会員登録を題材に、イベントオブジェクトを使ったフックの流れを具体的に見ていこう。名前空間MyPlugin\Membersの下に、登録イベントを表すクラスと、それを発行するクラス、そして受け取る側のコードを用意する。

イベントクラスの定義

namespace MyPlugin\Members;

final class MemberRegistered
{
    public function __construct(
        public readonly int    $userId,
        public readonly string $plan,
        public          bool   $sendWelcomeEmail = true,
    ) {}
}

$userIdと$planはreadonlyとして宣言され、リスナーは読み取り専用で使用する。一方、$sendWelcomeEmailは書き換え可能にしておき、ウェルカムメールを送るかどうかの判断をリスナーに委ねる。

Dispatcher（発行側）

namespace MyPlugin\Members;

final class MemberRegistrar
{
    public function register( int $userId, string $plan ): void
    {
        // アカウント作成処理...

        $event = new MemberRegistered( userId: $userId, plan: $plan );

        do_action( $event::class, $event );

        if ( $event->sendWelcomeEmail ) {
            // ウェルカムメールをキューに追加
        }
    }
}

ポイントは、do_action()の後で$event->sendWelcomeEmailを評価しているところだ。この値は後続のリスナーが変更したかもしれない。オブジェクトは参照で渡されるため、ディスパッチャはリスナーによる変更をそのまま拾える。ここにapply_filters()は必要ない。

ObserverとMutatorの2パターン

受け側はおおまかに2種類に分かれる。1つはイベントを観測するだけのObserverで、値を読み取るが変更はしない。もう1つはプロパティを書き換えるMutatorだ。

// Observer　ログ出力のみ
add_action( MemberRegistered::class, static function ( MemberRegistered $event ): void {
    error_log( sprintf(
        'Member #%d registered on the %s plan.',
        $event->userId,
        $event->plan
    ) );
} );

// Mutator　無料プランの場合はウェルカムメールを無効化
add_action( MemberRegistered::class, function ( MemberRegistered $event ): void {
    if ( 'free' === $event->plan ) {
        $event->sendWelcomeEmail = false;
    }
} );

Mutatorのコールバックを見ると、型ヒントによって$eventのプロパティが自動補完されることがわかる。$userIdや$planの順序を気にする必要はなく、add_action()の第4引数で引数の数を指定する手間もない。これがオブジェクト化の地味ながら大きな恩恵だ。

このように、1つのオブジェクトを受け渡すだけで、従来のアクションとフィルターの両方の役割を統一的に扱える。コードの見通しは飛躍的に良くなるはずだ。

オブジェクト化がもたらすメリットのまとめ

これまでの例から、イベントオブジェクトパターンを採用することで得られる具体的な利点を整理する。

• 型安全なリスナー　すべてのコールバックがイベントクラスで型を宣言するため、エディタの補完と静的解析がフルに働く。
• 名前衝突からの解放　フック名は完全修飾クラス名（または明示的な文字列）で管理されるため、prefixを手動で付ける必要がなくなる。
• フィルターのような書き換えをアクションで実現　オブジェクトのプロパティをミュータブルにしておけば、apply_filters()を使わずとも値の変更が可能。戻り値の返し忘れによるバグも消える。
• 自己文書化　各イベントクラスが独立したファイルになるため、どの拡張ポイントが存在するかがディレクトリを見るだけで把握できる。

これらの改善は、特別なライブラリを導入しなくても、今日から自社のプラグインに適用できる。既存のdo_action()やadd_action()をそのまま使いつつ、ペイロードをオブジェクトに切り替えるだけだ。

WordPressのルーツとPSR-14の関係

このパターンを「新しいアイデア」と感じるかもしれないが、実はWordPressが2004年のバージョン1.2で搭載したプラグインAPIの時点で、根幹の設計は既に存在していた。

PHPの世界でPSR-14（Event Dispatcher）として標準化された「イベント、リスナー、ディスパッチャ」の概念は、do_action()とadd_action()の組み合わせでほぼ表現できる。つまり、WordPressはとっくにイベント駆動の基盤を持っていたことになる。

PSR-14が定める厳密な契約（伝播制御、リスナープロバイダー、ディスパッチャの交換など）はWordPressには組み込まれていない。だが、「イベントをオブジェクトで表現し、そのクラス名でフックする」という発想は、PSR-14のイベントモデルと驚くほど調和する。結果として、WordPressのネイティブな関数の上に、よりモダンで安全なイベント設計を載せられるわけだ。

Developer WordPress Newsの記事の著者も、PSR-14を完全実装する試みの中で、大半の価値がこの小さな習慣に詰まっていることに気づいたと述べている。段階的な移行が可能で、いきなり大掛かりなフレームワークに乗り換える必要はない。

このパターンの限界と発展の方向性

ここまでのテクニックで、自作プラグインのカスタムフックの多くは十分に改善できる。ただし、次のような高度な要件に直面したときは、より本格的なイベントシステムの導入を検討してもいい。

• 伝播の停止　あるリスナーが「以降のリスナーは実行するな」と指示する仕組み。これはremove_action()と優先度では再現しきれない場面がある。
• 複雑なリスナー管理　数十個のリスナーを手作業で登録するのではなく、1つのサブスクライバークラスにまとめて登録したいケース。
• テストのための差し替え　ディスパッチャ自体を丸ごと入れ替えて、イベントの発生をテストダブルで差し替えたい状況。

これらの必要性を感じ始めた時が、PSR-14準拠のディスパッチャを導入する潮時といえる。しかし、そこに至るまでは、「do_action()にオブジェクトを渡す」習慣だけで、保守性も開発体験も大きく前進させられる。

今日からすぐに実践できる小さな設計変更が、コードベースの品質を長期にわたって支える土台になる。次のカスタムフックを書くときに、このパターンをぜひ試してみてほしい。

この記事のポイント

• do_action()にバラバラの引数ではなく1つのイベントオブジェクトを渡すと、引数の順序問題や型の不明瞭さが解消される。
• フック名にクラスの完全修飾名を使うことで、名前空間が自然に確保され、衝突リスクが劇的に下がる。
• オブジェクトの書き換え可能プロパティを利用すれば、apply_filters()を使わずにフィルター的な挙動を安全に実装できる。
• オブザーバーとミューテーターの2種類のリスナーを型安全に記述でき、コードエディタの補完がフルに働く。
• PSR-14のような本格的なイベントシステムを導入しなくても、小さな習慣を変えるだけで開発体験が大幅に改善する。

海田 洋祐

・ 複数業界における17年間のデジタルビジネス開発経験
・ ウェブサイト開発のためのHTML、PHP、CSS、JavaScript等の実用的知識
・ 15ヶ国語対応の多言語SaaSの開発経験
・ 17年間にも及ぶ、Eコマース長期運営経験
・ 幅広い業界でのSEO最適化の豊富な経験

www.aandgweb.co.jp