Fonction PHP setrawcookie() : Tout ce que vous devez savoir

En tant que développeur PHP, vous pouvez avoir besoin de définir des cookies bruts pour votre application web afin de stocker des informations côté client. La fonction setrawcookie() est une fonction PHP intégrée qui vous permet de définir un cookie brut. Contrairement à la fonction standard setcookie(), setrawcookie() n'encode pas la valeur du cookie en URL, ce qui la rend utile lorsque vous devez stocker des données pré-encodées ou des chaînes binaires. Dans cet article, nous examinons en détail la fonction setrawcookie() — sa syntaxe, ses paramètres, la forme moderne avec tableau d'options, les pièges courants et ses différences avec setcookie().

Cette page suppose que vous comprenez déjà les bases des cookies PHP. Si vous souhaitez simplement stocker du texte ordinaire, setcookie() est généralement le meilleur choix — n'utilisez setrawcookie() que lorsque vous devez envoyer la valeur exactement telle quelle.

Qu'est-ce que la fonction setrawcookie() ?

La fonction setrawcookie() est une fonction intégrée PHP (disponible depuis PHP 5.2.0) qui vous permet de définir un cookie brut côté client. Elle fonctionne en ajoutant un en-tête de réponse HTTP Set-Cookie, donc — comme toute fonction émettant des en-têtes — elle doit être appelée avant tout envoi de sortie au navigateur (aucun HTML affiché, aucune ligne vide avant <?php, aucun BOM). Si une sortie a déjà commencé, l'en-tête est silencieusement ignoré. Consultez headers_sent() pour savoir comment détecter cette situation.

La fonction retourne true si l'en-tête a été correctement mis en file d'attente et false en cas d'échec. Notez qu'un retour true ne garantit pas que le navigateur a accepté le cookie ou le renverra — cela signifie seulement que l'en-tête a été émis.

Comment utiliser la fonction setrawcookie() ?

L'utilisation de la fonction setrawcookie() est simple. Voici la syntaxe :

Syntaxe PHP

setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

La fonction accepte sept paramètres :

• $name : Le nom du cookie.
• $value : La valeur brute du cookie (non encodée en URL).
• $expire : L'heure d'expiration sous forme d'horodatage Unix.
• $path : Le chemin serveur où le cookie sera disponible.
• $domain : Le domaine où le cookie sera disponible.
• $secure : Indique si le cookie doit être transmis uniquement via HTTPS.
• $httponly : Indique si le cookie doit être inaccessible au JavaScript côté client.

Voici un exemple d'utilisation de la fonction setrawcookie() pour définir un cookie brut :

Exemple

<?php

$name = "username";
$value = "john";
$expire = time() + (86400 * 30); // 30 days
$path = "/";
$domain = ".example.com";
$secure = true;
$httponly = true;
setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

Dans cet exemple, nous utilisons la fonction setrawcookie() pour définir un cookie brut nommé username avec la valeur john. Nous spécifions l'heure d'expiration à 30 jours à partir du moment actuel (en utilisant time() comme base), le chemin serveur comme / et le domaine comme .example.com. Les drapeaux secure et httponly sont définis à true pour garantir que le cookie n'est transmis que via HTTPS et est inaccessible au JavaScript côté client.

La signature avec tableau d'options (PHP 7.3+)

Depuis PHP 7.3, vous pouvez passer un seul tableau $options au lieu des arguments positionnels. C'est la forme recommandée car c'est la seule façon de définir l'attribut SameSite, qui contrôle si le cookie est envoyé lors de requêtes cross-site :

<?php

setrawcookie("username", "john", [
    "expires"  => time() + (86400 * 30), // 30 days
    "path"     => "/",
    "domain"   => ".example.com",
    "secure"   => true,
    "httponly" => true,
    "samesite" => "Strict", // "Strict", "Lax", or "None"
]);

Avec la forme tableau, la clé $expire se nomme expires (avec un s), et samesite n'a pas d'équivalent dans la signature positionnelle.

Lire le cookie en retour

Un cookie défini lors d'une requête n'est pas disponible dans $_COOKIE tant que le navigateur ne le renvoie pas lors d'une requête ultérieure. Lors de cette requête suivante, vous le lisez comme n'importe quel autre cookie :

<?php

if (isset($_COOKIE["username"])) {
    echo "Welcome back, " . $_COOKIE["username"];
} else {
    echo "Cookie not set yet.";
}

Comme setrawcookie() n'encode pas la valeur, les octets que vous avez stockés sont retournés exactement tels quels — il n'y a pas d'étape automatique urldecode() lors de la lecture.

Supprimer un cookie brut

Pour supprimer un cookie, définissez-le à nouveau avec une heure d'expiration dans le passé. Le name, le path et le domain doivent correspondre au cookie d'origine :

<?php

setrawcookie("username", "", time() - 3600, "/", ".example.com");

setrawcookie() vs setcookie()

La principale différence entre setcookie() et setrawcookie() réside dans la façon dont elles gèrent la valeur du cookie. setcookie() encode automatiquement la valeur en URL à l'aide de rawurlencode(), ce qui est sûr pour le texte standard mais peut poser problème si vous devez stocker des données pré-encodées ou des chaînes binaires. setrawcookie() ignore cette étape d'encodage, vous donnant un contrôle total sur la valeur brute. Pour la plupart des cas d'utilisation standard, setcookie() est préférée, mais setrawcookie() est indispensable lorsque vous travaillez avec des données déjà encodées.

Une conséquence pratique : avec setrawcookie(), vous êtes responsable de garder la valeur compatible avec les cookies. Une valeur de cookie brute ne doit pas contenir certains caractères — caractères de contrôle, espaces, virgules, points-virgules ou signes égal — car ils ont une signification particulière dans l'en-tête Set-Cookie. Si votre valeur peut contenir ces caractères, encodez-la vous-même (par exemple avec rawurlencode()) avant de la passer :

<?php

$raw = rawurlencode("john doe; admin=1"); // pre-encode unsafe bytes
setrawcookie("username", $raw, time() + 3600, "/");

Conclusion

La fonction setrawcookie() est un outil utile pour définir des cookies bruts dans votre application web PHP. En comprenant sa syntaxe, ses paramètres, la forme avec tableau d'options et ses différences avec setcookie(), vous pouvez stocker en toute sécurité des données pré-encodées côté client. N'oubliez pas de l'appeler avant toute sortie, préférez le tableau d'options pour pouvoir définir SameSite, et n'y recourez que lorsque vous avez réellement besoin de contourner l'encodage URL.

Sujets connexes

• Cookies PHP — vue d'ensemble du fonctionnement des cookies en PHP.
• setcookie() — le setter de cookies standard avec encodage URL.
• Sessions PHP — état côté serveur, une alternative aux cookies.
• header() — envoyer manuellement des en-têtes HTTP arbitraires.
• headers_sent() — vérifier si les en-têtes ont déjà été envoyés.

Pratique