管理メニュー

PHP

【WordPress】管理画面上部にadd_settings_error()でメッセージを表示する

更新日：2023/02/02

WordPressの管理画面の上部に、左端に緑や赤などのボーダーと共にメッセージが表示されているのを目にしたことがあると思います。
今回は、このようなメッセージを表示する方法をお伝えします。

メッセージの種類

add_settings_error()を使用すると、次のような４種類のメッセージを管理画面に表示できます。

■info

■success

■warning

■error

コード例

管理画面にエラーメッセージを表示する時は、add_settings_error()でメッセージを登録します。
関数の解説の前に、コード例を紹介します。

入力値の検証してエラーメッセージを表示

管理画面でメッセージを表示する場面は、入力された値を検証してエラー表示するケースが考えられます。
次のようなコードで検証とエラー表示できます。

$option_name = 'my_option_item';
register_setting( 'my_option_page', $option_name );

add_filter( "pre_update_option_{$option_name}"
	, function( $value, $old_value, $option){

		if( preg_match('/^[a-zA-Z]+$/',$value) ) return $value;

		add_settings_error($option, $option, 'アルファベットのみを指定', 'error');
		return $old_value;
	},10,3 );

この記事では上記のコードについての詳しい解説はしませんので、次のページを読んでみてください。

特定の管理画面にメッセージを表示

次のコードは、特定の管理画面にadd_settings_error()でメッセージ表示しています。

add_action('all_admin_notices',function(){
	global $hook_suffix;
	if ('my_test_menu' !== substr($hook_suffix, -strlen('my_test_menu'))) return;
	add_settings_error('my_test_menu', 'my_test_menu', 'メッセージ' , 'info');
	settings_errors();
});

このコードについては、次のページを読んでみてください。

全ての管理画面に共通メッセージを表示

次のコードは、全ての管理画面にadd_settings_error()でメッセージ表示しています。

add_action('all_admin_notices',function(){
	add_settings_error('my_test_menu', 'my_test_menu', 'メッセージ' , 'info');

	global $hook_suffix,$parent_file;
	if ( 'options-general.php' === $parent_file ) return;

	$array = array('export-personal-data.php'
					,'erase-personal-data.php');
	if( in_array($hook_suffix,$array) ) return;

	settings_errors();
});

このコードを見ただけだと、if文での判定の意味がわからないと思います。
次の記事で解説しているので読んでみてください。

add_settings_error()の構文

add_settings_error()は、エラー情報を登録します。

add_settings_error( $setting, $code, $message, $type = 'error' )

• $setting :
  メッセージをグループ化するための文字列。
  ほとんど使用されないので、なんでもいい。

• $code :
  出力タグのid属性の一部として使用される。
  生成されるid属性 => 'setting-error-' . esc_attr($code)

  値はなんでもいいが、id属性なので重複しないようにする。

• $message :
  出力するメッセージ。
  そのまま出力されるので、リンクやテーブルなどを表示可能。

• $type :
  メッセージのタイプ。
  'error'、'success'、'warning'、'info'の４種類。
  クラス名の一部として出力され、cssにより左端の色分けに使用される。

  生成されるクラス属性 => 'notice notice-'. esc_attr($type) . ' settings-error is-dismissible'

  ただし$typeの前に'notice-'が付加されるのは、4つの値の時のみ。

  異なるクラス名を割り込ませたいときは、$type = 'notice-info my-class' のように指定する。

この関数は、次のように受け取った引数をグローバル変数にセットしているだけです。

function add_settings_error( $setting, $code, $message, $type = 'error' ) {
	global $wp_settings_errors;

	$wp_settings_errors[] = array(
		'setting' => $setting,
		'code'    => $code,
		'message' => $message,
		'type'    => $type,
	);
}

メッセージ出力はsettings_errors()が必要

add_settings_error()で登録したメッセージの出力は、settings_errors()でおこないます。

settings_errors()は、『設定』の各サブメニューと『ツール』の個人データのエクスポートと個人データの削除でのみ呼び出されています。（※WordPressのバージョン6.1.1の場合）

そのため、他の管理画面はsettings_errors()を実行する必要があります。

方法は、この記事の特定の管理画面にメッセージを表示または全ての管理画面に共通メッセージを表示のコード例を参考にしてください。

『変更を保存』押下時の流れ

■データベース登録後リダイレクトされる

管理画面の『変更を保存』ボタンを押すと、/wp-admin/options.phpが呼び出されて入力値がデータベースに保存されます。
その後、元の管理画面のＵＲＬにリダイレクトされて管理画面が再描画されます。

リダイレクト後はプロセスが異なるためグローバル変数はリセットされます。

■options.phpでadd_settings_error()を呼び出した場合

例えば/wp-admin/options.phpで値の検証を行いエラー判定されたら、add_settings_error()を呼び出したとします。
しかし、その情報を保持するグローバル変数はリダイレクト後にリセットされます。
従って、エラーメッセージを受け渡すことができません。

■キャッシュで対応

そこでWordPressはset_transient()でメッセージのデータをキャッシュします。
そして元の管理画面側でキャッシュを取り出して、元の管理画面でセットしたエラー情報と連結しています。

■キャッシュは30秒

この時、キャッシュは30秒制限がかかっています。
それ以上経過するとキャッシュから消去されます。

今回ブレークポイントを設置して処理を追っていたら、メッセージが表示されないので非常に混乱しました。
30秒以上経過したのが原因だと気づくのに時間がかかりました。

関連記事

スポンサーリンク

記事の内容について

こんにちはけーちゃんです。
説明するのって難しいですね。

「なんか言ってることおかしくない？」
たぶん、こんなご意見あると思います。

裏付けを取りながら記事を作成していますが、僕の勘違いだったり、そもそも情報源の内容が間違えていたりで、正確でないことが多いと思います。
そんなときは、ご意見もらえたら嬉しいです。

掲載コードについては事前に動作確認をしていますが、貼り付け後に体裁を整えるなどをした結果動作しないものになっていることがあります。
生暖かい視線でスルーするか、ご指摘ください。

ご意見、ご指摘はこちら。
https://note.affi-sapo-sv.com/info.php

 

このサイトは、リンクフリーです。大歓迎です。