Функция esc_url() используется для очистки и экранирования URL перед их выводом на экран, чтобы предотвратить атаки XSS и другие уязвимости безопасности. Она удаляет или изменяет потенциально опасные символы в URL и проверяет, что ссылка начинается с допустимого протокола. Применяется для всех контекстов, где URL выводится в HTML-коде (например, в ссылках, изображениях, формах и т.д.).
esc_url( string $url, string[] $protocols = null, string $_context = 'display' ): stringПараметры
$url(string, обязательный): URL, который необходимо очистить.$protocols(array, необязательный): Массив допустимых протоколов. По умолчанию используется список, возвращаемый функциейwp_allowed_protocols().$_context(string, необязательный): Контекст использования URL. Значение по умолчанию —'display', что заменяет амперсанд (&) и кавычки (‘) на HTML-сущности.
Возвращаемое значение
string: Очищенный URL, готовый к безопасному выводу на экран. Если протокол не входит в список разрешенных, функция вернет пустую строку.
Пример 1: Очистка URL
Этот пример демонстрирует очистку URL с небезопасными символами.
$url = "http://example.com/link?var='value&";
echo esc_url( $url );
// Результат: http://example.com/link?var='value&
В этом случае одинарные кавычки и амперсанд были заменены на соответствующие HTML-сущности.
Пример 2: Относительный и некорректный URL
esc_url() корректно обрабатывает относительные URL и удаляет потенциально опасные данные, как в следующем примере:
echo esc_url( '#some' ); // Результат: #some
$url = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABIAAAD///////neHiwAAAAF3RST/+8RwZ==';
echo esc_url( $url ); // Результат: ''Во втором случае, поскольку протокол data: не разрешен, функция вернула пустую строку.
Пример 3: Относительный и абсолютный URL
Функция также корректно обрабатывает относительные ссылки.
echo esc_url( '/foo' ); // Результат: /foo
echo esc_url( 'foo' ); // Результат: http://foo
Пример 4: Использование в HTML-атрибутах
Экранирование URL в атрибутах HTML-тегов, таких как href или src, помогает защититься от XSS-атак:
// Пример ссылки на домашнюю страницу
<a href="<?php echo esc_url( home_url( '/' ) ); ?>">Home</a>
// Пример использования в изображении
<img src="<?php echo esc_url( $image_url ); ?>" alt="Описание изображения" />
// Пример использования в форме
<form action="<?php echo esc_url( $form_submit_url ); ?>">
Настройка списка разрешенных протоколов
Список разрешенных протоколов может быть расширен с помощью фильтра kses_allowed_protocols:
function my_extend_allowed_protocols( $protocols ) {
$protocols[] = 'skype';
$protocols[] = 'spotify';
return $protocols;
}
add_filter( 'kses_allowed_protocols', 'my_extend_allowed_protocols' );
В этом примере добавлены дополнительные протоколы: skype и spotify.
Сравнение с urlencode()
Функция esc_url() не кодирует URL таким же образом, как urlencode(). Она заботится о безопасности URL и экранировании опасных символов.
$url = "http://example.com/моя ссылка?var='some&";
echo esc_url( $url ); // Результат: http://example.com/моя%20ссылка?var='value&
echo urlencode( $url ); // Результат: http%3A%2F%2Fexample.com%2F%D0%BC%D0%BE%D1%8F+%D1%81%D1%81%D1%8B%D0%BB%D0%BA%D0%B0%3Fvar%3D%27value%26
Заключение
Функция esc_url() — это незаменимый инструмент для безопасного вывода URL на экран. Она предотвращает XSS-атаки, удаляя или изменяя опасные символы и фильтруя неподдерживаемые протоколы.