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

Функция wp_nonce_url() добавляет параметр nonce в URL, который используется для защиты от подделки межсайтовых запросов (CSRF). Nonce (от «number used once») — это уникальный ключ, который WordPress использует для защиты операций в формах и ссылках. Важно использовать wp_nonce_url() для создания безопасных URL, выполняющих важные действия в административной панели или на пользовательских страницах.

wp_nonce_url( string $actionurl, int|string $action = -1, string $name = '_wpnonce' ): string

Параметры:

• $actionurl (string, обязательный): URL, к которому необходимо добавить параметр nonce.
• $action(int|string, необязательный): Контекст или название действия, для которого создается nonce. Должен быть уникальным для каждого действия.
  • По умолчанию: -1.
• $name(string, необязательный): Имя параметра, под которым будет добавлен nonce.
  • По умолчанию: '_wpnonce'.

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

• Возвращает: Строку с URL, содержащим параметр nonce. URL безопасен для вывода на экран, так как экранируется через esc_html().

Особенности:

• Функция добавляет параметр &_wpnonce=<значение> в конец переданного URL.
• Работает на основе функции wp_create_nonce().
• Не подходит для использования в wp_redirect() из-за экранирования символов, например, & заменяется на &. В таких случаях лучше использовать add_query_arg() для ручного добавления nonce в URL.

Пример 1: Добавление nonce в URL

Простой пример добавления nonce в URL:

echo wp_nonce_url( 'http://example.com/action' );
// Результат: http://example.com/action?_wpnonce=1nf8428532

Добавление nonce в URL с параметрами:

echo wp_nonce_url( 'http://example.com/action?arg=data' );
// Результат: http://example.com/action?arg=data&_wpnonce=7d6bd294a7

Пример 2: Проверка ссылки с nonce

Создаем URL с nonce для действия, а затем проверяем его при получении данных:

// Генерация URL с nonce
$url = wp_nonce_url( 'http://example.com/action', 'my_action' );
echo $url;
// Результат: http://example.com/action?_wpnonce=4a115t9c33

// Проверка nonce после перехода по ссылке
if ( wp_verify_nonce( $_GET['_wpnonce'], 'my_action' ) ) {
    echo "Проверка nonce пройдена.";
} else {
    echo "Проверка nonce не пройдена.";
}

Пример 3: Добавление nonce в URL для редиректа

Так как wp_nonce_url() предназначен для вывода на экран, для редиректов следует использовать add_query_arg() с добавлением nonce вручную:

$url = '/wp-admin/admin.php?page=foo';
$nonce = wp_create_nonce( 'my_nonce_key' ); // Создаем nonce

// Добавляем nonce в URL
$nonce_url = add_query_arg( array( '_wpnonce' => $nonce ), $url );

echo $nonce_url;
// Результат: /wp-admin/admin.php?page=foo&_wpnonce=45c55a132a

Пример 4: Использование в плагинах (кнопка действия)

Этот пример показывает, как можно добавить ссылку с nonce в административную панель плагина. Пользователь нажимает на кнопку, и проверяется nonce перед выполнением действий.

<?php
function my_plugin_do_something() {
?>
<h2><?php esc_html_e( 'My Plugin Admin Screen', 'my-plugin-textdomain' ); ?></h2>
<p>
    <a href="<?php print wp_nonce_url( admin_url( 'options.php?page=my_plugin_settings' ), 'doing_something', 'my_nonce' ); ?>"
       class="button button-primary"><?php esc_html_e( 'Do Something!', 'my-plugin-textdomain' ); ?></a>
    <span class="description"><?php esc_html_e( 'This button does something interesting.', 'my-plugin-textdomain' ); ?></span>
</p>
<?php
}

// Добавляем страницу настроек плагина
add_action( 'admin_menu', 'add_my_plugin_admin_screen' );
function add_my_plugin_admin_screen() {
    add_options_page(
        __( 'My Plugin Settings', 'my-plugin-textdomain' ),
        __( 'My Plugin', 'my-plugin-textdomain' ),
        'manage_options',
        'my_plugin_settings',
        'my_plugin_do_something'
    );
}

// Обработка действий при нажатии кнопки
function my_plugin_do_something() {
    if ( ! isset( $_GET['my_nonce'] ) || ! wp_verify_nonce( $_GET['my_nonce'], 'doing_something' ) ) {
?>
<h2><?php esc_html_e( 'My Plugin Admin Screen', 'my-plugin-textdomain' ); ?></h2>
<p>
    <a href="<?php print wp_nonce_url( admin_url( 'options.php?page=my_plugin_settings' ), 'doing_something', 'my_nonce' ); ?>"
       class="button button-primary"><?php esc_html_e( 'Do Something!', 'my-plugin-textdomain' ); ?></a>
    <span class="description"><?php esc_html_e( 'This button does something interesting.', 'my-plugin-textdomain' ); ?></span>
</p>
<?php
    } else {
        // Пользователь нажал кнопку, выполняем действие
        // Здесь реализуем что-то интересное
    }
}

Заключение:

Функция wp_nonce_url() используется для защиты действий, выполняемых через ссылки, от подделки запросов (CSRF). Это особенно важно для разработчиков плагинов и тем, так как гарантирует, что критические действия (например, удаление данных) будут выполняться только с разрешения инициализированного действия.