# WP_REST_Request::get_headers() : lire les en-têtes bruts d’une requête REST entrante

> La méthode get_headers() de WP_REST_Request donne accès aux en-têtes d'une requête entrante, avec une normalisation des clés qu'il faut connaître avant d'écrire une vérification d'en-tête personnalisé.

- Auteur : WordPress Développement
- Publié le : 2026-10-24
- Mis à jour le : 2026-10-11
- Catégorie : Headless & API
- URL : https://www.wpmoderne.fr/headless/wp-rest-request-get-headers-entetes-requete/

## L’essentiel

- get_headers() retourne un tableau associatif dont chaque clé est normalisée en minuscules
- get_header() reste préférable pour lire un en-tête précis sans reconstruire cette normalisation à la main
- Ces en-têtes sont ceux de la requête entrante, pas ceux qu'un contrôleur s'apprête à renvoyer

« Retrieves all headers from the request. » C'est en ces termes que la référence officielle décrit `WP_REST_Request::get_headers()`, sans préciser qu'un tout autre `get_headers()` existe déjà nativement en PHP, sans aucun rapport avec une requête REST en cours de traitement : celui-là sert à interroger les en-têtes de réponse d'une URL distante. Pour un endpoint qui doit vérifier un en-tête personnalisé posé par un front ou par un CDN en amont, c'est bien la méthode de la classe `WP_REST_Request` qu'il faut appeler, jamais la fonction globale du même nom.

## Ce que retourne réellement la méthode

`WP_REST_Request::get_headers()` retourne un tableau associatif où chaque clé correspond à un nom d'en-tête, toujours en minuscules, quelle que soit la casse utilisée par le client qui a envoyé la requête. Un en-tête `X-Front-Signature` envoyé par un client sera donc retrouvé sous la clé `x-front-signature` dans ce tableau. Cette normalisation suit la pratique HTTP courante qui traite les noms d'en-têtes comme insensibles à la casse, mais elle surprend un développeur qui teste sa clé exacte telle qu'envoyée et obtient un tableau vide en retour.

```
add_action( 'rest_api_init', function () {
    register_rest_route( 'mon-domaine/v1', '/webhook', array(
        'methods'             => 'POST',
        'callback'            => 'mon_domaine_webhook_callback',
        'permission_callback' => '__return_true',
    ) );
} );

function mon_domaine_webhook_callback( WP_REST_Request $request ) {
    $headers = $request->get_headers();

    if ( empty( $headers['x-front-signature'] ) ) {
        return new WP_Error( 'signature_manquante', 'En-tête de signature absent.', array( 'status' => 401 ) );
    }

    return rest_ensure_response( array( 'recu' => true ) );
}
```

## Une deuxième subtilité : les valeurs sont des tableaux

> L'essentiel à retenir : get_headers() retourne un tableau associatif dont chaque clé est normalisée en minuscules ; get_header() reste préférable pour lire un en-tête précis sans reconstruire cette normalisation à la main ; Ces en-têtes sont ceux de la requête entrante, pas ceux qu'un contrôleur s'apprête à renvoyer

Chaque valeur du tableau retourné par `get_headers()` est elle-même un tableau, pas une chaîne directe. WordPress conserve cette structure pour gérer le cas, rare mais légal en HTTP, d'un même en-tête envoyé plusieurs fois dans la même requête. Accéder directement à `$headers['x-front-signature']` donne donc un tableau à un ou plusieurs éléments, et non la valeur elle-même. C'est précisément pour éviter cette manipulation répétée que WordPress fournit une méthode dédiée à la lecture d'un en-tête unique :

```
$signature = $request->get_header( 'x-front-signature' );

if ( null === $signature ) {
    return new WP_Error( 'signature_manquante', 'En-tête de signature absent.', array( 'status' => 401 ) );
}
```

`get_header()` applique en interne la même normalisation de casse, récupère le tableau correspondant s'il existe, et retourne toutes ses valeurs jointes par une virgule sous forme de chaîne, ou `null` si l'en-tête est absent. Pour la très grande majorité des vérifications d'en-tête personnalisé, cette méthode évite d'avoir à retraiter la structure retournée par `get_headers()`.

## Pourquoi passer par get_headers() malgré tout

`get_headers()` reste utile quand un callback doit inspecter l'ensemble des en-têtes reçus plutôt qu'une clé précise, par exemple pour journaliser une requête entrante à des fins de diagnostic, ou pour détecter la présence d'un en-tête parmi plusieurs variantes possibles posées par différents CDN. Dans ce cas, itérer sur le tableau complet reste plus direct que d'appeler `get_header()` une fois par clé candidate :

```
foreach ( $request->get_headers() as $nom => $valeurs ) {
    if ( str_starts_with( $nom, 'cf-' ) ) {
        error_log( sprintf( 'En-tête Cloudflare reçu : %s = %s', $nom, implode( ', ', $valeurs ) ) );
    }
}
```

> Un en-tête entrant n'a de valeur que si la normalisation appliquée par WordPress est comprise avant d'écrire la première condition qui le teste.

## Le piège d'une confusion avec un en-tête de réponse

La confusion la plus fréquente vient du nom même de la méthode, proche de la fonction PHP native `get_headers()` qui sert à interroger une URL distante et n'a strictement rien à voir avec une requête REST entrante en cours de traitement. Une seconde confusion, plus discrète, consiste à mélanger la lecture des en-têtes entrants avec l'écriture des en-têtes de sortie sur l'objet `WP_REST_Response`, qui utilise ses propres méthodes (`header()`, `get_headers()` côté réponse cette fois) sur une classe distincte. Les deux classes portent des méthodes au nom identique mais opèrent sur des objets différents, l'un représentant ce qui a été reçu, l'autre ce qui s'apprête à être envoyé.

- Toujours normaliser en minuscules avant de comparer un nom d'en-tête
- Préférer `get_header()` pour une clé unique connue à l'avance
- Réserver `get_headers()` à une inspection d'ensemble ou une recherche par préfixe
- Ne jamais confondre cette lecture avec les en-têtes de la réponse renvoyée par le contrôleur

## Conclusion

Lire un en-tête personnalisé posé par un front ou un CDN dans un contrôleur REST WordPress n'a rien à voir avec la fonction PHP globale du même nom : c'est `WP_REST_Request::get_headers()`, associée le plus souvent à `get_header()` pour une clé précise, qui donne accès à cette information, avec une normalisation systématique des noms en minuscules. Connaître cette normalisation avant d'écrire la première condition évite l'écueil classique d'un en-tête pourtant bien envoyé, mais jamais détecté côté serveur.

*Correction du 11 octobre 2026 : get_header() ne renvoie pas la première valeur de l'en-tête mais toutes ses valeurs jointes par une virgule.*