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

PHP フックリファレンス

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

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

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

Pro 版のフック

Form Plant Pro が追加するフック・JavaScript イベントは Pro の開発者向け情報 にまとめています。

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, $is_preview )フォームが送信を受け付けるか 🆕 ( 第 3 引数は 1.5.2 で追加 )
fplant_preview_noticefilter( $notice, $form )未公開フォームの上に出るプレビュー注記の HTML 🆕
fplant_form_outputfilter( $html, $form, $context )描画されたフォームの HTML を差し替える / 前後に足す 1.5.2
fplant_form_unavailable_messagefilter( $message, $form )送信を受け付けないときに表示される文言 1.5.2

$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 );

受付を締め切って案内を出す ( 1.5.2 )​

fplant_form_is_viewable を false にするとフォームは何も出力されません ( iframe / JavaScript 埋め込みでは 404 ) 。「受付は終了しました」のような案内を代わりに出したい場合は、表示の可否には触れず次の 3 つを組み合わせます。

やりたいこと使うフック
フォームの代わりに案内を出すfplant_form_output
送信そのものを止める ( 開いたままのタブ・直接 POST への備え )fplant_form_is_submittable
送信を止めたときの文言を変えるfplant_form_unavailable_message
$deadline = strtotime( '2026-12-01 00:00:00' );

// 締切後はフォームの代わりに案内を出す
add_filter( 'fplant_form_output', function ( $html, $form, $context ) use ( $deadline ) {
    if ( 12 !== (int) $form['id'] || time() < $deadline ) {
        return $html;
    }
    return '<p class="entry-closed">受付は終了しました。</p>';
}, 10, 3 );

// 表示だけ変えても送信は止まらないので、こちらも必ず閉じる
add_filter( 'fplant_form_is_submittable', function ( $submittable, $form ) use ( $deadline ) {
    if ( 12 !== (int) $form['id'] ) {
        return $submittable;
    }
    return time() < $deadline ? $submittable : false;
}, 10, 2 );

// 送信が止まったときにフォーム上に出る文言
add_filter( 'fplant_form_unavailable_message', function ( $message, $form ) {
    return ( 12 === (int) $form['id'] ) ? '受付は終了しました。' : $message;
}, 10, 2 );

fplant_form_output の $html は、フォームを囲む <div class="fplant-form-wrapper"> まで含んだ描画結果です。前後に要素を足すこともできます。$context は設置方法で、'shortcode' ( ショートコード / ブロック ) ・'iframe' ( iframe 埋め込み ) ・'rest' ( JavaScript 埋め込み ) のいずれかです。

非公開フォームでは呼ばれません

fplant_form_is_viewable が false のフォームでは fplant_form_output は呼ばれません。未公開フォームの存在が訪問者に伝わらないようにするためです。

fplant_form_unavailable_message の戻り値はプレーンテキストです ( HTML タグは除去されます ) 。既定の文言は「このフォームは現在ご利用いただけません。」です。

プレビューからの送信を見分ける ( 1.5.2 )​

fplant_form_is_submittable の第 3 引数 $is_preview は、フォーム編集画面のプレビューから行われた検証だけの送信のときに true になります ( この送信は保存もメール送信もされません ) 。受付を制限しているフォームでも、編集者が動作を確認できるようにする用途です。

add_filter( 'fplant_form_is_submittable', function ( $submittable, $form, $is_preview ) {
    if ( $is_preview ) {
        return $submittable; // プレビューは制限しない
    }
    // …独自の受付制限…
    return $submittable;
}, 10, 3 );

引数が増えただけなので、2 引数で登録している既存のコールバックはそのまま動きます。

送信ライフサイクル​

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

フック種別引数タイミング・用途
fplant_before_submissionaction( $form_id, $data )バリデーション前。生データのロギングや前処理に
fplant_sanitize_field_valuefilter( $sanitized_value, $raw_value, $field, $form_id )専用サニタイザを持たないフィールド型 (テキスト系・独自フィールド型) のサニタイズを差し替え。戻り値 = 保存する値 🆕 v1.4.0
fplant_submission_datafilter( $data, $form_id )サニタイズ直後のデータ加工。戻り値 = 加工後のデータ
fplant_submission_gatefilter( $gate, $form, $data )保存直前の最終ゲート。WP_Error を返すと送信を中止 🆕 v1.5.2
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 );

例: 保存直前に送信を止める ( fplant_submission_gate ・1.5.2 )​

入力内容の検証をすべて通った後、データベースに保存される直前に 1 回だけ呼ばれる最終ゲートです。WP_Error を返すとその送信は中止され、保存・メール送信・Webhook 配信・fplant_after_submission のいずれも実行されません。訪問者にはエラーメッセージが表示されます。

定員・在庫・重複申込の判定など、「入力は正しいが受け付けられない」ケースに使います。

add_filter( 'fplant_submission_gate', function ( $gate, $form, $data ) {
    if ( 12 !== (int) $form['id'] || is_wp_error( $gate ) ) {
        return $gate; // 対象外、または他のフックが既に止めている
    }

    // 同じメールアドレスからの重複申込を拒否する
    $email = $data['email'] ?? '';
    if ( '' !== $email && my_already_applied( $email ) ) {
        return new WP_Error( 'already_applied', 'このメールアドレスは既に申し込み済みです。' );
    }

    return $gate; // 通す場合は受け取った値 ( 既定は null ) をそのまま返す
}, 10, 3 );
使い分け
  • fplant_form_is_submittable … フォームを開いた時点で受付を閉じているかどうか。入力画面に案内が出ます
  • fplant_submission_gate … 送信された内容を見てから判断するもの。入力エラーで弾かれる送信には枠を使いません
エラーメッセージはプレーンテキスト

WP_Error のメッセージは HTML タグが除去されて表示されます。空文字の場合は fplant_form_unavailable_message の文言が使われます。フォーム編集画面のプレビューからの送信では呼ばれません。

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

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

フック種別引数有効になる設定
fplant_complete_messagefilter( $message, $form_id, $data, $form )「メッセージ」 ( 差し込みタグ展開後 )
fplant_success_htmlfilter( $html, $form_id, $data, $form )「カスタムページ」 ( {{key}} と差し込みタグの展開後の HTML )
fplant_redirect_urlfilter( $url, $form_id, $data, $form )「リダイレクト」 ( esc_url_raw 前 )
fplant_submission_result 1.5filter( $result, $form_id, $data, $form )常に ( 上の 3 つの後 )。結果配列全体を差し替えられる

第 4 引数 $form ( フォーム設定全体の配列 ) は v1.4.0 で追加。フォーム設定を参照した条件分岐に使えます。

v1.5.0 から、完了メッセージと完了ページ HTML はメールと同じ差し込みタグ ( {submission_id} / {field:名前} / {all_fields} など ) を展開した状態でフィルターに渡ります。展開処理は FPLANT_Email_Handler::replace_tags( $text, $data, $form, $submission_id, $args ) として公開されており、独自の文字列にも同じ展開を適用できます ( $args['escape'] = 'html' で差し込み値をエスケープ、$args['mask_password'] = true でパスワードを伏せ字に )。

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

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 );

例: 入力値に応じて完了アクションの種別を切り替える ( 1.5.0 )​

fplant_redirect_url などは、フォーム設定で選んだ種別の分岐内でしか発火しません。「既定はメッセージ表示、特定の回答のときだけリダイレクト」のように種別そのものを切り替えるには fplant_submission_result を使います。$result のキーは success / message / submission_id / action_type ( message | custom_page | redirect ) / redirect_url / success_page_html です。

add_filter( 'fplant_submission_result', function ( $result, $form_id, $data, $form ) {
    if ( 12 === $form_id && 'premium' === ( $data['plan'] ?? '' ) ) {
        $result['action_type']  = 'redirect';
        $result['redirect_url'] = home_url( '/thanks-premium/' );
    }
    return $result;
}, 10, 4 );

リダイレクト先で [fplant_complete] を使う設定のフォームでは、このフィルターの後に完了トークンが付与されるため、切り替えたリダイレクト先でも完了画面を表示できます。

確認画面・メールに出す項目を絞り込む: fplant_display_fields ( 1.5.0 )​

フック種別引数
fplant_display_fieldsfilter( $fields, $data, $form, $context )

確認画面、メールの {all_fields} と既定本文、完了画面の {all_fields} を生成するときに、その送信に限って出力するフィールド定義の配列を差し替えられます ( フォーム定義自体は変わりません )。$context は confirmation / email / completion のいずれかです。

// 例: 「会社名」が空のときは確認画面とメールに出さない
add_filter( 'fplant_display_fields', function ( $fields, $data, $form, $context ) {
    if ( empty( $data['company'] ) ) {
        $fields = array_values( array_filter( $fields, function ( $field ) {
            return 'company' !== $field['name'];
        } ) );
    }
    return $fields;
}, 10, 4 );

[fplant_complete] ( リダイレクト先の完了画面 ) のフック ( 1.5.0 )​

フック種別引数用途
fplant_complete_shortcode_htmlfilter( $html, $form_id, $data, $submission_id, $form )ショートコードが出力する HTML を差し替え
fplant_complete_token_ttlfilter( $ttl, $form_id )表示されなかった完了トークンの有効期限 ( 秒。既定 300 )

使い方は フォーム設定 › リダイレクト先のページで完了画面を表示する を参照してください。

Webhook​

汎用 Webhook ( v1.4.0 で追加。機能の概要は Webhook 連携 を参照 ) の配信を フィルターでカスタマイズできます。

フック種別引数用途
fplant_webhook_should_sendfilter( $should_send, $webhook, $payload, $form_id, $data )false を返すと配信しない。条件付き配信に
fplant_webhook_payloadfilter( $payload, $form_id, $data, $submission_id )送信する JSON ペイロードの加工
fplant_webhook_request_argsfilter( $args, $url )wp_safe_remote_post() の引数 ( タイムアウト等 ) の変更
fplant_webhook_allow_httpfilter( $allow, $url )true を返すと http:// URL を許可 ( ローカル開発向け )

例: 特定の項目が空のときは配信しない​

add_filter( 'fplant_webhook_should_send', function ( $should_send, $webhook, $payload, $form_id, $data ) {
    if ( 12 === $form_id && empty( $data['company'] ) ) {
        return false; // 会社名が空の送信は連携先に送らない
    }
    return $should_send;
}, 10, 5 );

例: ペイロードに独自の項目を追加する​

add_filter( 'fplant_webhook_payload', function ( $payload, $form_id, $data, $submission_id ) {
    $payload['environment'] = wp_get_environment_type();
    return $payload;
}, 10, 4 );

メール送信​

管理者メールと自動返信 ( ユーザー ) メールで、対になるフックが用意されています。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, $data )件名 ( $data は v1.4.0 で追加 )
fplant_admin_email_bodyfilter( $message, $form_id, $data )本文
fplant_admin_email_headersfilter( $headers, $form_id, $data )ヘッダ ( From / Cc / Bcc / Reply-To ) 🆕
fplant_admin_email_attachmentsfilter( $attachments, $form_id, $data, $submission_id )管理者メールの添付ファイル ( 絶対パスの配列 ) 🆕 v1.5.1
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_attachments で足せるのは wp-content/uploads/fplant_uploads/ 配下のファイルだけです。それ以外のパスはフィルター適用後の検査で除外されます ( サーバー上の任意のファイルが添付されるのを防ぐため ) 。フォームのアップロード処理を通したファイルは自動的にこの配下に入ります。

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

管理者宛先 ( 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 等 ) は拒否されます。これらは整理 ( 日付別フォルダ・命名規則 ) のためのフックで、保護機構を無効化することはできません。

保存先は fplant_uploads 配下を指定してください

管理画面からのファイルダウンロードと、管理者通知メールへの添付は、wp-content/uploads/fplant_uploads/ 配下のファイルだけを対象にします。fplant_upload_dir でこの外を指定した場合、アップロード自体は成功しますがダウンロードと添付が行われません。整理用のサブフォルダは fplant_uploads の中に作ってください。

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

add_filter( 'fplant_upload_dir', function ( $dir, $form_id ) {
    $u   = wp_upload_dir();
    // ダウンロードと添付の対象は fplant_uploads 配下なので、その中に作る
    $sub = '/fplant_uploads/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_html_setting_keysfilter( $keys, $form_id )HTML を保存できるフォーム設定キーの一覧 1.5.2

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 );

HTML を保存できる設定にする ( 1.5.2 )​

フォーム設定の値は既定でタグが除去されて保存されます。案内文のように HTML を書かせたい項目は、HTML を許可するキーとして登録します。値は wp_kses_post() ( 投稿本文と同じ許可範囲 ) でサニタイズされます。

方法は 2 つあります。

// (a) 独自の設定項目を追加するとき: allow_html を付ける
add_filter( 'fplant_custom_settings_fields', function ( $fields, $form_id ) {
    $fields[] = array(
        'key'        => 'x_closed_notice',
        'type'       => 'textarea',
        'label'      => '受付終了時のお知らせ',
        'allow_html' => true,   // ← HTML を保存できる
    );
    return $fields;
}, 10, 2 );

// (b) 設定配列に独自のブロックを持つ拡張が、その中のキーを登録するとき
add_filter( 'fplant_html_setting_keys', function ( $keys, $form_id ) {
    $keys[] = 'x_addon_closed_message';
    return $keys;
}, 10, 2 );

現在の実効リストは FPLANT_Form_Manager::get_html_setting_keys( $form_id ) で取得できます ( 既定は confirmation_message / after_submit_html / success_page_html / confirmation_template の 4 つ ) 。

キーは名前で一致します

登録したキーは、フォーム設定配列のどの深さにあっても名前で一致します。message のような一般的な名前を登録すると、意図しない設定まで HTML 可になります。x_ のような接頭辞を付けた固有の名前を使ってください。また、保存時に許可されるのは wp_kses_post() の範囲までです。出力時には改めてエスケープしてください。

1.5.2 での修正

allow_html は 1.5.1 以前、フォーム編集画面から保存したときには効いていませんでした ( 保存の途中でタグが除去されていました ) 。1.5.2 で修正しています。標準の 4 キーの扱いは変わりません。

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

フック種別引数用途
fplant_locate_templatefilter( $template, $template_name, $template_path )テンプレートファイルの解決先パスを変更 ( テーマ側で上書き等 )
fplant_allowed_field_typesfilter( $allowed_field_types )HTML テンプレートで許可するフィールド型のホワイトリスト
fplant_template_valuesfilter( $values, $form_id )入力画面 HTML テンプレート・確認画面テンプレート・完了ページ HTML 内の {{key}} プレースホルダに値を差し込む ( 値は esc_html される )
fplant_allowed_form_htmlfilter( $allowed )フォーム出力で許可する HTML タグ・属性 ( wp_kses() 形式 ) 🆕 v1.5.1

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

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

fplant_template_values フィルターが返す配列のキーを、テンプレート内に {{キー名}} と書くと、レンダリング時にその値へ置換されます。置換は次の 3 箇所すべてで有効です。

画面設定箇所
入力画面入力画面 HTML テンプレート ( 「HTML テンプレートを利用する」が ON のとき )
確認画面確認画面テンプレート ( 「確認画面 HTML テンプレートを使用」が ON のとき )
完了画面送信後アクションの「完了ページ HTML」
add_filter( 'fplant_template_values', function ( $values, $form_id ) {
    $values['today']     = wp_date( 'Y年n月j日' );
    $values['shop_name'] = get_bloginfo( 'name' );
    return $values;
}, 10, 2 );

確認画面テンプレートでの記述例 ( {{shop_name}} と {{today}} が置換されます ) :

<h2>[fplant_confirmation_title]</h2>
<p>{{shop_name}} 宛に以下の内容で送信します ( {{today}} 受付 ) 。</p>
[fplant_all_fields]
[fplant_back] [fplant_confirm_submit]

[fplant_all_fields] などは確認画面テンプレート用のタグです ( フォーム編集画面の「利用可能なショートコード」から挿入できます ) 。

バージョン 1.4.1 から、確認画面テンプレート内でも WordPress のショートコードがそのまま展開されます ( 1.4.0 以前では展開されません ) 。ショートコードの出力 ( テキスト ) をこのフィルターの値にして差し込むこともできます。

add_filter( 'fplant_template_values', function ( $values, $form_id ) {
    // 例: 営業時間を返す自作ショートコードの出力を確認画面でも表示する
    $values['business_hours'] = do_shortcode( '[business_hours]' );
    return $values;
}, 10, 2 );
制約
  • 値は esc_html() でエスケープされるため、差し込めるのはテキストのみです ( HTML タグを含む値は、タグが文字としてそのまま表示されます ) 。
  • iframe / JavaScript 埋め込みでの置換はバージョン 1.4.1 以降で有効です ( 1.4.0 以前は通常のフォーム設置のみ ) 。
  • フィルターで定義していないキーの {{キー名}} は置換されず、そのまま表示されます。
  • 特定のフォームだけに差し込みたい場合は、第 2 引数の $form_id で分岐してください。

カスタムフィールド型の登録 (拡張開発者向け)​

プラグインやテーマから独自のフィールド型を追加できます ( v1.4.0 で拡張 API を整備 ) 。登録は次の 3 つのフィルターで完結します。

ステップフック役割
1. 型の登録fplant_field_typesフィールド追加ダイアログに型を表示 ( ラベル・アイコン・説明 )
2. 許可リストfplant_allowed_field_typesフロントのレンダリング許可 ( 忘れると一切表示されません )
3. テンプレート解決fplant_locate_templateform-fields/{型}.php を自前のディレクトリから供給

例: 独自フィールド型「評価 (rating)」を追加する​

// 1. 型を登録
add_filter( 'fplant_field_types', function ( $types ) {
    $types['rating'] = array(
        'label'       => '評価',
        'icon'        => 'dashicons-star-filled', // dashicons または独自 CSS クラス
        'description' => '5 段階評価',
    );
    return $types;
} );

// 2. レンダリング許可リストに追加
add_filter( 'fplant_allowed_field_types', function ( $allowed ) {
    $allowed[] = 'rating';
    return $allowed;
} );

// 3. テンプレートを自前のディレクトリから解決
//    ( テーマにもプラグイン本体にも無い場合、$template は空文字で渡ってくる )
add_filter( 'fplant_locate_template', function ( $template, $template_name, $template_path ) {
    if ( '' !== (string) $template ) {
        return $template; // テーマ側のオーバーライド等を優先
    }
    $candidate = plugin_dir_path( __FILE__ ) . 'templates/' . $template_name;
    return file_exists( $candidate ) ? $candidate : $template;
}, 10, 3 );

テンプレートファイル ( 例: templates/form-fields/rating.php ) の書き方は既存フィールドの テンプレートが参考になります ( テーマからのテンプレート上書き 参照 ) 。

あわせて次の点も実装してください。

  • バリデーション: 独自型は必須チェック以外のサーバー検証を通りません。 バリデーションフック ( fplant_validation_errors 等 ) でサーバー側の検証を、 必要なら fplant.addValidator() でクライアント側の即時検証を追加します。
  • サニタイズ: 専用サニタイザを持たない型の保存値は fplant_sanitize_field_value ( 送信ライフサイクル 参照 ) で型別に差し替えられます。
  • 確認画面: 標準の確認画面はそのまま表示されます。カスタム確認テンプレートで [fplant_value name="..."] を使う場合のみ confirm-fields/{型}.php テンプレートも必要です ( 同じく fplant_locate_template で解決できます。[fplant_all_fields] には不要 ) 。

値を持たない型 ( レイアウト型 ) の登録 ( 1.5.2 )​

見出しや区切りのように入力値を持たないフィールド型は、レイアウト型として登録します。標準では html 型がこれにあたります。

add_filter( 'fplant_layout_field_types', function ( $types ) {
    $types[] = 'section_heading';
    return $types;
} );

登録すると、その型のフィールドは次のように扱われます。

箇所扱い
入力検証対象外 ( 必須チェックも行われません )
確認画面・{all_fields}・メール本文の既定出力されません
CSV エクスポート ( 単一フォーム )列が作られません
Webhook のペイロード含まれません
フォーム編集画面のメールタグ一覧表示されません
デフォルトレイアウトでの描画項目名・エラー表示の枠を付けずにそのまま出力されます

現在の一覧は FPLANT_Field_Manager::get_layout_field_types()、判定は FPLANT_Field_Manager::is_layout_type( $type ) で取得できます。

型の登録とは別です

fplant_field_types ( 型の登録 ) と fplant_allowed_field_types ( レンダリング許可 ) は従来どおり必要です。fplant_layout_field_types は「値を持たない」ことを伝えるだけのフィルターです。

構造化された値 (配列) の保存​

v1.4.0 から、独自フィールド型は配列 ( 入れ子 ) の値をそのまま保存できます。

  • 送信データは JSON で保存されるため、配列の構造は保存・再取得で維持されます
  • name="items[0][price]" のようなブラケット付き name の入力は、送信時に自動で 入れ子の値 ( 行配列 / オブジェクト ) として収集されます ( 詳細は JavaScript カスタマイズ )
  • 既定のサニタイズは構造を保ったままテキストサニタイズされます ( fplant_sanitize_field_value で差し替え可能 )

送信値の表示整形: fplant_format_submission_value​

保存された送信値をプレーンテキストへ整形する共通フィルターです ( v1.4.0 ) 。確認画面・メール・CSV・管理画面の送信詳細まで、すべての出力経路がこの整形を通るため、1 箇所のフックで独自型の表示を統一できます。

引数説明
$formatted既定の整形結果 ( フラット配列はカンマ結合、行配列は「1. ラベル: 値 / …」の番号付き行 )
$value保存されている生の値 ( 配列のことがあります )
$fieldフィールド設定の配列
$context出力先: confirmation / email_all_fields / email_tag / admin_detail / csv_single / csv_all
$form_idフォーム ID ( 不明な場合 0 )
$submission_id送信 ID ( v1.5.1 で追加 ) 。確認画面のようにまだ保存されていない場合は 0。過去の送信を当時のフィールド定義で表示したい拡張が、送信時のスナップショットを引くために使えます
add_filter( 'fplant_format_submission_value', function ( $formatted, $value, $field, $context, $form_id, $submission_id ) {
    if ( 'rating' !== ( $field['type'] ?? '' ) ) {
        return $formatted;
    }
    return str_repeat( '★', (int) $value ); // 例: 3 → ★★★
}, 10, 6 );

既存の 5 引数のコールバックはそのまま動きます ( 引数が増えても壊れません ) 。

戻り値はプレーンテキスト

HTML は書けません。エスケープと改行の <br> 変換は各出力側が行うため、HTML を返してもタグがそのまま文字として表示されます。

管理画面の送信詳細を HTML で差し替える: fplant_submission_detail_value_html ( 1.5.1 )​

fplant_format_submission_value はプレーンテキスト専用ですが、管理画面の送信詳細だけ HTML で差し替えられます。行を表で見せる、行ごとのダウンロードリンクを出すなど、独自型のリッチ表示に使います。

引数説明
$cell_html既定のセル HTML ( nl2br( esc_html( 整形結果 ) ) )
$raw_value整形前の値。パスワードはマスク済み、同意は表示文言に置換済みで渡ります
$field_defフィールド定義 ( 不明なときは空配列 )
$submission送信レコード全体
$formフォーム設定
add_filter( 'fplant_submission_detail_value_html', function ( $cell_html, $raw_value, $field_def ) {
    if ( 'rating' !== ( $field_def['type'] ?? '' ) ) {
        return $cell_html;
    }
    return '<strong>' . esc_html( str_repeat( '★', (int) $raw_value ) ) . '</strong>';
}, 10, 3 );
出力は wp_kses_post() を通ります

戻り値は投稿本文と同じ許可範囲まで絞られます。<script> や on* 属性は除去されるため、JavaScript は書けません。トップレベルのファイル型 ( ダウンロードリンク付きのセル ) はこのフィルターを通りません。

送信詳細からネストしたファイルを落とす ( 1.5.1 )​

ファイルダウンロードのエンドポイントは、任意パラメータ row ( 行番号 ) と sub ( サブフィールドのキー ) を受け取れます。グループやリピーターの中のファイルへのリンクを、独自の経路を作らずに組み立てられます。

$url = add_query_arg(
    array(
        'action'        => 'fplant_download_file',
        'submission_id' => $submission['id'],
        'field'         => 'members',
        'row'           => 0,          // 行配列の添字 ( 省略可 )
        'sub'           => 'photo',    // サブフィールドのキー ( 省略可 )
        'nonce'         => wp_create_nonce( 'fplant_download_file' ),
    ),
    admin_url( 'admin-ajax.php' )
);

nonce・manage_options 権限・fplant_uploads 配下かどうかの検査は既存のまま共通で適用されます。

許可されているフィールド型を取得する ( 1.5.1 )​

FPLANT_Template_Loader::get_allowed_field_types() で、fplant_allowed_field_types 適用後の実効リストを取得できます。

if ( in_array( 'rating', FPLANT_Template_Loader::get_allowed_field_types(), true ) ) {
    // rating 型はレンダリングされる状態
}
登録されていない型のフィールドは素通しされます

v1.5.1 から、許可リストに無い型のフィールド ( = 拡張プラグインを停止した状態 ) は必須チェックを含む検証がスキップされ、値も保存されません。停止中の拡張の必須フィールドでフォーム全体が送信できなくなるのを防ぐためです。フィールド編集画面では型が 型名 (利用不可) と表示され、保存しても型は失われません。

送信データへの拡張データ (extras)​

送信レコードに独自のデータ ( 例: 送信時点の設定スナップショット ) を紐付けたい場合は、次の静的メソッドが利用できます ( v1.4.0 ) 。

FPLANT_Database::set_submission_extra( $submission_id, $key, $value );
FPLANT_Database::get_submission_extra( $submission_id, $key, $default_value );

送信 ID は fplant_after_submission / fplant_after_submission_complete の引数で受け取れます。

データエクスポート​

フック種別引数用途
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 で追加。1.4 = v1.4.0 で追加または引数追加。1.5 = v1.5.0 で追加。1.5.1 = v1.5.1 で追加または引数追加。1.5.2 = v1.5.2 で追加または引数追加。

フック種別引数
fplant_form_is_viewable 🆕filter( $viewable, $form )
fplant_form_is_submittable 🆕 1.5.2filter( $submittable, $form, $is_preview )
fplant_preview_notice 🆕filter( $notice, $form )
fplant_form_output 1.5.2filter( $html, $form, $context )
fplant_form_unavailable_message 1.5.2filter( $message, $form )
fplant_before_submissionaction( $form_id, $data )
fplant_sanitize_field_value 1.4filter( $sanitized_value, $raw_value, $field, $form_id )
fplant_submission_datafilter( $data, $form_id )
fplant_submission_gate 1.5.2filter( $gate, $form, $data )
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 🆕 1.4filter( $message, $form_id, $data, $form )
fplant_success_html 🆕 1.4filter( $html, $form_id, $data, $form )
fplant_redirect_url 🆕 1.4filter( $url, $form_id, $data, $form )
fplant_submission_result 1.5filter( $result, $form_id, $data, $form )
fplant_display_fields 1.5filter( $fields, $data, $form, $context )
fplant_complete_shortcode_html 1.5filter( $html, $form_id, $data, $submission_id, $form )
fplant_complete_token_ttl 1.5filter( $ttl, $form_id )
fplant_webhook_should_send 1.4filter( $should_send, $webhook, $payload, $form_id, $data )
fplant_webhook_payload 1.4filter( $payload, $form_id, $data, $submission_id )
fplant_webhook_request_args 1.4filter( $args, $url )
fplant_webhook_allow_http 1.4filter( $allow, $url )
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_subject 1.4filter( $subject, $form_id, $data )
fplant_admin_email_bodyfilter( $message, $form_id, $data )
fplant_admin_email_headers 🆕filter( $headers, $form_id, $data )
fplant_admin_email_attachments 1.5.1filter( $attachments, $form_id, $data, $submission_id )
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_subject 1.4filter( $subject, $form_id, $data )
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_layout_field_types 1.5.2filter( $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_html_setting_keys 1.5.2filter( $keys, $form_id )
fplant_locate_templatefilter( $template, $template_name, $template_path )
fplant_allowed_field_typesfilter( $allowed_field_types )
fplant_template_valuesfilter( $values, $form_id )
fplant_allowed_form_html 1.5.1filter( $allowed )
fplant_format_submission_value 1.4 1.5.1filter( $formatted, $value, $field, $context, $form_id, $submission_id )
fplant_submission_detail_value_html 1.5.1filter( $cell_html, $raw_value, $field_def, $submission, $form )
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 配下限定・拡張子ブラックリスト ) は無効化できません。