WordPressのSetting APIを使ってプラグインの設定ページを作成

WordPressのSetting APIを使って設定ページを作成する方法を確認し、実際にサンプルを作成しました。

※目次をクリックすると目次の下部にコンテンツが表示されます。

Setting APIの概要
・WordPressで使用するオプションの値を簡単にセキュアに保存できる。
・セキュリティチェックを行ってくれ、フォーム内にnonceを手動で指定する必要がなくなる。
　
●主な関数
　
・設定の登録
register_setting()
　
・フィールドやセクションの追加
add_settings_field()
add_settings_section()
　
・オプションフォームの作成
settings_fields()

新規にプラグインの設定ページを作成するサンプル
１）仕様
　
・トップレベルメニューにプラグインの設定ページを作成する。
・プラグイン設定ページの仕様
スラグ：myplg_main_menu
設定項目：Name、Email、URL
　
２）プラグイン設定メニューを作成
　
●サンプルコード全体
　

add_action( 'admin_menu', 'myplg_create_menu' );
function myplg_create_menu() {
  add_menu_page( 'My Plugin Settings', 'My Settings',
    'manage_options', 'myplg_main_menu', 'myplg_settings_page' );
  add_action( 'admin_init', 'myplg_register_settings' );
}
function myplg_register_settings() {
  register_setting( 'myplg-settings-group',
    'myplg_options', 'myplg_sanitize_options' );
}
function myplg_sanitize_options( $input ) {
  $input['option_name'] = sanitize_text_field( $input['option_name'] );
  $input['option_email'] = sanitize_email( $input['option_email'] );
  $input['option_url'] = esc_url( $input['option_url'] );
  return $input;
}
function myplg_settings_page() {
?>
  <div class="wrap">
    <h2>My Plugin Options</h2>
    <form method="post" action="options.php">
      <?php settings_fields( 'myplg-settings-group' ); ?>
      <?php $myplg_options = get_option( 'myplg_options' ); ?>
      <table class="form-table">
        <tr valign="top">
          <th scope="row">Name</th>
          <td><input type="text"
                 name="myplg_options[option_name]"
                 value="<?php echo esc_attr(
                   $myplg_options['option_name'] ); ?>" /></td>
        </tr>
        <tr valign="top">
          <th scope="row">Email</th>
          <td><input type="text"
                 name="myplg_options[option_email]"
                 value="<?php echo esc_attr(
                   $myplg_options['option_email'] ); ?>" /></td>
        </tr>
        <tr valign="top">
          <th scope="row">URL</th>
          <td><input type="text"
                 name="myplg_options[option_url]"
                 value="<?php echo esc_url(
                   $myplg_options['option_url'] ); ?>" /></td>
        </tr>
      </table>
      <p class="submit">
        <input type="submit" class="button-primary"
          value="Save Changes" />
      </p>
    </form>
  </div>
<?php
}

　
①トップレベルメニューにオプション設定ページを追加（add_menu_page()）
　
●add_menu_page関数
　
add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position )
　
$page_title：メニューページのタイトル。HTMLのtitleタグのテキスト。
$menu_title：管理画面に表示されるメニュー名。
$capability：メニューを見るのに必要な権限。
$menu_slug：メニューのスラッグ。
$function：メニュー設定ページを表示するコールバック関数
$icon_url：メニュー横に表示されるアイコンファイルのURL（省略時は”）。
$position：メニューの追加位置（省略時はNULL）。
　

function myplg_create_menu() {
  add_menu_page( 'My Plugin Settings', 'My Settings',
    'manage_options', 'myplg_main_menu', 'myplg_settings_page' );
  add_action( 'admin_init', 'myplg_register_settings' );
}

　
②オプション設定ページのフォームで保存するオプションを定義（register_setting()）、サニタイズ
　
・フォームが保存できるオプションのホワイトリストにオプションを追加／削除する。
・セキュリティのために、各オプションの値をチェックするコールバック関数を指定できる。
・register_setting関数はadmin_initアクションフックで呼び出す。このフックは他の管理ページよりも先に呼び出され、このフォームを受け取るoptions.phpよりも先に呼び出される。
　
●register_setting関数
　
register_setting( $option_group, $option_name, $sanitize_callback )
　
$option_group：セッティンググループ名。settings_fields()で指定する値と同じにする。
$option_name：サニタイズ、保存するオプションの名前
$sanitize_callback：オプションの値をサニタイズするコールバック関数
　

register_setting( 'myplg-settings-group',
    'myplg_options', 'myplg_sanitize_options' );
//３つのオプションの値を一つの配列として保存
function myplg_sanitize_options( $input ) {
  $input['option_name'] = sanitize_text_field( $input['option_name'] );
  $input['option_email'] = sanitize_email( $input['option_email'] );
  $input['option_url'] = esc_url( $input['option_url'] );
  return $input;
}

　
③オプション設定ページ、HTMLフォームを作成
　
a)formタグの開始
　
下記のようにaction=”options.php”を指定する。
<form method=”post” action=”options.php”>
　
b)セッティンググループを使って上記②で定義したオプションとフォーム内のオプションをリンク
　
上記②のregister_setting()で指定したグループ名と同じにする。
　
settings_fields( ‘myplg-settings-group’ );
　
c)既存のオプションを取得
　
$myplg_options = get_option( ‘myplg_options’ )
　
d)フォームのフィールドを作成
　

<table class="form-table">
  <tr valign="top">
    <th scope="row">Name</th>
    <td><input type="text"
           name="myplg_options[option_name]"
           value="<?php echo esc_attr(
             $myplg_options['option_name'] ); ?>" /></td>
  </tr>

　
３）データベースに保存されたオプションの値
　

mysql> select option_id,option_name from wp_options where option_name like "%prowp%" ;

select option_id,option_name,option_value from wp_options where option_name like "%myplg%" ;

|     10491 | myplg_options | a:3:{s:11:"option_name";s:5:"test1";s:12:"option_email";s:17:"test1@example.com";s:10:"option_url";s:16:"http://test1.com";} |
+-----------+---------------+------------------------------------------------------------------------------------------------------------------------------+

既存の設定ページにプラグイン設定フォームを追加するサンプル
１）仕様
　
・既存の”表示設定”ページの下部にプラグイン設定セクションを追加する。
・プラグイン設定セクションの仕様
スラグ：myplg_main_menu
設定項目：有効のチェックボックス、名前
　
２）プラグイン設定セクションを既存の設定ページに追加
　
●サンプルの全体
　

<?php
add_action( 'admin_init', 'myplg_settings_init' );
function myplg_settings_init() {
//設定→表示設定ページの下部にプラグイン設定セクションを追加
  add_settings_section(
    'myplg_setting_section',
    'My Plugin設定',
    'myplg_setting_section',
    'reading'
  );
  // 設定オプションを登録
  add_settings_field(
    'myplg_setting_enable_id',
    'My Pluginの機能を有効にする',
    'myplg_setting_enabled',
    'reading',
    'myplg_setting_section'
  );
  add_settings_field(
    'myplg_saved_setting_name_id',
    '名前',
    'myplg_setting_name',
    'reading',
    'myplg_setting_section'
  );
  register_setting(
    'reading',
    'myplg_setting_values',
    'myplg_sanitize_settings'
  );
}
function myplg_sanitize_settings( $input ) {
  $input['enabled'] = ( $input['enabled'] == 'on' ) ? 'on' : '';
  $input['name'] = sanitize_text_field( $input['name'] );
  return $input;
}
// 設定セクション
function myplg_setting_section() {
  echo '<p>My Pluginのオプションを以下で設定</p>';
}
// チェックボックス入力のフォーム
function myplg_setting_enabled() {
  $myplg_options = get_option( 'myplg_setting_values' );
  echo '<input '.checked( $myplg_options['enabled'], 'on',false ).
       ' name="myplg_setting_values[enabled]"
         type="checkbox" /> 有効';
}
// 名前入力のフォーム
function myplg_setting_name() {
  $myplg_options = get_option( 'myplg_setting_values' );
  echo '<input type="text" name="myplg_setting_values[name]"
               value="'.esc_attr( $myplg_options['name'] ).'" />';
}

　
①設定セクションの追加（add_settings_section()）
　
・設定セクションは、WordPress設定ページでヘッダを共有するいくつかの設定のまとまり。
・新規ページを作成するのではなく、既存の設定ページにセクションを追加できる。
　
●add_settings_section関数
　
add_settings_section( $id, $title, $callback, $page )
　
$id：タグの’id’属性に使用する文字列。
$title：設定ページに表示するセクションのタイトル。
$callback：適切な内容のセクションを出力する関数。関数は出力をechoする必要がある。
$page：セクションを表示する設定ページのタイプ(general,reading,writing,media 等)。
　

add_settings_section(
  'myplg_setting_section',
  'My Plugin設定',
  'myplg_setting_section',
  'reading'
);

　
②設定フィールドを追加（add_settings_field()）
　
・既存のページに新たな設定フィールドを追加。
　
●add_settings_field関数
　
add_settings_field( $id, $title, $callback, $page, $section = ‘default’, $args = array() )
　
$id：タグの ‘id’ 属性に使用する文字列。
$title：設定ページに表示するフィールドのタイトル。
$callback；フォームの一部として、適切なinputを含むフィールドを表示する関数。inputのnameとidはこの関数の$idと一致する必要がある。関数は出力をechoする必要がある。
$page：フィールドを表示する設定ページのタイプ (general, reading, writing 等)。
$section：ボックスを表示する設定ページのセクション。
$args – 追加の引数
　

add_settings_field(
  'myplg_setting_enable_id',
  'My Pluginの機能を有効にする',
  'myplg_setting_enabled',
  'reading',
  'myplg_setting_section'
);

　
③オプション設定ページのフォームで保存するオプションを定義（register_setting()）、サニタイズ
　
・フォームが保存できるオプションのホワイトリストにオプションを追加／削除する。
・セキュリティのために、各オプションの値をチェックするコールバック関数を指定できる。
・register_setting関数はadmin_initアクションフックで呼び出す。このフックは他の管理ページよりも先に呼び出され、このフォームを受け取るoptions.php よりも先に呼び出される。
　
●register_setting関数
　
register_setting( $option_group, $option_name, $sanitize_callback )
　
$option_group：セッティンググループ名。settings_fields()で指定する値と同じにする。
$option_name：サニタイズ、保存するオプションの名前
$sanitize_callback：オプションの値をサニタイズするコールバック関数
　

register_setting(
  'reading',
  'myplg_setting_values',
  'myplg_sanitize_settings'
);

function myplg_sanitize_settings( $input ) {
  $input['enabled'] = ( $input['enabled'] == 'on' ) ? 'on' : '';
  $input['name'] = sanitize_text_field( $input['name'] );
  return $input;
}

　
④追加する設定項目のHTMLフォームのフィールドを作成
　
上記①②で指定したコールバック関数で定義。
　

①セクション部
function myplg_setting_section() {
  echo '<p>My Pluginのオプションを以下で設定</p>';
}

②チェックボックス入力のフォーム
function myplg_setting_enabled() {
  $myplg_options = get_option( 'myplg_setting_values' );
  echo '<input '.checked( $myplg_options['enabled'], 'on',false ).
       ' name="myplg_setting_values[enabled]"
         type="checkbox" /> 有効';
}
③名前入力のフォーム
function myplg_setting_name() {
  $myplg_options = get_option( 'myplg_setting_values' );
  echo '<input type="text" name="myplg_setting_values[name]"
               value="'.esc_attr( $myplg_options['name'] ).'" />';
}

関連記事の目次
WordPressプラグイン

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。

Proudly powered by WordPress