Tech
Contact Form 7のフック一覧と実行順(6.2.3実測)
Contact Form 7のフックとフィルターを6.2.3の配布zipから機械的に抽出し、102個の内訳と送信1回で走る実行順を行番号つきで整理しました。
wpcf7_before_send_mailが効かない原因と、バージョン間の増減も実測で掲載します。
Contact Form 7 を少しでもカスタマイズしようとすると、必ずフックの話になります。
ところが「どんなフックがあるのか」を調べると、公式ドキュメントに載っているものと、ブログ記事で見かけるもの、すでに本体から消えているものが混ざって出てきます。
どれが今のバージョンに実在するのかが分からないまま、動かないコードを書いてしまう状態です。
この記事では配布zipを実際に取得し、PHPファイルからフック名を機械的に抽出して一覧化しました。
あわせて、送信1回で走るフックの実行順を本体コードの行番号つきで整理し、よく詰まる wpcf7_before_send_mail が効かない理由と、バージョン間での増減も実測で掲載します。
検証した環境
| 対象 | 値 |
|---|---|
| Contact Form 7 | 6.2.3(downloads.wordpress.org/plugin/contact-form-7.zip を2026-10-21に実取得) |
| 配布zipのmd5 | 68b35dd1c8c1946bf8ec85a56d1763c0(368,433バイト) |
| 比較に使った旧版 | 6.2.2(b1f76736a64607352e9c60fff6389320・368,658バイト)/6.0.6(a5ddd83bfbc40095cabaae35fcedadfc・297,094バイト)/5.9.8(5597a739e0b9538e18989f93375742d9・295,498バイト) |
| 抽出方法 | zip内の全.phpに対しapply_filters apply_filters_ref_array do_action do_action_ref_array の第1引数リテラルを抽出し重複排除 |
抽出に使ったコマンドはこれだけです。
手元で再現できます。
# 配布zipを取得して展開
curl -o contact-form-7.zip https://downloads.wordpress.org/plugin/contact-form-7.zip
unzip -q contact-form-7.zip -d cf7
# フィルター名を重複なく列挙
grep -rhoP "apply_filters(_ref_array)?\(\s*'\K[a-z0-9_]+" cf7/contact-form-7 --include=*.php | sort -u
# アクション名を重複なく列挙
grep -rhoP "do_action(_ref_array)?\(\s*'\K[a-z0-9_]+" cf7/contact-form-7 --include=*.php | sort -u
結果はフィルター74個、アクション28個、合計102個でした。
公式ドキュメントのフィルター一覧より多く、ドキュメント化されていないフックが相当数あります。
存在はしますが、将来の互換が約束されているわけではない点は前提にしてください。
送信1回で走るフックの実行順
カスタマイズで一番詰まるのは「どのタイミングで割り込むか」です。
6.2.3 の includes/submission.php の submit() がそのまま順序になっているので、行番号つきで並べます。
| 順 | フック | 場所(6.2.3) | 種類 |
|---|---|---|---|
| 1 | wpcf7_posted_data_{タイプ} | submission.php:395 | filter |
| 2 | wpcf7_posted_data | submission.php:408 | filter |
| 3 | wpcf7_validate_{タイプ} | submission.php:581 | filter |
| 4 | wpcf7_validate | submission.php:584 | filter |
| 5 | wpcf7_acceptance | submission.php:596 | filter |
| 6 | wpcf7_skip_spam_check | submission.php:630 | filter |
| 7 | wpcf7_spam | submission.php:666 | filter |
| 8 | wpcf7_before_send_mail | submission.php:715 | action(参照渡し) |
| 9 | wpcf7_skip_mail | submission.php:731 | filter |
| 10 | wpcf7_mail_components | mail.php:241 | filter |
| 11 | wpcf7_additional_mail | submission.php:751 | filter |
| 12 | wpcf7_mail_sent / wpcf7_mail_failed | submission.php:129 / 134 | action |
| 13 | wpcf7_submit | contact-form.php:1091 | action |
| 14 | wpcf7_submission_result | submission.php:204 | filter |
| 15 | wpcf7_feedback_response | rest-api.php:410 | filter |
この順序から読み取れることが3つあります。
1つ目は、スパム判定とバリデーションが wpcf7_before_send_mail より前に終わっていることです。
採番や外部API連携を wpcf7_before_send_mail に書けば、スパム送信や入力不備で無駄に走ることはありません。
逆に「スパム扱いにする条件を足したい」処理をここに書いても遅すぎます。
その場合は wpcf7_spam です。
2つ目は、メール本文の差し替えは wpcf7_mail_components だということです。wpcf7_before_send_mail で本文を変えようとしても、本文はまだ組み立てられていません。
宛先の振り分けも同様で、送信先を条件で変えたい場合は wpcf7_mail_components 側で触ります(詳しくはContact Form 7で宛先を条件によって振り分けるで扱っています)。
3つ目は、画面に返る文字列は最後の2つで決まることです。wpcf7_submission_result と wpcf7_feedback_response はどちらもレスポンス全体を触れるので、エラーメッセージの文面やフィールド単位のエラー表示を加工するならここになります。
フックを書く前に確認したいこと
フックで実装している機能が、設定だけで済むかもしれません
送信内容のデータベース保存、確認画面、マルチステップ、CSV書き出しは、Contact Form 7 では自分でフックを書く領域です。Frontierline Forms はこれらを無料版に含んでいるため、同じ要件を設定画面だけで満たせます。自作コードは本体のバージョンアップごとに検証が必要になるので、定番の要件は先にプラグイン側へ寄せて、本当に固有の処理だけフックで書く形が保守しやすくなります。
wpcf7_before_send_mailが効かない理由
「送信を条件で止めたい」という要件でこのフックを使うと、たいてい最初は止まりません。
原因は本体の呼び出し方にあります。
6.2.3 の includes/submission.php の715行目はこうなっています。
private function before_send_mail() {
$abort = false;
do_action_ref_array( 'wpcf7_before_send_mail', array(
$this->contact_form,
&$abort,
$this,
) );
return ! $abort;
}
do_action ではなく do_action_ref_array で、第2引数が &$abort と参照で渡されています。
つまり中止を伝える方法は戻り値ではなく、第2引数に true を代入することだけです。
しかも add_action で引数の数を指定しないと、コールバックには第1引数しか渡りません。
正しく書くとこうなります。
add_action( 'wpcf7_before_send_mail', 'fl_cf7_abort_on_condition', 10, 3 );
function fl_cf7_abort_on_condition( $contact_form, &$abort, $submission ) {
// 対象フォームだけに限定する(IDは管理画面のフォーム一覧で確認)
if ( 123 !== (int) $contact_form->id() ) {
return;
}
$posted = $submission->get_posted_data();
$email = isset( $posted['your-email'] ) ? (string) $posted['your-email'] : '';
// 受け付けないドメインなら送信自体を止める
if ( preg_match( '/@(example\.test|blocked\.test)$/i', $email ) ) {
$abort = true;
$submission->set_response(
'このメールアドレスからのお問い合わせはお受けできません。'
);
}
}
押さえておく点は4つです。
add_actionの第4引数に3を指定する。省略すると$abortに触れません。- 関数定義側で
&$abortと参照で受ける。値で受けると代入しても本体に戻りません。 - 中止したときの画面文言は
set_response()で差し替える。省略すると送信完了の文言が出たまま、メールだけ飛ばない状態になります。 $abort = trueにした場合のステータスはabortedです。wpcf7_mail_sentもwpcf7_mail_failedも発火しません。GA4のイベント計測をどちらかに紐づけている場合は、中止分が計測から落ちます。
入力値そのものを弾くなら、wpcf7_before_send_mail ではなくバリデーション側の方が利用者に親切です(Contact Form 7で独自のバリデーションを追加するで扱っています)。
送信を止めたい動機がスパムであれば、Contact Form 7のスパム対策の順序で先に設定を見直した方が確実です。
実務で使うフックの早見表
102個すべてを使うことはありません。
用途別に、実際に手が伸びるものを挙げます。
すべて 6.2.3 に実在することを確認済みです。
| やりたいこと | フック |
|---|---|
| 送信値を保存前に整形する(全角空白のtrimなど) | wpcf7_posted_data |
| 独自の入力チェックを足す | wpcf7_validate_{タイプ} |
| 独自条件でスパム扱いにする | wpcf7_spam |
| 特定条件でスパム判定だけ外す | wpcf7_skip_spam_check |
| 送信を中止する/外部APIへ連携する | wpcf7_before_send_mail |
| メールだけ送らない | wpcf7_skip_mail |
| 宛先・件名・本文・添付・ヘッダーを差し替える | wpcf7_mail_components |
独自のメールタグ([_xxx])を追加する | wpcf7_special_mail_tags |
| 画面に出すメッセージ文言を変える | wpcf7_messages / wpcf7_display_message |
| フォームのHTML全体に手を入れる | wpcf7_form_elements |
| アップロード先ディレクトリを変える | wpcf7_upload_dir |
| CSS・JSの読み込みを止める | wpcf7_load_css / wpcf7_load_js |
| 送信結果のレスポンスを加工する | wpcf7_submission_result / wpcf7_feedback_response |
| Flamingo保存時の項目を増やす | wpcf7_flamingo_inbound_message_parameters |
wpcf7_mail_components を使う場合は、自動返信メール(mail_2)にも同じフィルターが走る点に注意してください。
本体メールだけを対象にするなら $mail->name() で判別します。
add_filter( 'wpcf7_mail_components', 'fl_cf7_mail_components', 10, 3 );
function fl_cf7_mail_components( $components, $contact_form, $mail ) {
// 自動返信(mail_2)には適用しない
if ( 'mail' !== $mail->name() ) {
return $components;
}
$components['additional_headers'] .= "\nBcc: log@example.com";
return $components;
}
additional_headers は文字列です。
配列を代入すると送信時に落ちるので、改行で連結します。
バージョン間でフックは増減します
自作コードが本体更新で壊れる典型が、フック名の消滅です。
実測した増減は次のとおりです。
| 比較 | フック総数 | 差分 |
|---|---|---|
| 5.9.8 | 100 | — |
| 6.0.6 | 99 | — |
| 6.2.2 | 102 | — |
| 6.2.3 | 102 | 6.2.2から増減0 |
5.9.8 と 6.2.3 を比べると、wpcf7_constant_contact_submit と wpcf7_post_edit_form_tag の2つが消滅し、wpcf7_dashboard_setup、wpcf7_manage_custom_column、wpcf7_turnstile_secret、wpcf7_turnstile_sitekey の4つが増えています。
Turnstile関連が増えたのは、Cloudflare Turnstile のモジュールが本体に入った影響です。
6.2.2 から 6.2.3 への変更ではフックの増減はなく、差分のあったファイルは admin/includes/dashboard.php、includes/rest-api.php、includes/swv/js/index.js、readme.txt、vendor/composer/installed.php、wp-contact-form-7.php の6つでした。
フック依存のコードについては、このマイナー更新で壊れる箇所はありません。
運用としては、自作コードが使っているフック名を一覧にしておき、更新前に配布zipを取得して存在確認するのが最も確実です。
1行で済みます。
# 自作コードが依存するフック名が新バージョンに存在するか確認
for h in wpcf7_before_send_mail wpcf7_mail_components wpcf7_posted_data; do
printf '%s: ' "$h"
grep -rq "'$h'" cf7/contact-form-7 --include=*.php && echo OK || echo MISSING
done
まとめ
Contact Form 7 のフックは 6.2.3 時点で102個あり、そのうち実務で触るのは15個前後です。
順序は includes/submission.php の submit() がそのまま答えなので、迷ったら本体コードの行を見るのが最短です。wpcf7_before_send_mail が効かない原因はほぼ do_action_ref_array と引数の数の指定漏れで、add_action の第4引数に3を入れて &$abort で受ければ解決します。
そしてフックで実装した機能は、本体の更新ごとに検証コストが発生します。
送信内容の保存や確認画面のように要件として定番化しているものは、プラグイン側の設定で満たしておき、フックは本当に固有の処理だけに絞る方が長く保ちます。
Frontierline Forms
フックで書いた機能は、更新のたびに検証が必要になります
送信内容のデータベース保存・確認画面・マルチステップ・CSV書き出しは、Contact Form 7 では自作コードの領域です。Frontierline Forms はこれらを無料版に含んでいるため、本体のバージョンアップごとに自分のフックを検証する作業が不要になります。まず定番の要件をプラグインへ寄せて、残った固有処理だけをフックで書く構成にしてください。