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

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

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

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

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

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' );
//3つのオプションの値を一つの配列として保存
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>

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

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";} |
+-----------+---------------+------------------------------------------------------------------------------------------------------------------------------+

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

<?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'] ).'" />';
}

関連記事の目次

コメントを残す

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