add_allowed_options()

add_allowed_options() は、WordPress のオプション（設定値）をグループごとにホワイトリストへ追加する関数です。

この関数を使用すると、register_setting() を使わずに特定のオプションキーを許可リストに追加でき、設定保存時のバリデーションをカスタマイズできます。

主に、WordPress の update_option() を使用して設定を保存する際に、許可されていないオプションが保存できない問題を解決するために利用されます。

機能の説明

add_allowed_options() は、特定のオプションキーを指定のオプショングループに追加し、update_option() で設定値を変更できるようにする関数です。

通常、WordPress の options.php を経由して設定を保存する場合、デフォルトで許可されていないオプションは保存されませんが、この関数を使用すると、指定したオプションキーが許可リストに追加され、保存できるようになります。

• update_option() を使用してオプションを保存する際にエラーが発生する場合
• register_setting() を使用せずに、特定のオプショングループへオプションを追加したい場合
• カスタム設定ページで独自のオプションを管理する際に、許可リストを拡張したい場合

シンプルなコード例

以下のコードは、my_plugin_options というオプショングループに custom_setting を追加する例です。

add_allowed_options('my_plugin_options', array('custom_setting'));

この設定を行うことで、update_option('custom_setting', 'value') を使用して custom_setting を保存できるようになります。

使い方の説明

基本的な使用例

以下のコードは、my_plugin_options グループに複数のオプションキーを追加する方法です。

add_allowed_options('my_plugin_options', array('option_one', 'option_two'));

この設定を行うことで、以下のように update_option() を使ってオプションを保存できるようになります。

update_option('option_one', 'value1');
update_option('option_two', 'value2');

引数

• $group（文字列）：オプショングループの名前
• $options（配列）：許可リストに追加するオプションキーの配列

戻り値

• なし（設定が追加されるだけ）

一緒に使うことが多い関連タグ

update_option()

オプションの値を更新する関数。

update_option('custom_setting', 'new_value');

get_option()

オプションの値を取得する関数。

$value = get_option('custom_setting');
echo $value;

register_setting()

通常の設定登録時に使用される関数。
add_allowed_options() を使わない場合は、こちらを使用するのが一般的。

register_setting('my_plugin_options', 'custom_setting');

追加情報で取得したい場合

すべてのオプショングループを取得する

現在登録されているオプショングループを確認するには、以下のコードを使用できます。

global $wp_registered_settings;
print_r($wp_registered_settings);

許可リストに登録されたオプションを取得する

現在のオプションホワイトリストを確認する方法は、以下のようになります。

global $allowed_options;
print_r($allowed_options);

想定されるトラブル

update_option() で値が保存されない

• add_allowed_options() が適切な場所で実行されているか確認（admin_init フック内で実行するのが推奨）
• 指定したオプショングループ名が正しいか確認
• options.php を経由しない場合は register_setting() も検討する

add_allowed_options() が反映されない

• functions.php やプラグインの init フック内で設定しているか確認
• add_allowed_options() の呼び出し後に、対象のオプションを update_option() で保存してみる

Q＆A

まとめ

add_allowed_options() は、WordPress のオプション保存時に許可リストへ追加する関数です。

update_option() を使って保存する際の制約を回避し、カスタムオプションを簡単に扱えるようになります。