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

Функция sanitize_url() используется для очистки и фильтрации URL-адресов перед их использованием, например, для редиректов или хранения в базе данных. Она защищает от некорректных и потенциально опасных данных в URL, а также позволяет указать список допустимых протоколов.

sanitize_url( string $url, string[] $protocols = null ): string

Параметры

• $url (string) (обязательный):
  URL, который нужно очистить. Это может быть URL, введенный пользователем, полученный из запроса или из других источников.
• $protocols (string[]) (опциональный):
  Массив протоколов, которые считаются допустимыми (например, http, https, ftp). По умолчанию используется возвращаемое значение функции wp_allowed_protocols(), которое включает такие протоколы как http, https, ftp, и другие.

Возвращаемое значение

• string: Очищенный URL, который прошел обработку через функцию esc_url() с контекстом db (для безопасного использования в базе данных).

Описание

Функция sanitize_url() проверяет и очищает URL, удаляя небезопасные или некорректные элементы. Внутри она использует функцию esc_url(), которая также удаляет потенциально опасные символы и проверяет корректность протоколов. Эта функция полезна при работе с пользовательскими вводами, при редиректах или сохранении URL в базе данных.

Важные моменты:

• Если URL не содержит допустимого протокола, функция вернет пустую строку.
• Функция может фильтровать URL по заданным протоколам. Если передать только http и https, все остальные протоколы будут отклонены.

Пример 1: Очистка URL перед использованием в заголовке

Этот пример иллюстрирует очистку URL перед добавлением в заголовок HTTP-запроса:

// Получаем URL REST API
$url = get_rest_url();

// Используем sanitize_url() для очистки URL перед вставкой в заголовок
header( sprintf( 'Link: <%s>; rel="https://api.w.org/"', sanitize_url( $url ) ), false );

Пример 2: Фильтрация только по протоколам http и https

Функция sanitize_url() позволяет ограничивать URL только разрешенными протоколами:

// Ссылка на ftp-ресурс
$url = 'ftp://ftp.example.com/pub/file.zip';
$new_url = sanitize_url( $url, array( 'http', 'https' ) );
// Вернёт пустую строку, так как протокол ftp не разрешён

// Обычная ссылка на HTTPS сайт
$url = 'https://example.com/projects/';
$new_url = sanitize_url( $url, array( 'http', 'https' ) );
// Вернёт: 'https://example.com/projects/'

Пример 3: Очистка пользовательского URL перед сохранением в базе данных

Если пользователь ввел URL, его можно очистить перед сохранением:

$user = new stdClass();

if ( isset( $_POST['url'] ) ) {
    // Очистка введенного URL
    $user->user_url = sanitize_url( $_POST['url'] );
}

// Сохраняем данные пользователя
$user_id = wp_insert_user( $user );

Пример 4: Очистка различных URL

var_dump( sanitize_url( 'https://example.com/foo' ) ); // 'https://example.com/foo'
var_dump( sanitize_url( 'https://example.com/foo-%2F-M' ) ); // 'https://example.com/foo-%2F-M'
var_dump( sanitize_url( '/foo' ) ); // '/foo'
var_dump( sanitize_url( '' ) ); // string(0) ""
var_dump( sanitize_url( false ) ); // string(0) ""
var_dump( sanitize_url( null ) ); // string(0) ""
var_dump( sanitize_url( true ) ); // 'http://1'

Важные функции, связанные с sanitize_url()

• esc_url(): Основная функция, которая очищает URL для безопасного использования.
• wp_allowed_protocols(): Возвращает массив разрешённых протоколов, используемый по умолчанию для проверки URL.

Заключение

Функция sanitize_url() обеспечивает безопасное использование URL-адресов в WordPress. Она может быть полезна для очистки данных, введенных пользователями, и защиты от потенциальных уязвимостей. Возможность указать конкретные протоколы для фильтрации делает её ещё более гибкой в работе с различными типами URL.