WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

check_admin_referer() WP 1.2.1

Проверяет, отправлен ли текущий запрос со страницы админки и правильный ли указан nonce код. В случае ошибки обрывает работу скрипта (die).

Если проверка не будет пройдена, функция прерывает работу PHP скрипта (die) и выводит сообщение: "Are you sure you want to do this?" со ссылкой на предыдущую страницу. Читайте описание функции: wp_nonce_ays().

Заметка по этой функции: Если nonce правильный, то нет необходимости проверять реферер. Nonce коды используются во многом потому что нельзя доверять параметру referrer. Так можно сказать, что nonce полностью заменяет проверку реферера. Функция проверяет реферер только когда не указан параметр $action (не указан nonce для проверки). В настоящее время, проверка реферера очень редко встречается.

Из вышесказанного, у функции получилось неудачное название, потому что она почти никогда не проверяет реферер. Было бы лучше назвать её как-то вроде check_nonce(), но сделать это не позволяет обратная совместимость со старыми версиями тем и плагинов.

Есть еще аналогичная функция, для проверки AJAX запроса: check_ajax_referer()

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

Замена функции (переопределение) — в плагине можно создать функцию с таким же названием, тогда она заменит текущую функцию.

Хуки из функции
Возвращает

false/Int.

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

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

<?php check_admin_referer( $action, $query_arg ); ?>
$action(строка)
Идентификатор nonce проверки (первый аргумент функции wp_nonce_field).
По умолчанию: -1
$query_arg(строка)
Название параметра запроса, содержащего значение nonce, т.е. где искать проверочный код.
По умолчанию: '_wpnonce'

Примеры

#1. Базовый пример использования

<?php check_admin_referer( 'bcn_admin_options' ); ?>

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

#2. Добавление и проверка проверочного кода

Пример того, как использовать эту функцию при написании плагина. Добавляем проверочный код функцией wp_nonce_field()

<form method="post">
   <!-- данные формы ... -->
   <?php wp_nonce_field( 'name_of_my_action','name_of_nonce_field' ); ?>
</form>

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

function my_handler_function(){

	// Убедимся что запрос не просрочен
	// При ошибке, выведет сообщение и прервет работу PHP.
	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 The $query_arg parameter was added.

Код check_admin_referer() WP 5.5.1

wp-includes/pluggable.php
<?php
function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
	if ( -1 === $action ) {
		_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce action to be verified by using the first parameter.' ), '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;

	/**
	 * Fires once the admin request has been validated or not.
	 *
	 * @since 1.5.1
	 *
	 * @param string    $action The nonce action.
	 * @param false|int $result False if the nonce is invalid, 1 if the nonce is valid and generated between
	 *                          0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
	 */
	do_action( 'check_admin_referer', $action, $result );

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

	return $result;
}

Cвязанные функции

Из метки: nonce (защита)

Еще из раздела: Защита

3 коммента