check_admin_referer în WordPress

check_admin_referer( int|string $action = -1, string $query_arg = '_wpnonce' ): int|false

Ce face check_admin_referer

check_admin_referer() (din WordPress 1.2.0; argumentul $query_arg din 2.5.0) citește nonce-ul din $_REQUEST[ $query_arg ] (implicit _wpnonce) și îl verifică pentru acțiunea dată. Dacă e valid întoarce 1 (0-12 ore) sau 2 (12-24 de ore). Dacă e invalid sau lipsește, apelează wp_nonce_ays(), care afișează o pagină de eroare cu cod 403 și oprește scriptul.

Pe un site în engleză, pagina de eroare spune The link you followed has expired. și, dacă există un referer, un link „Please try again.”. Pe un site în română apare traducerea. Deoarece funcția oprește singură execuția, codul de după ea rulează doar pentru cereri valide.

Funcția se potrivește cu formularele care folosesc wp_nonce_field() și cu linkurile generate cu wp_nonce_url(). Dă mereu un nume de acțiune: cu -1 WordPress afișează un avertisment „doing it wrong” și verifică doar dacă cererea vine din administrare. Pentru cererile AJAX există check_ajax_referer() (din 2.0.3).

Parametri

Parametru	Descriere
$action	Numele acțiunii, același ca la wp_nonce_field() / wp_nonce_url().
$query_arg	Cheia din $_REQUEST unde se află nonce-ul. Implicit '_wpnonce'.

Ce returnează

1 sau 2 pentru un nonce valid. La nonce invalid execuția se oprește; false se întoarce doar când $action este -1.

Exemple

Exemplul 1: Procesarea unui formular trimis la admin-post.php

Formularul are wp_nonce_field( ‘dex_export_note’ ); handler-ul verifică nonce-ul și dreptul, apoi redirecționează.

<?php
// Formularul (pagina de administrare):
// <form method="post" action="<?php echo esc_url( admin_url( 'admin-post.php' ) ); ?>">
//     <input type="hidden" name="action" value="dex_export_note">
//     <?php wp_nonce_field( 'dex_export_note' ); ?>
//     <button>Exportă notele</button>
// </form>

function dex_export_note() {
    check_admin_referer( 'dex_export_note' );

    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( 'Nu ai dreptul să exporți notele.' );
    }

    // ... generează fișierul CSV ...
    wp_safe_redirect( admin_url( 'admin.php?page=dex-note&exportat=1' ) );
    exit;
}
add_action( 'admin_post_dex_export_note', 'dex_export_note' );

Exemplul 2: Link de ștergere protejat cu wp_nonce_url()

wp_nonce_url() adaugă _wpnonce în adresă; acțiunea include ID-ul, deci nonce-ul merge doar pentru acel element.

<?php
$id   = 42;
$link = wp_nonce_url(
    admin_url( 'admin-post.php?action=dex_sterge_rezervare&id=' . $id ),
    'dex_sterge_rezervare_' . $id
);
echo '<a href="' . esc_url( $link ) . '">Șterge rezervarea</a>';

function dex_sterge_rezervare() {
    $id = absint( $_GET['id'] ?? 0 );
    check_admin_referer( 'dex_sterge_rezervare_' . $id );
    if ( current_user_can( 'delete_post', $id ) ) {
        wp_trash_post( $id );
    }
    wp_safe_redirect( admin_url( 'edit.php?post_type=dex_rezervare' ) );
    exit;
}
add_action( 'admin_post_dex_sterge_rezervare', 'dex_sterge_rezervare' );

Ce afișează pagina

<a href="https://exemplu.ro/wp-admin/admin-post.php?action=dex_sterge_rezervare&#038;id=42&#038;_wpnonce=5c2e9a71d4">Șterge rezervarea</a>

Greșeli frecvente

• Să apelezi check_admin_referer() fără acțiune: primești avertismentul „doing it wrong” și o verificare mult mai slabă.
• Să schimbi numele câmpului în wp_nonce_field() (de exemplu dex_nonce) și să uiți să dai același nume ca $query_arg: verificarea eșuează mereu.
• Să o folosești pentru cereri AJAX: în loc de un răspuns JSON primești o pagină HTML de eroare. Pentru AJAX folosește check_ajax_referer().

Comenzi înrudite

• wp_nonce_field: Adaugă într-un formular un câmp ascuns cu un nonce, un cod care dovedește că cererea pornește chiar de pe site-ul tău.
• current_user_can: Verifică dacă utilizatorul conectat are un anumit drept (capability), de exemplu manage_options sau edit_post pentru un articol.
• admin_menu: Acțiunea în care adaugi pagini și submeniuri în panoul de administrare, cu add_menu_page() și add_submenu_page().