Функция check_ajax_referer() в WordPress: описание, примеры, изменения

# Функция check_ajax_referer() в WordPress

## Общее описание

Функция check_ajax_referer() проверяет «nonce» — специальный токен безопасности для AJAX-запросов в WordPress. Если проверка не проходит, функция завершает выполнение и останавливает работу PHP.

По умолчанию функция ищет токен в двух местах:  
- $_REQUEST['_ajax_nonce']   
- $_REQUEST['_wpnonce']  

> **Примечание:** «Nonce» — это строка, которая используется для проверки подлинности пользователя и предотвращения подделки запросов.

## Плагины и переопределение функции

Эта функция является «плагино-заменяемой», что означает, что вы можете создать свою версию функции в своем плагине. Однако её нельзя вызывать до того, как все плагины загрузятся. Для этого используйте хук plugins_loaded или более поздние хуки, такие как init.

### Как переопределить функцию

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

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

Функция возвращает:
- 1 — если токен действительный и был сгенерирован от 0 до 12 часов назад
- 2 — если токен действительный и был сгенерирован от 12 до 24 часов назад
- false — если токен недействительный

## Пример использования

Функция check_ajax_referer() используется следующим образом:

```php
check_ajax_referer( $action, $query_arg, $die );

Параметры функции:

• $action (int/string) — действие для проверки. Его указывают при создании nonce, например, wp_create_nonce("my_action").

  • По умолчанию: -1

• $query_arg (false/string) — ключ для проверки токена в $_REQUEST. Если не указано, функция проверит сначала на _ajax_nonce, затем на _wpnonce.

  • По умолчанию: false

• $die (true/false) — нужно ли завершать выполнение скрипта, если проверка токена не удалась.

  • true — выполнение завершится с сообщением об ошибке.
  • false — выполнение продолжится, и функция вернет false или один из целых чисел в зависимости от результата.
  • По умолчанию: true

Пример создания и проверки токена в AJAX-запросе

Вот как создать nonce и использовать его в AJAX-запросе:

// Создание Nonce
$ajax_nonce = wp_create_nonce("my-special-string");

JavaScript часть:

Совет: Лучше всего использовать wp_localize_script() для передачи токена в JavaScript, а JS-код держать в отдельном файле.

Проверка токена на сервере:

add_action( 'wp_ajax_my_action', 'my_action_function' );

function my_action_function() {
    check_ajax_referer( 'my-special-string', 'security' );
    echo $_POST['my_string'];
    wp_die(); // Завершает выполнение
}

В этом примере мы создали токен с действием my-special-string и проверили его при обработке AJAX-запроса.

Можно использовать _wpnonce или _ajax_nonce вместо security в JavaScript, так токен будет автоматически подхвачен функцией check_ajax_referer().

Изменения в функции

Функция check_ajax_referer() была представлена в версии 2.0.3 WordPress и обновлена в версии 6.7.2.

Фундаментальный код функции

function check_ajax_referer( $action = -1, $query_arg = false, $stop = true ) {
    if ( -1 === $action ) {
        _doing_it_wrong( __FUNCTION__, __( 'Вы должны указать действие для проверки, используя первый параметр.' ), '4.7.0' );
    }

    $nonce = '';

    if ( $query_arg && isset( $_REQUEST[ $query_arg ] ) ) {
        $nonce = $_REQUEST[ $query_arg ];
    } elseif ( isset( $_REQUEST['_ajax_nonce'] ) ) {
        $nonce = $_REQUEST['_ajax_nonce'];
    } elseif ( isset( $_REQUEST['_wpnonce'] ) ) {
        $nonce = $_REQUEST['_wpnonce'];
    }

    $result = wp_verify_nonce( $nonce, $action );

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

    if ( $stop && false === $result ) {
        if ( wp_doing_ajax() ) {
            wp_die( -1, 403 );
        } else {
            die( '-1' );
        }
    }

    return $result;
}

Заключение

Функция check_ajax_referer() является важным инструментом для обеспечения безопасности AJAX-запросов в WordPress. Правильное использование этой функции помогает защитить ваш сайт от мошеннических действий и атак. Обязательно следите за корректностью токенов и всегда используйте их при обработке данных из AJAX-запросов.