register_setting() の使い方｜説明・引数・注意点

説明

基本構文

register_setting( string $option_group, string $option_name, array $args = array() ): void

引数

• $option_group：設定グループ名
• $option_name：オプション名
• $args：type、sanitize_callback、default、show_in_rest など

戻り値

戻り値はありません。

使い方（サンプル）

add_action( 'admin_init', function() {
	register_setting( 'my_group', 'my_option', array(
		'type'              => 'string',
		'sanitize_callback' => 'sanitize_text_field',
	) );
} );

注意点

• admin_init フックで呼びます。
• sanitize_callback を必ず指定して、保存値を検証します。

実務での使いどころ

• プラグインやテーマの設定を、Settings API で、保存するときの、最初の登録。
• 保存時の、サニタイズの関数（sanitize_callback）を、指定するとき。

よくあるミスと対処

• admin_init フックの外で呼んでいる。
• sanitize_callback を、指定していない。入力値が、そのまま保存される。
• $option_group が、フォームの settings_fields() と、合っていない。
• show_in_rest を指定せず、REST APIやブロックエディターから、使えない。
• show_in_rest で、REST API・ブロックエディターから使う設定は、admin_init ではなく、init フックで登録する（admin_init は、RESTのリクエストでは実行されない）。

NG例

register_setting( 'my_group', 'my_option' ); // sanitize がなく、フックの外

OK例

add_action( 'admin_init', function () {
	register_setting( 'my_group', 'my_option', array(
		'type'              => 'string',
		'sanitize_callback' => 'sanitize_text_field',
		'default'           => '',
	) );
} );

使い分け早見表

関連項目

add_settings_section()、add_settings_field()、settings_fields()

公式リファレンス：register_setting() | Function | WordPress Developer Resources