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

Функция 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() для максимальной безопасности.