esc_url() – проверяет и очищает URL

Функция заботится о безопасном выводе URL на экран, как в виде текста, так и качестве HTML атрибутов, например <img src="">, <a href=""> и т.д. Никогда не выводите неочищенный URL в своём коде (узнайте, почему).

Что конкретно делает функция:

• Удаляет пробелы на концах.
• Заменяет пробелы внутри на символы %20.
• Для всех протоколов кроме mailto удалит символы %0d,%0a,%0D, %0A (подробнее, что это за символы).
• Заменит ;// на ://.
• Если URL не содержит протокола, но при этом не является относительной ссылкой /wordpress/esc_url.html, URL-параметрами ?myparam=yes, якорем #primer или php-файлом esc_url.php, то автоматически будет добавлен протокол http://.
• Экранирует HTML-сущности, т.е. например ' превратится в '.
• Заменит символы амперсанда и одинарной кавычки в числовые сущности & и ' соответственно.
• Если указанный в URL протокол не поддерживается, то возвратит пустую строку.
• Применит фильтр clean_url в самом конце.

esc_url( $url, $protocols = null, $_context = 'display' )

Параметры

$url

(строка) Текст, который предположительно является урлом, который мы и должны очистить.

$protocols

(массив) Массив из поддерживаемых протоколов в урле (http,ftp и так далее). Если в переданном URL используется протокол, который не указан в этом массиве, то функция возвращает пустую строку. По умолчанию – значение функции wp_allowed_protocols(), которая возвращает массив:

Array
(
    [0] => http
    [1] => https
    [2] => ftp
    [3] => ftps
    [4] => mailto
    [5] => news
    [6] => irc
    [7] => irc6
    [8] => ircs
    [9] => gopher
    [10] => nntp
    [11] => feed
    [12] => telnet
    [13] => mms
    [14] => rtsp
    [15] => sms
    [16] => svn
    [17] => tel
    [18] => fax
    [19] => xmpp
    [20] => webcal
    [21] => urn
)

$_context

(строка) В каком контексте планируется использовать URL. Рекомендуется не указывать этот параметр в вашем коде. Вы можете спокойно использовать функцию esc_url() со стандартным значением этого параметра, если планируете выводить урл в качестве HTML-атрибутов, например href и src или же прямо на странице. Однако, если вы хотите использовать URL для редиректов, HTTP-запросов или запросов к БД, тогда обратитесь к функции esc_url_raw().

Примеры

1. Как использовать

Когда мы передаём в URL какие-либо параметры, то там в принципе могут присутствовать и пробелы, хотя в самом URL их быть не должно. Функция esc_url() помогает с ними разобраться.

$url = 'https://misha.agency/?s=валидация и очистка';
 
echo '<a href="' . esc_url( $url ) . '">Искать на сайте</a>';
// получим
// https://misha.agency/?s=валидация%20и%20очистка

Ещё кстати неоднократно встречал такой пример: esc_url( home_url( '/' ) );, и хотя мы должны помнить, что никому не доверяем, но насколько всё должно быть печально, если в адресе сайта в настройках прописалась какая-то дичь.

2. Работа с протоколами

Тут я вспомнил про Skype почему-то. Там раньше были ссылки, типо позвонить кому-то или добавить в контакты, например <a href="skype:misha?call">позвонить</a>. Для того, чтобы функция esc_url() не превращала такие ссылки в пустую строку, мы должны будем указать поддерживаемый протокол во втором параметре функции.

$url = 'skype:misha?call';
echo '<a href="' . esc_url( $url, array( 'skype' ) ) . '">позвонить</a>';

Хуки

clean_url

Перед непосредственно возвращением уже очищенного URL, функция применяет к нему фильтр clean_url, который позволяет нам, разработчикам плагинов и тем, добавить ещё и какие-либо собственные правила очистки либо переписать функцию вовсе!

return apply_filters( 'clean_url', $good_protocol_url, $original_url, $_context );

$good_protocol_url

(строка) Уже очищенный URL.

$original_url

(строка) URL до очистки.

$_context

(строка) Принимает значение display по умолчанию, либо db, если фильтр был вызван внутри функции esc_url_raw().

add_filter( 'clean_url', 'true_clean_url', 25, 3 );
 
function true_clean_url( $good_protocol_url, $original_url, $_context ) {
 
	// делаем какие-либо изменения либо полностью кастомизируем очистку
	// записываем результат в $url и возвращаем его
	return $url;
}

Не знаете, как работать с фильтрами? Смотрите этот урок.