Проверка перенаправления администратора (CHECK_ADMIN_REFERER)

Функция check_admin_referer предназначена для проверки, что пользователь пришёл с другой страницы административной панели WordPress. Она также проверяет маркер безопасности, называемый nonce. Если проверка не прошла, исполнение PHP останавливается с сообщением об ошибке.

Заметка

Если маркер безопасности (nonce) действителен, проверка перенаправления не нужна. Ненадежность перенаправлений — одна из причин, почему используются маркеры (nonces). Они полностью заменяют необходимость проверки перенаправления. Проверка перенаправления применяется только в особых случаях, например, если пользователь не использует маркеры. В этом случае проверка осуществляется, чтобы обеспечить обратную совместимость. Сейчас такой случай встречается очень редко.

Функция check_admin_referer не совсем корректно названа, так как в большинстве случаев она не проводит проверку перенаправления. Её лучше было бы назвать check_nonce, но мы оставили это название для совместимости с более старыми версиями.

Похожая функция

Существует также аналогичная функция для AJAX-запросов: check_ajax_referer.

Платные фукнции

Функция check_admin_referer может быть переопределена (перезаписана) в плагинах. Это означает, что данная функция будет работать только после загрузки всех плагинов. Однако в ещё не загруженных плагинах её использовать нельзя. Поэтому вызов таких функций должен происходить только во время выполнения хука plugins_loaded или позже, например, в хуках init.

Замена функции

В вашем плагине вы можете создать функцию с тем же именем, и она заменит оригинальную.

Хуки функции

Функция check_admin_referer вызовет хуки, если проверка будет выполнена или не выполнена.

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

Функция возвращает одно из следующих значений:

• false — если код nonce неверен.
• 1 — если nonce действителен и был создан от 0 до 12 часов назад.
• 2 — если nonce действителен и был создан от 12 до 24 часов назад.

Использование

Синтаксис

check_admin_referer( $action, $query_arg );

• $action (int/string) — действие, которое нужно проверить (первый аргумент функции wp_nonce_field). По умолчанию: -1
• $query_arg (string) — ключ для проверки nonce в массиве $_REQUEST. По умолчанию: '_wpnonce'

Примеры

Пример 1: Базовое использование

При ошибке в запросе выполнение PHP будет остановлено.

Пример 2: Добавление и проверка nonce токена

Давайте добавим токен nonce в форму с помощью wp_nonce_field:

Теперь на странице, где обрабатывается запрос, проверяем токен nonce и перенаправление:

function my_handler_function(){
    check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' );

    // обработать запрос
}

Или используем условие if для лучшей читаемости:

if( check_admin_referer( 'name_of_my_action', 'name_of_nonce_field' ) ) {
   // обработать запрос
}

Изменения

• С 1.2.0 — Функция была введена.
• С 2.5.0 — Добавлен параметр $query_arg.

Код функции

function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
    if ( -1 === $action ) {
        _doing_it_wrong( __FUNCTION__, __( 'Укажите действие для проверки, используя первый параметр.' ), '3.2.0' );
    }

    $adminurl = strtolower( admin_url() );
    $referer  = strtolower( wp_get_referer() );
    $result   = isset( $_REQUEST[ $query_arg ] ) ? wp_verify_nonce( $_REQUEST[ $query_arg ], $action ) : false;

    do_action( 'check_admin_referer', $action, $result );

    if ( ! $result && ! ( -1 === $action && str_starts_with( $referer, $adminurl ) ) ) {
        wp_nonce_ays( $action );
        die();
    }

    return $result;
}

Эта функция проверяет, действителен ли код nonce и пришёл ли запрос с разрешённой страницы. Если что-то пойдёт не так, выполнение PHP остановится, и пользователь увидит сообщение об ошибке.

Теперь вы можете безопасно и эффективно использовать функцию check_admin_referer в ваших проектах на WordPress.