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

Функция 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(), эта функция помогает обеспечить безопасность вашего сайта.