Функция check_admin_referer() используется для проверки безопасности запросов в административной панели WordPress. Она проверяет nonce-код, который защищает от CSRF-атак (подделка межсайтовых запросов) и гарантирует, что запрос был выполнен с правильной страницы.
check_admin_referer( int|string $action = -1, string $query_arg = '_wpnonce' ): int|false
Параметры
- $action (int|string) (опциональный):
Идентификатор действия для nonce-кода. Это тот же идентификатор, который использовался при создании nonce с помощью функцииwp_nonce_field().
По умолчанию:-1. - $query_arg (string) (опциональный):
Ключ для поиска nonce-кода в массиве$_REQUEST. По умолчанию:'_wpnonce'.
Возвращаемое значение
- int|false:
Возвращает1, если nonce-код действителен и был создан менее 12 часов назад.
Возвращает2, если nonce-код действителен и был создан от 12 до 24 часов назад.
Возвращаетfalse, если nonce-код не прошел проверку.
Описание
Функция check_admin_referer() помогает защитить админку WordPress от CSRF-атак, проверяя переданный nonce-код. Если проверка не удалась, скрипт прерывается с сообщением «Are you sure you want to do this?».
Эта функция гарантирует, что запрос был выполнен с админ-страницы WordPress и содержит правильный nonce-код. Однако она не проверяет права пользователя — для этого необходимо использовать функции вроде current_user_can().
Особенности
- Pluggable функция: функция может быть заменена в плагинах.
- Обратная совместимость: Если параметр
$actionне указан, то проверяетсяrefererзапроса. Однако использование nonce-кода предпочтительнее и безопаснее. - Предупреждения: Если не указан
$action, начиная с версии 3.2, при включенномWP_DEBUG, функция завершится с сообщением о необходимости указать nonce-идентификатор.
Пример 1: Добавление и проверка nonce-кода в форме
Пример того, как использовать check_admin_referer() для защиты формы от CSRF-атак.
Шаг 1: Добавляем nonce в форму
Для защиты данных формы создаем nonce-код с помощью wp_nonce_field().
<form method="post">
<!-- Поля формы -->
<?php wp_nonce_field( 'my_custom_action', 'my_nonce_field' ); ?>
</form>
Здесь создается nonce-код с идентификатором действия my_custom_action и названием поля my_nonce_field.
Шаг 2: Проверка nonce при обработке формы
После отправки формы проверяем nonce-код с помощью check_admin_referer():
if ( ! empty( $_POST ) && check_admin_referer( 'my_custom_action', 'my_nonce_field' ) ) {
// Если проверка успешна, обрабатываем данные формы
// Например, обновляем опции
update_option( 'my_option', sanitize_text_field( $_POST['my_field'] ) );
}
Если nonce-код недействителен, функция автоматически выведет сообщение об ошибке и прекратит выполнение скрипта.
Пример 2: Использование функции без указания второго параметра
В этом примере функция check_admin_referer() будет искать nonce-код в стандартном параметре '_wpnonce'.
check_admin_referer( 'my_action' );
В данном случае nonce-код должен быть создан так:
wp_nonce_field( 'my_action' );
Пример 3: Прерывание выполнения при неверном nonce
Если вы хотите вывести собственное сообщение об ошибке при неудачной проверке nonce, можно использовать if условие:
if ( ! check_admin_referer( 'my_action', 'my_nonce_field', false ) ) {
wp_die( 'Invalid nonce. Please try again.' );
}
// Если проверка прошла, продолжаем выполнение
echo 'Nonce is valid!';
Пример 4: Использование в плагине
Пример использования функции в плагине для проверки nonce-кода при обработке настроек:
add_action( 'admin_post_my_plugin_options', 'my_plugin_options_handler' );
function my_plugin_options_handler() {
// Проверяем nonce
if ( check_admin_referer( 'my_plugin_action', 'my_plugin_nonce' ) ) {
// Если nonce прошел проверку, обновляем опции
update_option( 'my_plugin_option', sanitize_text_field( $_POST['my_option_field'] ) );
} else {
// Не удалось пройти проверку nonce
wp_die( 'Invalid nonce specified', 'Nonce Error', array( 'response' => 403 ) );
}
}
Заключение
Функция check_admin_referer() — это важный инструмент для защиты данных в админке WordPress. Она проверяет nonce-код, чтобы убедиться, что запрос был выполнен с правильной страницы и предназначен для выполнения определенного действия. В сочетании с проверкой прав пользователя через current_user_can(), эта функция помогает обеспечить безопасность вашего сайта.