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

En tant que développeur PHP, vous pouvez avoir besoin de définir des cookies pour stocker des informations côté client. La fonction setcookie() est une fonction PHP intégrée qui gère cela. Dans cet article, nous abordons sa syntaxe moderne, comment définir, lire et supprimer des cookies, les erreurs les plus fréquentes, et quand utiliser les sessions à la place.

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

La fonction setcookie() est une fonction intégrée PHP qui envoie un en-tête HTTP Set-Cookie au navigateur, lui demandant de stocker un petit morceau de données. Lors de la prochaine requête, le navigateur renvoie ces données, ce qui permet à un protocole sans état comme HTTP de « se souvenir » de choses entre les chargements de page — par exemple un jeton « se souvenir de moi », une préférence de langue ou un identifiant de suivi.

Comme un cookie est un en-tête HTTP, setcookie() doit s'exécuter avant tout envoi de contenu au navigateur. Le cookie lui-même n'est pas disponible immédiatement ; il apparaît dans le superglobal $_COOKIE uniquement lors de la requête suivante, une fois que le navigateur l'a renvoyé.

Comment utiliser la fonction setcookie() ?

L'utilisation de la fonction setcookie() est simple. La syntaxe basée sur un tableau d'options a été introduite dans PHP 7.3. Dans PHP 8.1, l'ancienne syntaxe positionnelle à sept paramètres a été dépréciée. Voici la syntaxe moderne :

Syntaxe PHP de la fonction setcookie()

setcookie($name, $value, $options);

Le paramètre $options est un tableau associatif qui accepte les clés suivantes :

• expires : L'heure d'expiration du cookie (horodatage Unix).
• path : Le chemin sur le serveur dans lequel le cookie sera disponible.
• domain : Le domaine sur lequel le cookie sera disponible.
• secure : Indique si le cookie doit être transmis uniquement via HTTPS.
• httponly : Indique si le cookie doit être accessible uniquement via HTTP.
• samesite : Restreint le cookie aux requêtes du même site. Accepte 'Strict', 'Lax' ou 'None'. Remarque : si vous utilisez 'None', vous devez également définir secure à true, sinon les navigateurs modernes rejetteront le cookie.

Si vous omettez expires (ou le définissez à 0), le cookie devient un cookie de session — il n'existe que jusqu'à la fermeture du navigateur. Définir expires sur un horodatage futur en fait un cookie persistant qui survit aux redémarrages du navigateur.

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

Comment utiliser la fonction setcookie() ?

<?php

$options = [
    'expires'  => time() + (86400 * 30), // 30 days
    'path'     => '/',
    'domain'   => '.example.com',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax'
];
setcookie('username', 'john', $options);

Dans cet exemple, nous utilisons la fonction setcookie() pour définir un cookie nommé username avec la valeur john. Nous spécifions également la durée d'expiration à 30 jours à partir du moment actuel, le chemin sur le serveur comme /, le domaine comme .example.com, et nous activons les indicateurs secure, httponly et samesite pour s'assurer que le cookie n'est transmis que via HTTPS, n'est pas accessible via les scripts côté client, et est restreint aux requêtes du même site, respectivement.

Lecture des cookies

Les cookies définis avec setcookie() sont automatiquement disponibles dans le tableau superglobal $_COOKIE lors des requêtes de page suivantes. Vous pouvez vérifier leur existence et lire leurs valeurs comme ceci :

if (isset($_COOKIE['username'])) {
    echo "Welcome, " . htmlspecialchars($_COOKIE['username']);
}

Suppression des cookies

Pour supprimer un cookie, vous devez définir son heure d'expiration sur un horodatage passé. La valeur peut être laissée vide.

setcookie('username', '', [
    'expires' => time() - 3600,
    'path'    => '/',
]);

Assurez-vous que path (et domain, si vous en avez défini un) correspondent aux valeurs utilisées lors de la création du cookie. Un cookie défini avec path => '/admin' ne sera pas supprimé par un appel utilisant path => '/', car le navigateur les traite comme des cookies différents.

Remarques importantes

• Valeur de retour : setcookie() renvoie true en cas de succès et false en cas d'échec (y compris lorsque les en-têtes ont déjà été envoyés).
• En-têtes déjà envoyés : Les cookies doivent être définis avant tout envoi de contenu au navigateur (y compris le HTML, les espaces blancs avant <?php ou echo). Sinon, PHP lancera un avertissement « Headers already sent ». Consultez headers_sent() pour détecter ce cas.
• Encodage automatique : setcookie() encode automatiquement les valeurs des cookies en URL, donc l'encodage manuel est généralement inutile. Si vous devez stocker une valeur telle quelle sans encodage, utilisez plutôt setrawcookie().
• Limites de taille : Les navigateurs limitent chaque cookie à environ 4 Ko et limitent le nombre de cookies qu'un seul domaine peut stocker, donc les cookies sont destinés aux petites valeurs, pas aux données volumineuses.

Cookies vs. Sessions

Les cookies résident dans le navigateur et sont envoyés à chaque requête, donc tout ce que vous y stockez est visible (et modifiable) par l'utilisateur. Pour les données sensibles, stockez uniquement un identifiant dans le cookie et conservez les données réelles côté serveur avec les sessions PHP. Pour un aperçu plus large de la gestion des cookies en PHP, consultez le chapitre Cookies PHP.

Conclusion

La fonction setcookie() est un outil utile pour définir des cookies dans votre application web PHP. En comprenant la syntaxe moderne par tableau, en l'appelant avant tout envoi de contenu, et en faisant correspondre path/domain lors de la suppression, vous pouvez gérer de manière fiable les données côté client — et vous savez quand utiliser les sessions à la place.

Pratique