プラグインのオプション設定を追加する際に指定できるサニタイズ関数いろいろ|Personal WP Customization Notes (PWCN)

公開日：2023(令和5)年8月18日／最終更新日： 2024(令和6)年5月1日

自作プラグインで、独自のオプション設定画面で、入力された値をデータベースのoptionsテーブルへ保存するために使用する「register_setting()」関数。

こんな感じで記述しますよね？

register_setting(
'表示している場所', 
'設定名',
[
'sanitize_callback' => 'サニタイズ用コールバック関数',
]
);

何かのデータを保存や出力前に検証して無害なものかどうかを判断したり、無効にすることを総称して「サニタイズ」といい、「register_setting」でコードを作る際に使用する「sanitize_callback」で指定するコールバック関数は、いらないものを除去したり、無効なデータは保存しないようにしてくれたりするので、セキュリティ上重要な役割を果たします。

原則どの項目タイプでも設定しておくべきですが、特に重要なのが何かのテキストを入力して保存する項目です。これに対してサニタイズ処理を怠ると、データ検証が行われず、何でもかんでもデータベースにデータとして保存されてしまうことにもつながります（厳密にはinputのvalue値などでもサニタイズはできるものの、データ保存前の最後の砦として必ずコールバック関数を指定しておくべきだと思います）。

ただ、コードを作っている時、自身でいつも「どれだっけ？」となってしまうので、主要なコールバック関数と用途をメモとして公開しておきます。

文末におまけで「サニタイズとエスケープの違い」というのも実験を踏まえて書いていますので、興味のある方はどうぞ。

本ページ掲載のコードを使用するときは

本ページで掲載しているコードは、以下に了承した上で使用ください

コードは商用・非商用問わず自由に使っていただいて構いませんが、コード追加による不具合やトラブルが発生しても当方では一切責任を負いません
コードは有効化しているテーマのfunctions.php、style.cssなどへ追加することで機能します。それらのファイルへの変更を行うことに不安のある方は使用しないでください
コードは本ページの公開日時点で私の環境において動作したものです。WordPressバージョン他環境の違いによって動作しないことがあります
コードは、セキュリティ、コードの正確さなどにおいて完全なものではありません。中には紹介するコードを簡略化するために省略している部分があるものもありますので、ご自身でコードを十分に検証し、必要な部分の編集を行った上で使用するようにしてください
掲載しているのは参考コードです。自身の環境に合わせるための編集はご自身で対応いただく必要があります（コメント欄等から質問いただいても基本回答は致しません）
掲載しているコードの転載を禁じます（SNSで紹介いただいたり、本ページへのリンクを張っていただくことは大歓迎です）

設定画面のサニタイズに使うコールバック関数いろいろ

コールバック関数は基本的に入出力両方に使えるサニタイズ処理関数で、入力（データベース保存）時には

'sanitize_callback' => 'サニタイズ用コールバック関数'

と記述し、出力時には

echo サニタイズ用コールバック関数('文字列');
return サニタイズ用コールバック関数('文字列');

などと記述することで、データの安全性を保ちます。

出力時には出力する値をサニタイズして一旦変数に格納後、echoやreturnで呼び出した方がよいと案内してる資料もあります。

$data = サニタイズ用コールバック関数('文字列');

echo $data;
return $data;

確かにこれで一度変数化してるからより安全な感じはしますが、実際どうなのかというのは不明です。

ただ1つ言えるのは、echoやreturnで返す時、単純な性質の文字列やタグであることが少ないので、それぞれのデータを変数化して、それらを確実に無害化するという意味では、非常に有効だと思いますから、コードを書く時の癖として定着させるといいと思います。

出力時にコンテンツのコールバック関数を使って呼び出すという方法もありますが、本ページの主旨と外れていきますので割愛します

データの入力時と出力時で制限を変えることは少ないですから、入出力時に同じコールバック関数を使うことで、保存できたけど出力されない（またはその逆）といったトラブルを回避することができます

データサニタイズ（消毒）用のコールバック関数は、大きく分けてWordPressやPHPが予め用意しているものと、データの性質によって自身で作成しなければならないものの2種類があります。

WordPressやPHPでコールバック関数が用意されているもの

※コールバック関数名をクリックするとWordPress公式やPHP公式の解説ページを見ることができます

「sanitize_text_field」

「sanitize_text_field」はテキスト入力を行うフォームで、以下に該当されると判断されるものをすべて除去します。

UTF-8形式に準拠していない文字列を削除します
単一の<文字をエンティティ「<」に変換してタグを文字列として表示させるようにします
すべてのタグを削除します
改行、タブ、余分な空白を削除します
パーセントエンコードされた文字（例：「<」 =「 %3C」など）を削除します

HTMLタグなどがなく全角・半角文字を用いて文字列で入力する項目に汎用的に使えます。

「absint()」

入力された値を正の整数のみにして保存します。数字やIDの指定のみをさせる場合や、セレクトボックスやラジオボタンで選択された値を数字として格納する場合、また、正の整数のみを出力する場合に使用します。

「sanitize_url()」

URLかどうかを判別します。URLではないと判断されたものは保存・出力されません。

保存・出力できるURLに「https（SSL通信）」だけを含める場合には、以下のようなコールバック関数を作って使用します。

function url_sanitize($data){
return = sanitize_url( $data, array('https') );
}

【保存時】

'sanitize_callback' => 'url_sanitize'

【出力時】

echo url_sanitize('文字列');
return url_sanitize('文字列');

この関数はWordPressバージョン2.8.0で一度非推奨になり、5.9.0で復活しました

「sanitize_email()」

メールアドレスとして使用できない文字列を削除して、保存・出力します。また、メールアドレスと認識できない場合は何もしません（データは破棄されて保存されず、出力もされません）。

「sanitize_hex_color()」

入力された値がHEX値のカラーコード（「#000」や「#000000」）かどうかを判断します。

「sanitize_hex_color_no_hash()」

入力された値が「#」を除くHEX値のカラーコード（「000」や「000000」）かどうかを判断します。

自身でコールバック関数を作成する必要があるもの

チェックボックス

チェックボックスでチェック（True）/未チェック（False）以外の値がないかをチェックします。

function sample_sanitize_checkbox( $checked ) {
	// Boolean check.
	return ( ( isset( $checked ) && true == $checked ) ? true : false );
}

上記コードの場合、入出力時には「sample_sanitize_checkbox」と指定します。

画像アップロード(URL)

アップロードされた画像のURLを検証して画像かどうかをチェックします。

function sample_sanitize_image( $input ) {
	$filetype = wp_check_filetype( $input );
	if ( $filetype['ext'] && wp_ext2type( $filetype['ext'] ) === 'image' ) {
		return esc_url( $input );
	}
	return '';
}

上記コードの場合、入出力時には「sample_sanitize_image」と指定します。

画像IDを扱う場合は、正の整数ですので「sanitize_text_field」か「absint」を使用します

CSS入力

テキスト入力欄に入力されたスタイルコードをサニタイズします。

function sample_sanitize_css( $input ) {
	return wp_strip_all_tags( $input );
}

上記コードの場合、入出力時には「sample_sanitize_css」と指定します。

スクリプト

テキスト入力欄にカスタムスクリプトを入力するような利用ケースの場合に使用します。

一度無害な状態で保存したものを、動作する状態で出力するという形になるので、厳密にはサニタイズということにはならないかも知れませんが、一応掲載しておきます。

以下は保存時に文字列を変換（エンコード）するための関数です。

function sanitize_js_code($data){
	return base64_encode($data);
}

そして以下のようにコールバック指定します。

'sanitize_callback' => 'sanitize_js_code'

続いて出力する際に再変換（デコード）する関数を追加します。

function sanitize_js_decode($data){
	return base64_decode($data);
}

以下のような形で出力します。

echo sanitize_js_decode('文字列');
return sanitize_js_decode('文字列');

許可するHTMLタグを制限できるwp_ksesの使い方（例）

私も完全に理解していないので、ひょっとすると間違っているかも知れませんが、フォームに入力されたHTMLタグをサニタイズする方法に「wp_kses()」というのがあります。

wp_kses()

サニタイズ用のコールバックとして使うなら、以下のように「wp_kses」を指定すれば、この関数で許可されているHTMLタグ以外は保存時に削除されるというものです。

'sanitize_callback' => 'wp_kses',

また、どこかで出力する場合はこの関数で囲むことで、許可されていないHTMLタグは削除されて出力されます。

echo wp_kses('HTMLソース');

そして、これをより使いやすくしたものが、「wp_kses_post()」という関数です。

wp_kses_post()

基本的な使い方は「wp_kses()」と同じで、実はこれ、以下のコードが示す通り、「wp_kses()」のうちの「post」（投稿に用いるであろうHTMLタグ）を許可した単独の関数化なのです。

function wp_kses_post( $data ) {
	return wp_kses( $data, 'post' );
}

まあ、投稿編集画面で使用できるようなHTMLのみを許可するのであれば、「wp_kses_post()」を使っておけば、特に問題ないとは思うのですが、そもそもこの許可するHTMLタグが何なのか？は詳しく書かれていません。

そこで、敢えて抽出してみたのが下のテキストです。

例えば、「a」タグは許可されていて、「href」「rel」「name」．．などの属性が利用可能というような見方をします。

繰り返しますが、まあこれでも問題ないのですが、場合によっては、入力できる値をもっと絞り込んでおきたいというケースもあると思います。

そこで柔軟に設定できるのが「wp_kses()」のいいところで、以下のようにすると、特定のHTMLタグのみ許可されるようになります。

function sample_wp_kses($input){
$allowed_html = array(
    'a' => array(
        'href' => array(),
        'title' => array()
    ),
    'br' => array(),
    'em' => array(),
    'strong' => array(),
);
  
return wp_kses($input, $allowed_html);
}

コードの概要としては、「sample_wp_kses」というユーザー定義関数（コールバック = 使いまわし用の関数）を用意して、許可するのは「a」「br」「em」「strong」タグと、「a」タグについては「href」と「title」の属性のみを許可するというものです。

これを設定画面のコールバック関数へ以下のように加えると機能します。

'sanitize_callback' => 'sample_wp_kses',

試しに、自作プラグインへ上記の関数を追加し、設定画面のプログラムでコールバック設定を行った上で、許可されている以外のタグを入力して保存すると．．．ね、許可されていないタグは見事に削除されるというわけです。

また、出力時には、このように記述することで機能します。

echo sample_wp_kses($content);

これを覚えると、いろいろなところで確実な制御ができますね。

ただ、唯一気を付けなければいけないのが、保存時と出力時で設定を合わせるか、出力側ので許可するHTMLタグが、確実に保存側で許可するHTMLタグを含んでいることです。

逆になっていると保存はできているのに出力されないというトラブルが起きますからね。これも先ほど同様に試してみると理解できると思います。

そうならないためにも、フォーム保存時のコールバック関数と出力時のコールバック関数は合わせておいた方が無難でしょう。

ちなみに私の場合はこんな風に独自のコールバック関数を作って使用しています（まだ多いかも）。

/* HTMLタグのコールバック */
function sample_sanitize_html_tags( $input ){
$allowed_tags = array(
	'a' => array(
		'class' => array(),
		'href'  => array(),
		'rel'   => array(),
		'title' => array(),
	),
	'aside' => array(
		'class' => array(),
		'style' => array(),
	),
	'b' => array(),
	'blockquote' => array(
		'cite'  => array(),
	),
	'br' => array(),
	'button' => array(
		'id' => array(),
		'class'  => array(),
		'style' => array(),
	),
	'cite' => array(
		'title' => array(),
	),
	'code' => array(),
	'del' => array(
		'datetime' => array(),
		'title' => array(),
	),
	'dd' => array(),
	'div' => array(
		'id' => array(),
		'class' => array(),
		'title' => array(),
		'style' => array(),
	),
	'dl' => array(),
	'dt' => array(),
	'em' => array(),
	'h1' => array(
		'class' => array(),
		'style' => array(),
	),
	'h2' => array(
		'class' => array(),
		'style' => array(),
	),
	'h3' => array(
		'class' => array(),
		'style' => array(),
	),
	'h4' => array(
		'class' => array(),
		'style' => array(),
	),
	'h5' => array(
		'class' => array(),
		'style' => array(),
	),
	'h6' => array(
		'class' => array(),
		'style' => array(),
	),
	'i' => array(),
	'img' => array(
		'alt'    => array(),
		'class'  => array(),
		'height' => array(),
		'src'    => array(),
		'width'  => array(),
	),
	'li' => array(
		'class' => array(),
		'style' => array(),
	),
	'nav' => array(
		'id' => array(),
		'class' => array(),
		'style' => array(),
	),
	'ol' => array(
		'class' => array(),
		'style' => array(),
	),
	'p' => array(
		'class' => array(),
		'style' => array(),
	),
	'q' => array(
		'cite' => array(),
		'title' => array(),
	),
	'section' => array(
		'id' => array(),
		'class' => array(),
		'style' => array(),
	),
	'span' => array(
		'class' => array(),
		'title' => array(),
		'style' => array(),
	),
	'strong' => array(),
	'ul' => array(
		'class' => array(),
		'style' => array(),
	),
);

	return wp_kses($input, $allowed_tags);
}

参考：WordPress Basic Allowed HTML for wp_kses

サニタイズとエスケープの違い

今回は「サニタイズ」という単語でずっと内容を書いてきました。同じようにデータセキュリティを向上させる言葉に「エスケープ」というのがあり、私同様違いは何？と戸惑う方も多いでしょう。

いろいろと呼んでいると、実は「サニタイズ」（無害化する、消毒する）という意味の処置の中に、「エスケープ」という処置があり、「エスケープ」は、有害なタグや使われたくないタグの文字列などを「文字」として扱う記号に変換するものを指すようです。

一方「サニタイズ」は広義なので、「エスケープ」と同様にふるまうものもあれば、「エスケープ」のように変換して無害化しつつ、許可されていないタグを削除してしまうという処置をするものも含まれます。

あくまでもWordPress上での用語の使い分けとして、「入力されたものをそのままにしつつ、セキュリティを担保する」場合は「エスケープ」を、「有害なものは除去することを前提にセキュリティを担保する」場合は「サニタイズ」と覚えておけばよいのだと思われます。

ちなみに、どちらもコールバック関数としても使えますし、出力時にも使えます。

具体的な処理の違い（例）

フォームのテキスト入力欄に以下の同じ要素を入れて、実際の振る舞いがどう違うかをテストしてみました。

<div>
	<p>あいうえお</p>
</div>

エスケープ関数としてよく使われる「esc_html」と、同じようにタグを削除するために良く使われる「sanitize_text_field」というサニタイズ関数を、それぞれ入出力両方に使ってチェックしました。

「esc_html」の場合

データベースへ保存される段階で「esc_html」がタグの記号を文字列化して以下のように保存されました。

&lt;div&gt;
	&lt;p&gt;あいうえお&lt;/p&gt;
&lt;/div&g...

出力する際にも同じ「esc_html」を使っていますが、既にデータが記号を文字列化しているので、フロントエンドではそのまま表示されました。

ただ、管理画面の入力欄自体は以下のように入力したままになっていて（文字列化した記号は再変換されていて）、以下のように表示されていました。

個人的には、「なぜ入力欄上で表示されるのに、フロントエンドでは記号化されてしまうの？」という風に思うかもという印象でした。

「sanitize_text_field」

「esc_html」の時と同じ入力を入出力双方を「sanitize_text_field」に変えてチェックしなおしました。

こちらはデータベースに保存する段階で、HTMLタグが除去され以下のように保存されていました。

あいうえお

表示させてみると、何もタグがないので単純な文字列「あいうえお」として表示されます。

そして、管理画面上は、除去されたHTMLタグはなくなり、下図のように「あいうえお」のみの表示に変わりました（まあデータベース上に文字しか保存されていないので当然ですが．．）

この結果から、HTMLタグを除去（無害化）するという性質のものでも違いがあり、個人的には、この関数の比較に関して言えば、すべての場面で同じように振る舞う「sanitize_text_field」の方が扱いやすい印象を受けました。

まあ「エスケープ」関数と呼ばれるものと、まったく同じ「サニタイズ」関数はないと思う（同じなら作る必要もない）ので、完全な比較は難しいですが、入力する人の立場と、どのようにセキュリティを担保したいかによって使い分けるのがよさそうです。

そういう意味では、別の場所からデータベースに格納されている「サイトタイトル」や「ページタイトル」を呼び出す場合には、入力欄との整合性が必要ないことが多いので「esc_html」でエスケープするっていうのも納得いく感じがしました。

本ページで掲載した内容や、紹介した参考コードなどがお役に立てたようでしたら、ページ末尾のコメント欄よりコメントを残す、SNS等で拡散するなどしていただけましたら幸いです。

本ページ掲載の方法やコード等はあくまでも最終更新日時点での私の環境において動作確認等を行ったものです。動作不良やカスタマイズの詳細な方法などをコメント欄よりいただきましても原則回答は致しませんのでご了承ください。

WordPressのカスタマイズに関するご要望はココナラにてお受けしております。お問い合わせ方法など詳しくはこちらをご覧ください。

最後までお読みいただきありがとうございました。

本ページで掲載している文章、画像、コード等すべてのコンテンツの著作権・所有権は当サイトにあり、転載を固く禁じます