メインコンテンツまでスキップ

PHP フックリファレンス

Form Plant は、送信処理・メール送信・リダイレクト・ファイルアップロード・フィールド・フォーム設定など、フォーム動作のほぼすべての段階に WordPress の アクション / フィルターフック を用意しています。functions.php などにフックを追加するだけで、プラグイン本体を改変せずに挙動を拡張・カスタマイズできます。

バリデーション専用フックは別ページ

入力検証 ( fplant_validate_* / fplant_validation_message_* 等) のフックは バリデーションフック (PHP) にまとめています。本ページではそれ以外のフックを扱います。

MW WP Form から移行する方へ

mwform_* フックからの書き換え対応表と before / after の例は MW WP Form からの移行 にあります。あわせてご覧ください。

フックの基本​

フォームの絞り込み​

多くのフックはサイト内の全フォームで発火します。特定のフォームだけを対象にしたい場合は、コールバック内でフォーム ID ( $form_id ) を判定してください。フォーム ID は設置ショートコード [fplant id="12"] や編集画面 URL ( ...&id=12 ) の数値です。

add_filter( 'fplant_redirect_url', function ( $url, $form_id, $data ) {
    if ( 12 !== $form_id ) {
        return $url; // 対象フォーム以外はそのまま返す
    }
    return home_url( '/thanks/' );
}, 10, 3 );

フィールド名で狙うフック (動的フック)​

一部のフックは フィールド名を末尾に付けて、特定フィールドだけを対象にできます ( 例: fplant_field_choices_{name} )。これらは内部的に「全フィールド共通版 → フィールド別版」の 2 段で呼ばれ、フィールド別版は共通版の戻り値を受け取ります。

  • 共通版: fplant_field_choices … 引数に $field_name を含む
  • フィールド別版: fplant_field_choices_お問い合わせ種別 のように名前を埋め込む
フィールド名は英数字キー

フック名やコールバックで使うフィールド名は、フォーム編集画面で確認できる name (英数字キー) です。MW WP Form から移行した場合、日本語名は英数字に変換されています ( 例: お名前 → your_name ) 。

フォームの表示・送信制御​

v1.2.1 以降、フォームは公開ステータス ( post status ) を尊重します。公開 (publish) のフォームは誰でも表示・送信でき、非公開・下書き・レビュー待ちのフォームは一般訪問者には表示・送信されず、そのフォームを編集できるユーザーだけがプレビュー・テスト送信できます。この判定は次のフィルターで上書きできます。

フック種別引数用途
fplant_form_is_viewablefilter( $viewable, $form )フォームをフロントに表示してよいか 🆕
fplant_form_is_submittablefilter( $submittable, $form )フォームが送信を受け付けるか 🆕
fplant_preview_noticefilter( $notice, $form )未公開フォームの上に出るプレビュー注記の HTML 🆕

$form は id や status を含むフォーム配列です。true を返すとステータスに関わらず表示・送信を許可します。

非公開フォームを編集権限者が表示すると、上部に「このフォームは未公開です」というプレビュー注記が出ます。fplant_preview_notice で文言を差し替えたり、空文字を返して非表示にできます。会員限定フォーム ( fplant_form_is_viewable で会員に表示を許可 ) のように、編集者以外にも表示するケースで便利です。

例: 従来どおり全ステータスのフォームを表示・送信可能に戻す​

add_filter( 'fplant_form_is_viewable', '__return_true' );
add_filter( 'fplant_form_is_submittable', '__return_true' );

例: 特定フォームだけ非公開でも表示する​

add_filter( 'fplant_form_is_viewable', function ( $viewable, $form ) {
    if ( 12 === (int) $form['id'] ) {
        return true;
    }
    return $viewable;
}, 10, 2 );

例: 会員限定フォーム ( ログイン会員にだけ非公開フォームを見せる )​

非公開フォームをログイン会員に表示・送信させ、編集者向けのプレビュー注記は消す例です。

// フォーム ID 12 を、ログインしていれば誰でも表示・送信できるようにする
add_filter( 'fplant_form_is_viewable', function ( $viewable, $form ) {
    return ( 12 === (int) $form['id'] && is_user_logged_in() ) ? true : $viewable;
}, 10, 2 );

add_filter( 'fplant_form_is_submittable', function ( $submittable, $form ) {
    return ( 12 === (int) $form['id'] && is_user_logged_in() ) ? true : $submittable;
}, 10, 2 );

// 会員には「未公開」プレビュー注記を出さない
add_filter( 'fplant_preview_notice', function ( $notice, $form ) {
    return ( 12 === (int) $form['id'] ) ? '' : $notice;
}, 10, 2 );

送信ライフサイクル​

フォーム送信は次の順序で処理されます。各段階にフックが用意されています。■ アクション / ■ フィルター で色分けしています。

フック種別引数タイミング・用途
fplant_before_submissionaction( $form_id, $data )バリデーション前。生データのロギングや前処理に
fplant_submission_datafilter( $data, $form_id )サニタイズ直後のデータ加工。戻り値 = 加工後のデータ
fplant_before_save_submission_datafilter( $data, $form_id )DB 保存直前のデータ加工 ( パスワードのマスク前 ) 。特定キーを unset して保存対象から除外する用途にも。戻り値 = 保存用データ
fplant_after_submissionaction( $submission_id, $form_id, $data )DB 保存後・メール送信前
fplant_after_submission_completeaction( $data, $form_id, $form, $submission_id )メール送信まで完了した後。外部サービス連携の定番フック

例: 送信完了後に外部サービスへ連携する​

add_action( 'fplant_after_submission_complete', function ( $data, $form_id, $form, $submission_id ) {
    if ( 12 !== $form_id ) {
        return;
    }
    // 例: Slack やCRM へ通知
    wp_remote_post( 'https://example.com/webhook', array(
        'body' => array(
            'submission_id' => $submission_id,
            'email'         => $data['email'] ?? '',
        ),
        'timeout' => 5,
    ) );
}, 10, 4 );

例: 特定の項目を DB に保存しない​

add_filter( 'fplant_before_save_submission_data', function ( $data, $form_id ) {
    // クレジットカード番号など、保存したくない項目を除外
    unset( $data['card_number'] );
    return $data;
}, 10, 2 );

送信後アクション (完了メッセージ・リダイレクト)​

フォーム設定の「送信後のアクション」に応じて、いずれか 1 つが発火します。すべて v1.2.0 で追加されました。

フック種別引数有効になる設定
fplant_complete_messagefilter( $message, $form_id, $data )「メッセージ」
fplant_success_htmlfilter( $html, $form_id, $data )「カスタムページ」 ( プレースホルダ置換後の HTML )
fplant_redirect_urlfilter( $url, $form_id, $data )「リダイレクト」 ( esc_url_raw 前 )

例: 入力値に応じて完了メッセージを変える​

add_filter( 'fplant_complete_message', function ( $message, $form_id, $data ) {
    if ( 12 === $form_id ) {
        $name    = $data['your_name'] ?? 'お客';
        $message = $name . ' 様、お問い合わせありがとうございました。';
    }
    return $message;
}, 10, 3 );

例: プランに応じてリダイレクト先を分岐​

add_filter( 'fplant_redirect_url', function ( $url, $form_id, $data ) {
    if ( 12 === $form_id && 'premium' === ( $data['plan'] ?? '' ) ) {
        $url = home_url( '/thanks-premium/' );
    }
    return $url;
}, 10, 3 );

メール送信​

管理者メールと自動返信 ( ユーザー ) メールで、対になるフックが用意されています。admin を user に置き換えると自動返信側のフックになります。

フック種別引数用途
fplant_before_admin_email_sendaction( $email_settings, $form_id )管理者メール送信処理の冒頭
fplant_skip_admin_emailfilter( $skip, $form, $data, $submission_id )true を返すと送信スキップ 🆕
fplant_before_send_email_datafilter( $data, $form, $submission_id, $type )本文生成前のデータ加工。$type は 'admin' / 'user' ( 共通フック )
fplant_admin_email_tofilter( $to, $form_id, $data )管理者の宛先 ( 配列 ) 。空配列で送信スキップ 🆕
fplant_admin_email_subjectfilter( $subject, $form_id )件名 ( 第 3 引数なし )
fplant_admin_email_bodyfilter( $message, $form_id, $data )本文
fplant_admin_email_headersfilter( $headers, $form_id, $data )ヘッダ ( From / Cc / Bcc / Reply-To ) 🆕
fplant_after_admin_email_sendaction( $email_settings, $form_id, $result )wp_mail() 実行後。$result は成否

自動返信側: fplant_before_user_email_send / fplant_skip_user_email 🆕 / fplant_user_email_to 🆕 / fplant_user_email_subject / fplant_user_email_body / fplant_user_email_headers 🆕 / fplant_after_user_email_send。

🆕 = v1.2.0 で追加。

宛先フックの戻り値の型に注意

管理者宛先 ( fplant_admin_email_to ) は複数宛先を想定した配列、自動返信宛先 ( fplant_user_email_to ) は単一の文字列を返します。fplant_skip_admin_email / fplant_skip_user_email の第 2 引数 $form は フォーム ID ではなくフォーム配列です ( $form['id'] で ID を取得 ) 。

例: 入力内容に応じて管理者メールの宛先を振り分ける​

add_filter( 'fplant_admin_email_to', function ( $to, $form_id, $data ) {
    if ( 12 === $form_id && '営業' === ( $data['category'] ?? '' ) ) {
        $to = array( 'sales@example.com' );
    }
    return $to;
}, 10, 3 );

例: BCC を追加する​

add_filter( 'fplant_admin_email_headers', function ( $headers, $form_id, $data ) {
    if ( 12 === $form_id ) {
        $headers[] = 'Bcc: archive@example.com';
    }
    return $headers;
}, 10, 3 );

例: 条件に応じて自動返信を送らない​

add_filter( 'fplant_skip_user_email', function ( $skip, $form, $data, $submission_id ) {
    if ( (int) $form['id'] === 12 && empty( $data['newsletter'] ) ) {
        return true; // 送信中止
    }
    return $skip;
}, 10, 4 );

ファイルアップロード​

フック種別引数用途
fplant_upload_dirfilter( $custom_dir, $form_id )保存先ディレクトリ。$custom_dir は array( 'path' => ..., 'url' => ... ) 🆕
fplant_upload_filenamefilter( $filename, $field_config, $form_id )保存ファイル名 🆕
セキュリティ上の再検証

fplant_upload_dir の戻り値は WordPress の uploads フォルダ内に限定されます ( 外を指定するとエラー ) 。fplant_upload_filename の戻り値は再サニタイズされ、危険な拡張子 ( .php 等 ) は拒否されます。これらは整理 ( 日付別フォルダ・命名規則 ) のためのフックで、保護機構を無効化することはできません。

例: 年月別のフォルダに保存する​

add_filter( 'fplant_upload_dir', function ( $dir, $form_id ) {
    $u   = wp_upload_dir();
    $sub = '/form-uploads/' . gmdate( 'Y-m' );
    return array(
        'path' => $u['basedir'] . $sub,
        'url'  => $u['baseurl'] . $sub,
    );
}, 10, 2 );

フィールド・選択肢・初期値​

フック種別引数用途
fplant_field_typesfilter( $field_types )利用可能なフィールド型の定義を追加・変更
fplant_field_defaultsfilter( $defaults, $field_type )フィールド型ごとの初期設定値
fplant_field_initial_valuefilter( null, $field_name, $field, $form_id )全フィールド共通の初期値。null を返すと次へ
fplant_field_initial_value_{name}filter( $value, $field, $form_id )フィールド別の初期値
fplant_field_choicesfilter( $options, $field_name, $field, $form_id )全フィールド共通の選択肢 ( select / radio / checkbox ) 🆕
fplant_field_choices_{name}filter( $options, $field, $form_id )フィールド別の選択肢 🆕
fplant_custom_mail_tag_valuefilter( '', $field_name, $field, $form_id )カスタムメールタグの値 ( 共通版 ) 🆕
fplant_custom_mail_tag_value_{name}filter( $value, $field, $form_id )カスタムメールタグの値 ( フィールド別 ) 🆕

選択肢 ( $options ) は array( 'label' => 表示名, 'value' => 値 ) の配列です。

例: ログインユーザーのメールアドレスを初期値にする​

add_filter( 'fplant_field_initial_value_email', function ( $value, $field, $form_id ) {
    if ( is_user_logged_in() ) {
        $value = wp_get_current_user()->user_email;
    }
    return $value;
}, 10, 3 );

例: 投稿一覧からセレクトの選択肢を動的生成する​

add_filter( 'fplant_field_choices_product', function ( $options, $field, $form_id ) {
    foreach ( get_posts( array( 'post_type' => 'product' ) ) as $p ) {
        $options[] = array( 'label' => $p->post_title, 'value' => (string) $p->ID );
    }
    return $options;
}, 10, 3 );

例: カスタムメールタグに会員ランクを差し込む​

custom_mail_tag フィールド ( name = member_rank ) の値をフックで供給します。

add_filter( 'fplant_custom_mail_tag_value_member_rank', function ( $value, $field, $form_id ) {
    return get_user_meta( get_current_user_id(), 'rank', true );
}, 10, 3 );

フォーム設定の拡張​

フック種別引数用途
fplant_custom_settings_fieldsfilter( $fields, $form_id )フォーム設定画面に独自の入力項目を追加 🆕
fplant_form_settings_savedaction( $form_id, $settings )フォーム設定の保存直後 🆕

fplant_custom_settings_fields で定義した項目は設定画面に自動描画・保存され、実行時に $form['settings'][キー] で参照できます。

例: 設定画面に CRM 連携先 URL の入力欄を追加する​

add_filter( 'fplant_custom_settings_fields', function ( $fields, $form_id ) {
    $fields[] = array(
        'key'         => 'x_crm_endpoint',  // 英数字・アンダースコア
        'type'        => 'text',            // text / textarea / checkbox / select / number
        'label'       => 'CRM 連携先 URL',
        'description' => 'CRM の API エンドポイント',
    );
    return $fields;
}, 10, 2 );

// 保存した値を送信完了時に利用
add_action( 'fplant_after_submission_complete', function ( $data, $form_id, $form, $submission_id ) {
    if ( ! empty( $form['settings']['x_crm_endpoint'] ) ) {
        // $form['settings']['x_crm_endpoint'] を使った処理
    }
}, 10, 4 );

テンプレート・レンダリング​

フック種別引数用途
fplant_locate_templatefilter( $template, $template_name, $template_path )テンプレートファイルの解決先パスを変更 ( テーマ側で上書き等 )
fplant_allowed_field_typesfilter( $allowed_field_types )HTML テンプレートで許可するフィールド型のホワイトリスト
fplant_template_valuesfilter( $values, $form_id )HTML テンプレート内の {{key}} プレースホルダに値を差し込む ( 値は esc_html される )

HTML テンプレート機能そのものの使い方は HTML テンプレート を参照してください。

例: テンプレートに動的な値を差し込む​

add_filter( 'fplant_template_values', function ( $values, $form_id ) {
    $values['today'] = wp_date( 'Y年n月j日' );
    return $values;
}, 10, 2 );
// テンプレート内で {{today}} と書くと当日の日付に置換される

データエクスポート​

フック種別引数用途
fplant_export_encodingfilter( $encoding, $form_id )送信データ CSV の文字コード ( 既定 UTF-8 ) 🆕

例: Excel 互換のため Shift-JIS で出力する​

add_filter( 'fplant_export_encoding', function ( $encoding, $form_id ) {
    return 'sjis-win'; // Shift-JIS ( CP932 )
}, 10, 2 );

フック一覧 (早見表)​

🆕 = v1.2.0 / v1.2.1 で追加。

フック種別引数
fplant_form_is_viewable 🆕filter( $viewable, $form )
fplant_form_is_submittable 🆕filter( $submittable, $form )
fplant_preview_notice 🆕filter( $notice, $form )
fplant_before_submissionaction( $form_id, $data )
fplant_submission_datafilter( $data, $form_id )
fplant_before_save_submission_datafilter( $data, $form_id )
fplant_after_submissionaction( $submission_id, $form_id, $data )
fplant_after_submission_completeaction( $data, $form_id, $form, $submission_id )
fplant_complete_message 🆕filter( $message, $form_id, $data )
fplant_success_html 🆕filter( $html, $form_id, $data )
fplant_redirect_url 🆕filter( $url, $form_id, $data )
fplant_before_admin_email_sendaction( $email_settings, $form_id )
fplant_skip_admin_email 🆕filter( $skip, $form, $data, $submission_id )
fplant_before_send_email_datafilter( $data, $form, $submission_id, $type )
fplant_admin_email_to 🆕filter( $to, $form_id, $data )
fplant_admin_email_subjectfilter( $subject, $form_id )
fplant_admin_email_bodyfilter( $message, $form_id, $data )
fplant_admin_email_headers 🆕filter( $headers, $form_id, $data )
fplant_after_admin_email_sendaction( $email_settings, $form_id, $result )
fplant_before_user_email_sendaction( $email_settings, $form_id )
fplant_skip_user_email 🆕filter( $skip, $form, $data, $submission_id )
fplant_user_email_to 🆕filter( $to, $form_id, $data )
fplant_user_email_subjectfilter( $subject, $form_id )
fplant_user_email_bodyfilter( $message, $form_id, $data )
fplant_user_email_headers 🆕filter( $headers, $form_id, $data )
fplant_after_user_email_sendaction( $email_settings, $form_id, $result )
fplant_upload_dir 🆕filter( $custom_dir, $form_id )
fplant_upload_filename 🆕filter( $filename, $field_config, $form_id )
fplant_field_typesfilter( $field_types )
fplant_field_defaultsfilter( $defaults, $field_type )
fplant_field_initial_value ( _{name} )filter( $value, [$field_name,] $field, $form_id )
fplant_field_choices 🆕 ( _{name} )filter( $options, [$field_name,] $field, $form_id )
fplant_custom_mail_tag_value 🆕 ( _{name} )filter( $value, [$field_name,] $field, $form_id )
fplant_custom_settings_fields 🆕filter( $fields, $form_id )
fplant_form_settings_saved 🆕action( $form_id, $settings )
fplant_locate_templatefilter( $template, $template_name, $template_path )
fplant_allowed_field_typesfilter( $allowed_field_types )
fplant_template_valuesfilter( $values, $form_id )
fplant_export_encoding 🆕filter( $encoding, $form_id )

バリデーション系フック ( fplant_validate_* / fplant_validation_message_* / fplant_before_validation / fplant_validation_errors ) は バリデーションフック (PHP) を参照してください。

セキュリティ上の注意​

  • フックで受け取った入力値は、出力前に必ず esc_html() / esc_attr() / esc_url() 等でエスケープしてください。
  • 外部 API を呼ぶ処理は timeout を設定し、必要に応じて Transient API でキャッシュしてください。
  • fplant_upload_dir / fplant_upload_filename の保護機構 ( uploads 配下限定・拡張子ブラックリスト ) は無効化できません。