Функция check_ajax_referer() используется для проверки безопасности AJAX-запросов в WordPress. Она проверяет переданный nonce-код (одноразовый уникальный токен) и предотвращает выполнение запросов, которые не прошли проверку.
check_ajax_referer( int|string $action = -1, false|string $query_arg = false, bool $stop = true ): int|falseПараметры
- $action (int|string) (опциональный):
Действие, с которым связан nonce-код. Это тот же идентификатор, который использовался при создании nonce с помощью функцииwp_create_nonce(). По умолчанию-1. - $query_arg (false|string) (опциональный):
Ключ для поиска nonce-кода в массиве$_REQUEST. Если не указано, будут проверены ключи_ajax_nonceи_wpnonce. По умолчаниюfalse. - $stop (bool) (опциональный):
Если установлено вtrue(по умолчанию), функция прекратит выполнение скрипта и вернет ответ-1, если проверка nonce не пройдена. Еслиfalse, функция просто вернетfalseв случае неудачной проверки.
Возвращаемое значение
- int|false:
Возвращает1, если nonce-код действителен и был создан менее 12 часов назад.
Возвращает2, если nonce-код действителен и был создан от 12 до 24 часов назад.
Возвращаетfalse, если nonce-код не прошел проверку.
Описание
Функция check_ajax_referer() помогает защитить ваши AJAX-запросы, проверяя переданный nonce-код. Это предотвращает внешние или поддельные запросы к вашему сайту. Если проверка не пройдена и параметр $stop установлен в true, выполнение скрипта завершится, и запрос получит ответ с кодом ошибки 403 (доступ запрещен).
Важно помнить, что nonce-коды не предназначены для полной аутентификации или управления доступом. Они служат для защиты от CSRF-атак (межсайтовой подделки запроса), но должны использоваться в паре с другими методами проверки прав пользователя, например, с функцией current_user_can().
Пример 1: Создание и проверка nonce-кода в AJAX-запросе
В основном PHP-файле создаем nonce и передаем его в JavaScript:
<?php
// Создаем nonce для использования в AJAX-запросе
$ajax_nonce = wp_create_nonce( "my-special-string" );
?>
<script type="text/javascript">
jQuery(document).ready(function($) {
var data = {
action: 'my_action',
security: '<?php echo $ajax_nonce; ?>', // Передаем nonce-код в запрос
my_string: 'Hello World!'
};
$.post(ajaxurl, data, function(response) {
alert("Response: " + response);
});
});
</script>
Этот код создает nonce с помощью функции wp_create_nonce() и передает его через переменную security в AJAX-запрос.
Затем проверяем этот nonce при обработке AJAX-запроса:
add_action( 'wp_ajax_my_action', 'my_action_function' );
function my_action_function() {
// Проверяем nonce-код, переданный через параметр security
check_ajax_referer( 'my-special-string', 'security' );
// Если проверка прошла, выводим данные
echo sanitize_text_field( $_POST['my_string'] );
die;
}
Функция check_ajax_referer() проверяет nonce-код с идентификатором my-special-string, который был передан в security. Если проверка успешна, запрос будет выполнен.
Пример 2: Использование стандартных имен для nonce
Если в запросе не указан параметр $query_arg, check_ajax_referer() будет искать nonce-код в полях _ajax_nonce и _wpnonce:
add_action( 'wp_ajax_my_action', 'my_action_function' );
function my_action_function() {
// Проверяем nonce-код, используя стандартные ключи _ajax_nonce или _wpnonce
check_ajax_referer( 'my-special-string' );
// Если проверка прошла, продолжаем обработку
echo sanitize_text_field( $_POST['my_string'] );
die;
}
Пример 3: Отключение автоматического завершения скрипта при ошибке
Если вам нужно продолжить выполнение скрипта, даже если nonce-код не прошел проверку, можно передать третий параметр $stop как false:
add_action( 'wp_ajax_my_action', 'my_action_function' );
function my_action_function() {
// Проверяем nonce-код, но не прерываем выполнение скрипта при ошибке
if ( ! check_ajax_referer( 'my-special-string', 'security', false ) ) {
wp_send_json_error( array( 'message' => 'Nonce verification failed' ) );
} else {
wp_send_json_success( array( 'message' => 'Nonce verified successfully' ) );
}
die;
}
В этом случае, если проверка не удастся, функция не завершит выполнение, а вернет ошибку через wp_send_json_error().
Заключение
Функция check_ajax_referer() — это мощный инструмент для защиты AJAX-запросов от поддельных запросов и CSRF-атак. Она должна использоваться вместе с проверкой прав пользователя через current_user_can() для максимальной безопасности.