Функция esc_url_raw() в WordPress используется для безопасного очищения URL перед его использованием в базах данных, редиректах или HTTP-запросах. Она является версией esc_url(), которая не заменяет символы для отображения, и поэтому идеально подходит для использования в запросах, но не в выводе на экран.
esc_url_raw( string $url, string[] $protocols = null ): string
Эта функция принимает строку — URL-адрес — и возвращает очищенный URL. При этом удаляются недопустимые символы и проверяется протокол, чтобы URL был безопасным для последующего использования.
Параметры
$url(строка, обязательный): URL-адрес, который нужно очистить.$protocols(массив строк, необязательный): Список допустимых протоколов. По умолчанию включаетhttp,https,ftp,mailtoи другие, но его можно изменить, передав массив с нужными значениями.
Возвращаемое значение
- Возвращает очищенный URL-адрес. Если URL содержит недопустимый протокол, функция возвращает пустую строку.
Особенности функции
Функция esc_url_raw() используется для очистки URL в сценариях, где не требуется отображение ссылки. Она выполняет очистку URL, но в отличие от esc_url() не преобразует специальные символы, что делает её небезопасной для использования в HTML. В таких случаях рекомендуется использовать esc_url().
Очистка URL перед запросом к удаленному серверу
<?php
$url = 'http://example.com/api/data?param=<script>alert("test")</script>';
$sanitized_url = esc_url_raw($url);
$response = wp_remote_get($sanitized_url);
if (!is_wp_error($response)) {
echo wp_remote_retrieve_body($response);
}
?>
В этом примере esc_url_raw() удаляет опасные теги из параметра param, делая URL безопасным для запроса к API.
Использование с набором допустимых протоколов
<?php
$url = 'ftp://example.com/file.zip';
$sanitized_url = esc_url_raw($url, ['ftp', 'http', 'https']);
echo $sanitized_url; // Результат: ftp://example.com/file.zip
?>
Здесь функция проверяет, что ftp является допустимым протоколом, и очищает URL. Если бы протокол был недопустимым, функция вернула бы пустую строку.
Удаление недопустимых символов и параметров
<?php
$url = 'https://example.com?param=<>&another=value';
echo esc_url_raw($url); // Результат: https://example.com?param=&another=value
?>
Функция удаляет символы < и > из параметра, делая URL безопасным для использования в запросах.
Неправильное использование esc_url_raw() в HTML-коде
<!-- Неправильное использование: не используйте esc_url_raw() для вывода в HTML -->
<img src="<?php echo esc_url_raw($url); ?>" />
<a href="<?php echo esc_url_raw($url); ?>">Перейти</a>
Для вывода в HTML-коде вместо esc_url_raw() следует использовать esc_url(), которая защищает URL от XSS-атак, преобразуя специальные символы.
Корректное использование при построении динамических ссылок
<?php
$url = 'https://mywebsite.com/download?file=myfile.zip';
$clean_url = esc_url_raw($url);
// Пример правильного использования
$response = wp_remote_get($clean_url);
if (!is_wp_error($response)) {
$body = wp_remote_retrieve_body($response);
// Обработка данных из запроса
}
?>
esc_url_raw() используется здесь для очистки ссылки перед запросом, обеспечивая безопасность URL при работе с данными из внешних источников.
Заключение
Функция esc_url_raw() оптимально подходит для очистки URL перед их сохранением в базе данных, в запросах к API или редиректах.