Функция esc_url() в WordPress с примерами

Функция 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=&#039value&#038
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-атаки, удаляя или изменяя опасные символы и фильтруя неподдерживаемые протоколы.