コードサンプル
基本的な書き方は、以下のGistを参照くだだい。
WordPressのビルトインセクション
WordPressでもともと用意されている、add_control で指定できるセクション。
| title_tagline | サイトタイトルと説明文 |
| colors | 色 |
| header_image | ヘッダー画像 |
| background_image | 背景画像 |
| static_front_page | ホームページ設定 |
フィールドタイプ
add_control の type で指定できるタイプ名。他にもあると思う。
| text | 1行テキスト |
| textarea | 複数行テキスト |
| メールアドレス | |
| number | 数値 |
| url | URL |
| select | セレクトボックス |
| checkbox | チェックボックス |
| radio | ラジオボタン |
| dropdown-pages | ドロップダウン固定ページ |
設定値の読み出しには get_theme_mod()を使う
<?php
return get_theme_mod(設定ID, デフォルト値);第1引数は設定ID、第2引数はデフォルト値を設定できる。add_setting の第2引数の default="xxx" でデフォルト値を設定してない場合でも、こちらに設定しておけば良い。
get_theme_mod()の注意点
注意点として、add_setting の第2引数に 'type' => 'option' 等を設定していると、get_theme_mod() が使えないので、覚えておくべし。
というのも、デフォルトでは theme_mods_テーマ名 という名前でoptionに登録されるのだが、 'type' => 'option' を設定した項目は、設定IDの名前でデータベースのoptionに登録されるため。なので、その場合 get_option() で取得する必要がある。
サニタイズ sanitize_callback
設定項目には sanitize_callback を指定するべき。なくても動くけど、テーマを公式リポジトリに公開するには全ての設定項目に sanitize_callback を設定しなければなりません。
テキスト / テキストエリア
sanitize_text_field
HTMLタグの削除や記号のエスケープなどで文字列を無害化する。前後の半角スペースのトリミングも行われる。
wp_strip_all_tags
script と style を含むすべてのHTMLタグを削除する。
wp_filter_nohtml_kses の方が、不正なHTMLをよりよい方法で処理しようとするが、完全なHTMLパーサーではなく、かつはるかに遅い。通常は wp_strip_all_tags が推奨される。
CSS
wp_strip_all_tags を使うとよい。
HTML
wp_filter_post_kses
文字列を無害化するが、HTMLタグが使える。script タグは削除される。インラインスタイルの display 属性など特定のプロパティは削除される。クオーテーション, ダブルクオーテーションはエスケープされる。
メールアドレス
sanitize_email
メールアドレスに使用できない文字を削除する。
URL
esc_url_raw
URLエンコードされる。
色
sanitize_hex_color
有効なHEXカラー（#000000 から #ffffff まで）の場合はそのまま、それ以外は null を返す。
数値
absint
数値を正の整数に変換する。
チェックボックス
自前で用意する。
function themename_sanitize_checkbox($input) {
return (isset($input) ? true : false);
}ラジオボタン / セレクトボックス
さまざまなサイトでこれ↓が紹介されているが…僕の環境では$choices が null になってしまうので使えない。
function themename_sanitize_select($input, $setting) {
$input = sanitize_key($input);
$choices = $setting->manager->get_control($setting->id)->choices;
return (array_key_exists($input, $choices) ? $input : $setting->default);
}null になる原因は、get_control() の引数に control のIDではなく setting のIDを入れてるからだと思うんだけど、皆はこれでうまく取得できているのだろうか？
もちろん、control のIDを手動でハードコードすると choices を正しく取得できる。つまり $setting からそれぞれの control のIDを取得できれば解決するのだが、ググっても方法がわからない。（上のコードばかり出てくる）。
というわけで、僕は代替としてsanitize_text_field を使ってる。
ドロップダウン固定ページ
absint を使う。
ファイルアップロード
自前で用意する。
function theme_slug_sanitize_image($input, $setting) {
$mimes = array(
'jpg|jpeg|jpe' => 'image/jpeg',
'gif' => 'image/gif',
'png' => 'image/png',
'svg' => 'image/svg+xml',
'bmp' => 'image/bmp',
'tif|tiff' => 'image/tiff',
'ico' => 'image/x-icon'
);
$file = wp_check_filetype($input, $mimes);
return ($file['ext'] ? $input : $setting->default);
}
