概要
esc_url_raw 関数は、WordPress において URL 文字列をデータベース向けにクリーニングする際に使用されます。この関数は、特にデータベースに格納する前に、無効な文字やスキームを除去するために利用されます。以下は、この関数がよく使われる場面の例です。
- ユーザーが投稿した URL を保存する際
- オプション値に URL を保存する際
- カスタムフィールドに URL を保存する際
- デフォルトの設定に URL を指定する際
- プラグインやテーマの設定で URL 入力を受け付ける際
- データベースから出力する前に安全な URL に変換する際
- REST API のリクエストで URL を処理する際
- URL が含まれるウィジェットやショートコードの出力時
構文
esc_url_raw( $url, $protocols );
パラメータ
$url(string) : クリーニングしたい URL。$protocols(array|bool) : 使用を許可するプロトコルの配列。指定しない場合は、デフォルトのプロトコルが使用される。
戻り値
- クリーニングされた URL の文字列が返されます。
関連する関数
使用可能なバージョン
esc_url_rawは、WordPress 1.5.0 以降で使用可能です。
コアファイルのパス
wp-includes/formatting.php
この関数のアクションでの使用可能性
| アクション | 使用例 |
|---|---|
| mu_plugin_loaded | |
| registered_post_type | |
| plugins_loaded | 〇 |
| wp_roles_init | |
| setup_theme | |
| after_setup_theme | |
| set_current_user | |
| init | 〇 |
| register_sidebar | |
| wp_loaded | 〇 |
| send_headers | |
| parse_query | |
| pre_get_posts | |
| wp | 〇 |
| template_redirect | |
| get_header | |
| wp_head | 〇 |
非推奨または削除されたバージョン
なし
サンプルコード
サンプルコード 1: 基本的な使用法
このコードは、ユーザーから取得した URL を安全な形式でクリーニングし、オプションに保存します。
$user_url = $_POST['user_url'];
$safe_url = esc_url_raw( $user_url );
update_option( 'my_custom_url', $safe_url );
（引用元：WordPress 開発者リファレンス）
サンプルコード 2: 設定フィールドでの使用
このサンプルコードは、設定ページに表示するために URL をクリーニングします。
function my_setting_callback() {
$url = esc_url_raw( get_option( 'my_custom_url' ) );
echo '<input type="text" name="my_custom_url" value="' . esc_attr( $url ) . '">';
}
（引用元：WordPress 開発者リファレンス）
サンプルコード 3: REST API のリクエスト処理
このコードは、REST API 経由で受信した URL をクリーニングします。
add_action( 'rest_api_init', function () {
register_rest_route( 'myplugin/v1', '/submit', array(
'methods' => 'POST',
'callback' => function( $request ) {
$url = esc_url_raw( $request['url'] );
// 処理を続行...
}
));
});
（引用元：WordPress 開発者リファレンス）
サンプルコード 4: URL チェック
このコードは、入力された URL が有効なものかどうか確認します。
$posted_url = $_POST['url'];
if ( $posted_url && filter_var( $posted_url, FILTER_VALIDATE_URL ) ) {
$clean_url = esc_url_raw( $posted_url );
// 処理を続ける...
}
（引用元：WordPress 開発者リファレンス）
サンプルコード 5: プラグインオプションの保存
プラグインオプションを管理する際に URL をクリーニングします。
function save_plugin_options() {
if ( isset( $_POST['my_plugin_url'] ) ) {
$url = esc_url_raw( $_POST['my_plugin_url'] );
update_option( 'my_plugin_url', $url );
}
}
add_action( 'admin_post_save_plugin_options', 'save_plugin_options' );
（引用元：WordPress 開発者リファレンス）