エスケープ関数

WordPressには、最も一般的なシナリオに使用できる多くのヘルパー関数があります。

各関数が何をするのかに注意を払いましょう。いくつかの関数はHTMLを削除し、他の関数はそれを許可します。エコーする内容とコンテキストに最も適した関数を使用する必要があります。エコーする際は常にエスケープを行い、事前には行わないようにしましょう。

  • esc_html()– 表示されるデータのセクションを囲むHTML要素がある場合はいつでも使用します。これによりHTMLが削除されます。
  1. <h4><?php echo esc_html( $title ); ?></h4>
  • esc_js()– インラインJavaScriptに使用します。
  1. <div onclick='<?php echo esc_js( $value ); ?>' />
  • esc_url()– srcおよびhref属性を含むすべてのURLに使用します。
  1. <img alt="" src="<?php echo esc_url( $media_url ); ?>" />
  • esc_url_raw()– データベースにURLを保存する場合や、エンコードされていないURLが必要な他のケースで使用します。
  • esc_xml()– XMLブロックをエスケープするために使用します。
  • esc_attr()– HTML要素の属性に出力されるすべての他のものに使用します。
  1. <ul class="<?php echo esc_attr( $stored_class ); ?>">
  • esc_textarea()– テキストエリア要素内で使用するためにテキストをエンコードするために使用します。
  • wp_kses()– 信頼されていないすべてのHTML（投稿テキスト、コメントテキストなど）を安全にエスケープするために使用します。これによりHTMLが保持されます。
  • wp_kses_post()– 投稿コンテンツで許可されているすべてのHTMLを自動的に許可するwp_kses()の代替バージョンです。
  • wp_kses_data()– 投稿コメントで許可されているHTMLのみを許可するwp_kses()の代替バージョンです。

カスタムエスケープの例

特定の方法で出力をエスケープする必要がある場合、関数wp_kses()（「キス」と発音されます）が役立ちます。

この関数は、指定されたHTML要素、属性、および属性値のみが出力に含まれることを保証し、HTMLエンティティを正規化します。 

  1. <?php
  2. echo wp_kses_post( $partial_html );
  3. echo wp_kses(
  4.    $another_partial_html,
  5.    array(
  6.    'a'      => array(
  7.    'href'  => array(),
  8.    'title' => array(),
  9.    ),
  10.    'br'     => array(),
  11.    'em'     => array(),
  12.    'strong' => array(),
  13.    )
  14. ); ?>

この例では、<a>、<br>、<em>、および<strong>以外のすべてのタグが削除されます。さらに、<a>タグが渡された場合、エスケープによりhrefとtitleのみが返されることが保証されます。

常に遅れてエスケープ

出力エスケープはできるだけ遅く行うのが最良であり、理想的にはデータが出力されるときに行います。

遅れてエスケープする方が良い理由はいくつかあります：

  • コードレビューとデプロイが迅速に行えるため、出力が安全であると一目で判断でき、すでにエスケープされているかどうかを確認するために多くのコード行を探す必要がありません。
  • 変数が最初にキャストされたときと出力されるときの間に意図せず変更される可能性があり、潜在的な脆弱性を引き起こす可能性があります。
  • 遅れてエスケープすることで、自動コードスキャンが容易になり、時間を節約し、レビューとデプロイの時間を短縮できます。
  • 可能な限り遅れてエスケープすることで、コードがより堅牢で将来にわたって耐久性が向上します。
  • 出力時のエスケープ/キャストは、あいまいさを取り除き、明確さを加えます（常にメンテナのために開発します）。
  1. // Okay, but not great.
  2. $url = esc_url( $url );
  3. $text = esc_html( $text );
  4. echo '<a href="'. $url . '">' . $text . '</a>';
  6. // Much better!
  7. echo '<a href="'. esc_url( $url ) . '">' . esc_html( $text ) . '</a>';

… できない場合を除いて

遅れてエスケープするのが実用的でない場合もあります。いくつかの稀な状況では、出力をwp_kses()に渡すことができません。定義上、生成されるスクリプトが削除されるためです。

このような状況では、常に文字列を作成する際にエスケープし、_escaped、_safe、または_cleanで後置された変数に値を保存します（例：$variableは$variable_escapedまたは$variable_safeになります）。

関数が内部で出力できず、遅れてエスケープできない場合は、常に「安全な」HTMLを返す必要があります。これにより、echo my_custom_script_code();を行うことができ、スクリプトタグをwp_kses()のバージョンを通過させる必要がなくなります。

ローカリゼーションを伴うエスケープ

データを出力するためにechoを使用するのではなく、_e()や()などのWordPressローカリゼーション関数を使用するのが一般的です。

これらの関数は、単にローカリゼーション関数をエスケープ関数内にラップします： 

  1. esc_html_e( 'Hello World', 'text_domain' );
  2. // Same as
  3. echo esc_html( __( 'Hello World', 'text_domain' ) );

これらのヘルパー関数は、ローカリゼーションとエスケープを組み合わせます：

例

どこでも使用される任意の数値変数のエスケープ

  1. echo $int;

整数か浮動小数点数かに応じて、(int)、absint()、(float)はすべて正しいと受け入れられます。

時には、number_format()やnumber_format_i18n()の方が適切な場合もあります。 

  1.  <a name="escaping-arbitrary-variable-within-html-attribute"></a>
  3. ### HTML属性内の任意の変数のエスケープ
  5. ``````bash
  6. echo '<div id="', $prefix, '-box', $id, '">';
  7. `

これはesc_attr()への1回の呼び出しでエスケープされるべきです。

変数が属性やURLの一部として使用される場合、全体の文字列をエスケープする方が常に良いです。そうすることで、変数の直前にある潜在的なエスケープ文字が正しくエスケープされます。

正しい: 

  1. echo '<div id="', esc_attr( $prefix . '-box' . $id ), '">';

不正確: 

  1. echo '<div id="', esc_attr( $prefix ), '-box', esc_attr( $id ), '">';

注：wp_create_nonce()を使用して作成されたノンスも、HTML属性で使用される場合はこのようにエスケープする必要があります。

HTML属性内の任意のURLのエスケープ、他のコンテキストでも

  1. echo '<a href="', $url, '">';

これはesc_url()でエスケープされるべきです。

正しい: 

  1. echo '<a href="', esc_url( $url ), '">';

不正確: 

  1. echo '<a href="', esc_attr( $url ), '">';
  2. echo '<a href="', esc_attr( esc_url( $url ) ), '">';

wp_localize_script()を介してJavaScriptに任意の変数を渡す

  1. wp_localize_script( 'handle', 'name',
  2.     array(
  3.         'prefix_nonce' => wp_create_nonce( 'plugin-name' ),
  4.         'ajaxurl'      => admin_url( 'admin-ajax.php' ),
  5.         'errorMsg'     => __( 'An error occurred', 'plugin-name' ),
  6.     )
  7. );

エスケープは必要ありません。WordPressがこれをエスケープします。

JavaScriptブロック内の任意の変数のエスケープ

  1. <script type="text/javascript">
  2.    var myVar = <?php echo $my_var; ?>
  3. </script>
  2. **正しい:**  
  5. ``````bash
  6. <script type="text/javascript">
  7.    var myVar = <?php echo esc_js( $my_var ); ?>
  8. </script>
  9. `

インラインJavaScript内の任意の変数のエスケープ

  1. <a href="#" onclick="do_something(<?php echo $var; ?>); return false;">
  2. **正しい:**  
  5. ``````bash
  6. <a href="#" onclick="do_something(<?php echo esc_js( $var ); ?>); return false;">
  7. `

JavaScriptによる使用のためのHTML属性内の任意の変数のエスケープ

  1. <a href="#" data-json="<?php echo $var; ?>">
  2. **正しい:**  
  5. ``````bash
  6. <a href="#" data-json="<?php echo esc_js( $var ); ?>">
  7. `

HTMLテキストエリア内の任意の文字列のエスケープ

  1. echo '<textarea>', $data, '</textarea>';
  2. **正しい:**  
  5. ``````bash
  6. echo '<textarea>', esc_textarea( $data ), '</textarea>';
  7. `

HTMLタグ内の任意の文字列のエスケープ

  1. echo '<div>', $phrase, '</div>';

これは$phraseがHTMLを含むことが期待されるかどうかに依存します。

  • そうでない場合は、esc_html()またはそのバリアントのいずれかを使用します。
  • HTMLが期待される場合は、wp_kses_post()、wp_kses_allowed_html()、またはwp_kses()を使用し、許可したいHTMLタグのセットを指定します。

XMLまたはXSLコンテキスト内の任意の文字列のエスケープ

  1. echo '<loc>', $var, '</loc>';
  2. **正しい:**  
  5. ``````bash
  6. echo '<loc>', ent2ncr( $var ), '</loc>';
  7. `