Snow Monkey Forms のフックをまとめてみました

snow_monkey_forms/complete/message

送信完了画面に表示するメッセージはフォームの設定画面の「完了画面」のところで設定できますが、これを動的に変えることができます。

return に表示したいものを設定します。
「完了画面」欄で設定したメッセージ（出力されるHTML）は $message で取得できます。
フィールドの入力値は、$responser->get( 'フィールドのNAME値' ); で取得できます。
フォームの設定値は、$setting->get_control( '設定項目のNAME値' ) で取得できます。

/*
 * 完了画面欄で設定したメッセージの前にお名前を表示する
 */
add_filter(
	'snow_monkey_forms/complete/message',
	function( $message, $responser, $setting ) {
		$data = '<p>' . $responser->get( 'fullname' ) . '様</p>'.$message;
		return $data;
	},
	10,
	2
);

snow_monkey_forms/system_error/message

return に表示したいものを設定します。

$message は Snow Monkey Forms のプログラムに記述されているデフォルトメッセージです。
フィールドの入力値は、$responser->get( 'フィールドのNAME値' ); で取得できます。

なお、デフォルトメッセージは英語で記述されていて翻訳で日本語になっていますので、単純にメッセージを変えたいだけであれば翻訳を変える方法もあります。

/*
 * システムエラー時、デフォルトメッセージの後にメール送信先を表示する
 */
add_filter(
	'snow_monkey_forms/system_erro/message',
	function( $message, $responser ) {
		$data = $message . '<p>メール送信先は "' . $responser->get( 'email' ) . ' "です。</p>';
		return $data;
	},
	10,
	2
);

snow_monkey_forms/validator/error_message

Snow Monkey Forms のバリデーションは「必須」しかありませんが、その「必須」がエラーになったときのメッセージを変更できます。

なお、デフォルトメッセージは英語で記述されていて翻訳で日本語になっていますので、単純にメッセージを変えたいだけであれば翻訳を変える方法もあります。

$name は変更したいフィールドのNAME値です。
バリデーションは「必須」しかありませんので、$validation_name は 'required' 固定になります。

/*
 * 項目ごとにエラーメッセージを変える
 */
add_filter(
	'snow_monkey_forms/validator/error_message',
	function( $error_message, $validation_name, $name ) {
		if ( 'required' === $validation_name && 'fullname' === $name ) {
			return 'お名前は必須です';
		}
		if ( 'required' === $validation_name && 'email' === $name ) {
			return 'メールアドレスは必須です';
		}
		return $error_message;
	},
	10,
	3
);

snow_monkey_forms/control/attributes

フォームの項目の設定で value に初期値を設定しておくことができますが、これを動的に設定することができます。

フォームページへのリンクにクエリを付加しておき、それを取得して反映させる方法がよく使われます。
下記のコードでは、お問い合わせページへのリンクURLに元ページのIDを付加しておき（ /contact/?page_id=1234 とか）、クエリパラメーターからページのタイトルを取得して refererフィールドの初期値に設定します。

クエリパラメーターには悪意のあるスクリプトを含められてしまう危険性がありますので、必ずサニタイズしてください。
下記のコードでは filter_input 関数を使用しています。

<!-- このページのIDが1234だとして、そのIDをクエリパラメーターとして指定する -->
<a href="/contact/?post_id=1234">お問い合わせはこちら</a>

/*
 * リンクURLに含まれるページIDからリンク元のページタイトルを取得して NAME値がrefererのフィールドに設定する
 */
add_filter(
	'snow_monkey_forms/control/attributes',
	function( $attributes ) {
		// name値が referer という名前のブロック
		if ( isset( $attributes['name'] ) && 'referer' === $attributes['name'] ) {
			// ?post_id という URL クエリがあるとき
			$post_id = filter_input( INPUT_GET, 'post_id' );
			if ( ! is_null( $post_id ) ) {
				// ?post_id で指定された投稿のタイトルを初期値として設定
				$attributes['value'] = get_the_title( $post_id );
			}
		}
		return $attributes;
	}
);

snow_monkey_forms/custom_mail_tag

有名なフォームプラグイン「Contact Form 7」では特別なメールタグとして送信者情報、ページ情報などを取得できるようになっていますが、Snow Monkey Forms には用意されていません。

管理者宛メールに、送信された日時・送信者IPアドレスなどの項目を入れたいという要望は多いと思います。
特にスパム対策には有効です。

Snow Monkey Forms では用意されていない情報を取得して、独自のメールタグを定義してメールに埋め込むことができます。
ただし情報取得は自分でコードを書く必要があります。

メールタグは {タグ名} としてメールに埋め込みます。
下記のコードでは、送信日付を {date} で埋め込めるようにします。

/*
 * {date}タグが使用されていたら現在の日付を取得して返す
 */
add_filter(
	'snow_monkey_forms/custom_mail_tag',
	function( $value, $name ) {
		if ( 'date' === $name ) {
			return date('Y-m-d');
		}
		return $value;
	},
	10,
	2
);

snow_monkey_forms/administrator_mailer/args

例えば、お問い合わせの内容によってメールの送信先を変更したりできます。

$argsが設定値です。
$respomserでフォームの入力値が扱えます。
$settingでフォームの設定値が扱えます。

チェックボックスで選んだ送信先にメールを送信するには下記のようにします。
例えば、チェックボックスの name を 'multiple-to' として、value にメールアドレスを指定します。
フォームのチェックボックスでチェックした送信先（複数可）に管理者あてメールが送信されます。
チェックしないとフォーム設定の送信先に送信されます。

チェックボックス 'multiple-to' の value

'kawai@cherrypieweb.com':'川井'
'tanaka@cherrypieweb.com':'田中'
'suzuki@cherrypieweb.com':'鈴木'

/*
 * チェックボックスの値をメール送信先に設定する
 */
add_filter(
	'snow_monkey_forms/administrator_mailer/args',
	function( $args, $responser, $setting ) {
		if ( $responser->get( 'multiple-to' ) ) {
			$args['to'] = implode(',', $responser->get( 'multiple-to' ) );
		}
		return $args;
	},
	10,
	2
);

こちらの記事もわかりやすいです。

snow_monkey_forms/auto_reply_mailer/skip

trueを返すとユーザーあての自動返信メールを送信しません。
（内部的にはユーザーあての自動返信メールが送信されたものとして扱われます）

add_filter(
	'snow_monkey_forms/auto_reply_mailer/skip',
	'__return_true'
);

snow_monkey_forms/administrator_mailer/skip

trueを返すと管理者あての自動返信メールを送信しません。
（内部的には管理者あての自動返信メールが送信されたものとして扱われます）

実は私にはちょっと使い道がわからなかったのですが、Slackでキタジマさんに伺ったところ、例えば外部のASPにデータをとばして管理するといった用途を想定されているそうです。
（後述の snow_monkey_forms/administrator_mailer/after_send フックを使うということになるのでしょうか？）

実際に使われている方がいらっしゃったら教えていただけると嬉しいです。

add_filter(
	'snow_monkey_forms/administrator_mailer/skip',
	'__return_true'
);

snow_monkey_forms/auto_reply_mailer/is_sended

falseを返すと内部的にはユーザーあての自動返信メールの送信が失敗されたものとして扱われます。
実際のメール送信処理には影響しません。

実はちょっと使い道がわかりません。デバッグ用なのでしょうか？

add_filter(
	'snow_monkey_forms/auto_reply_mailer/is_sended',
	'__return_false'
);

snow_monkey_forms/administrator_mailer/is_sended

falseを返すと内部的には管理者あての自動返信メールの送信が失敗されたものとして扱われます。
実際のメール送信処理には影響しません。

実はちょっと使い道がわかりません。デバッグ用なのでしょうか？

add_filter(
	'snow_monkey_forms/administrator_mailer/is_sended',
	'__return_false'
);

（管理者あてメール）
snow_monkey_forms/administrator_mailer/headers

（ユーザーあてメール）
snow_monkey_forms/auto_reply_mailer/headers

（共通）
snow_monkey_forms/mailer/headers

メールヘッダーの書式に従ってカスタマイズ内容を記述します。
メールの件名も変更できます。

フィールドの入力値は、$responser->get( 'フィールドのNAME値' ); で取得できます。
フォームの設定値は、$setting->get_control( '設定項目のNAME値' ) で取得できます。

/*
 * 管理者あてメールとユーザーあてメールにCc, Bcc, Reply-to を指定する
 */
add_filter(
	'snow_monkey_forms/mailer/headers',
	function ($headers, $responser, $setting) {
		return [
			'Cc: cc@example.com',
			'Cc: cc2@example.com',
			'Bcc: bcc@example.com',
			'Bcc: bcc2@example.com',
			'Reply-to: rpy@example.com',
		];
	}
);