Rechercher une fonction PHP

setcookie

Table des matières

(PHP 4, PHP 5, PHP 7)

setcookie — Envoie un cookie

Description

bool setcookie ( string $name [, string $value [, int $expire = 0 [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false ]]]]]] )

setcookie() définit un cookie qui sera envoyé avec le reste des en-têtes. Comme pour les autres en-têtes, les cookies doivent être envoyés avant toute autre sortie (c'est une restriction du protocole HTTP, pas de PHP). Cela vous impose d'appeler cette fonction avant toute balise <html> ou <head>.

Une fois que le cookie a été placé, il est accessible dans les variables globales $_COOKIE ou bien $HTTP_COOKIE_VARS. Notez que les superglobales comme $_COOKIE deviennent disponibles depuis PHP 4.1.0. Les valeurs de cookies existent aussi dans la variable $_REQUEST.

  

Liste de paramètres

Tous les arguments sauf name (nom) sont optionnels. Si seul le nom est présent, le cookie portant ce nom sera supprimé du navigateur de l'internaute. Vous pouvez aussi utiliser une chaîne vide ("") comme valeur, pour ignorer un argument. Comme l'argument expire est un entier, il ne peut pas être ignoré avec une chaîne vide, vous devez utiliser le zéro pour cela (0).

La » RFC 6265 est la référence pour l'interprétation des paramètres passés à setcookie().

name

Le nom du cookie.

value

La valeur du cookie. Cette valeur est stockée sur l'ordinateur du client ; ne stockez pas d'informations importantes. Si le paramètre name vaut 'cookiename', alors cette valeur est retrouvée en utilisant $_COOKIE['cookiename'].

expire

Le temps après lequel le cookie expire. C'est un timestamp Unix, donc, ce sera un nombre de secondes depuis l'époque Unix (1 Janvier 1970). En d'autres termes, vous devriez fixer cette valeur à l'aide de la fonction time() en y ajoutant le nombre de secondes après lequel on veut que le cookie expire. Vous pouvez utiliser aussi mktime(). time()+60*60*24*30 fera expirer le cookie dans 30 jours. Si vous ne spécifiez pas ce paramètre ou s'il vaut 0, le cookie expirera à la fin de la session (lorsque le navigateur sera fermé).

Note:

Vous pourrez noter que le paramètre expire prend un timestamp unique, et non pas la date au format Jour, JJ-Mois-AAAA HH:MM:SS GMT, car PHP fait la conversion en interne.

path

Le chemin sur le serveur sur lequel le cookie sera disponible. Si la valeur est '/', le cookie sera disponible sur l'ensemble du domaine domain. Si la valeur est '/foo/', le cookie sera uniquement disponible dans le répertoire /foo/ ainsi que tous ses sous-répertoires comme /foo/bar/ dans le domaine domain. La valeur par défaut est le répertoire courant où le cookie a été défini.

domain

Le domaine pour lequel le cookie est disponible. Le fait de définir le domaine à 'www.example.com' rendra le cookie disponible pour le sous-domaine www mais aussi pour les sous-domaines supérieurs (ex: 'sub.www.example.com'). Les cookies disponibles pour un domaine inférieur, comme 'example.com' seront aussi disponibles pour les sous-domaines, comme 'www.example.com'. Les anciens navigateurs continuant d'implémenter la » RFC 2109 (obsolète) peuvent nécessiter un . pour rendre disponible tous les sous-domaines.

secure

Indique si le cookie doit uniquement être transmis à travers une connexion sécurisée HTTPS depuis le client. Lorsqu'il est positionné à TRUE, le cookie ne sera envoyé que si la connexion est sécurisée. Côté serveur, c'est au développeur d'envoyer ce genre de cookie uniquement sur les connexions sécurisées (par exemple, en utilisant la variable $_SERVER["HTTPS"]).

httponly

Lorsque ce paramètre vaut TRUE, le cookie ne sera accessible que par le protocole HTTP. Cela signifie que le cookie ne sera pas accessible via des langages de scripts, comme Javascript. Il a été accepté que cette configuration permet de limiter les attaques via XSS (bien qu'elle ne soit pas supportée par tous les navigateurs), c'est relativement discutable. Ajouté en PHP 5.2.0. TRUE ou FALSE

  

Valeurs de retour

Si quelque chose a été envoyé sur la sortie standard avant l'appel à cette fonction, setcookie() échouera et retournera FALSE. Si setcookie() réussi, elle retournera TRUE. Cela n'indique pas si le client accepte ou pas le cookie.

  

Exemples

Quelques exemples d'envoi de cookies :

Exemple #1 Exemple d'envoi d'un cookie avec setcookie()

<?php
$value = 'Valeur de test';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* expire dans 1 heure */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
?>

Notez que la partie "valeur" du cookie sera automatiquement encodée URL lorsque vous envoyez le cookie et, lorsque vous le recevez, il sera automatiquement décodé et affecté à la variable du même nom que le cookie. Si vous ne souhaitez pas ce comportement par défaut, vous pouvez utiliser la fonction setrawcookie(). Pour voir le résultat, essayez les scripts suivants :

<?php
// Afficher un cookie
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];

// Une autre méthode pour afficher tous les cookies
print_r($_COOKIE);
?>

Exemple #2 Exemple d'effacement d'un cookie avec setcookie()

Pour effacer un cookie sur le client, vous devez toujours vous assurer que sa date d'expiration est passée, pour déclencher le mécanisme du navigateur client. Voici comment procéder :

<?php
// Utilisation de la date courante, moins une heure
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>

Exemple #3 setcookie() et les tableaux

Vous pouvez aussi utiliser les cookies avec des tableaux, en utilisant la notation des tableaux. Cela a pour effet de créer autant de cookies que votre tableau a d'éléments, mais lorsque les cookies seront reçus par votre script, les valeurs seront placées dans un tableau :

<?php
// Définit les cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// Après le rechargemet de la page, nous les affichons
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);        
        echo "$name : $value <br />\n";
    }
}
?>

L'exemple ci-dessus va afficher :

three : cookiethree
two : cookietwo
one : cookieone

  

Historique

Version Description
5.5.0 Un attribut Max-Age est maintenant inclus dans l'en-tête Set-Cookie envoyé au client.
5.2.0 Le paramètre httponly a été ajouté.

  

Notes

Note:

Vous pouvez utiliser la bufferisation de sortie pour pouvoir envoyer du contenu avant d'appeler cette fonction, avec la contrepartie que toute votre page sera envoyée en une fois. Vous pouvez faire cela en appelant ob_start() et ob_end_flush() dans votre script, ou en activant la directive output_buffering dans votre fichier de configuration php.ini ou dans le fichier de configuration de votre serveur.

Note:

Si la directive PHP register_globals est positionnée à on, la valeur du cookie est aussi disponible dans une variable. Dans l'exemple ci-dessous, $TestCookie existe. Il est vivement recommandé d'utiliser $_COOKIE.

Erreurs communes :

  • Les cookies ne seront accessibles qu'au chargement de la prochaine page, ou au rechargement de la page courante. Pour tester si un cookie a été défini avec succès, vérifiez la présence du cookie au prochain chargement de la page avant que le cookie n'expire. Le délai d'expiration est défini en utilisant le paramètre expire. Une façon simple de vérifier le positionnement du cookie est d'utiliser print_r($_COOKIE);.
  • Les cookies doivent être effacés avec les mêmes paramètres que ceux utilisés lors de leur création. Si l'argument value est une chaîne vide ou vaut FALSE et que les autres arguments sont exactement les mêmes que lors du positionnement du cookie, alors le cookie sera effacé du client. En interne, l'effacement est réalisé en positionnant la valeur à 'deleted' et la date d'expiration à une année dans le passé.
  • Du fait que l'assignation d'une valeur valant FALSE à un cookie tente de l'effacer, vous ne devriez pas utiliser de booléen. À la place, utilisez 0 pour FALSE et 1 pour TRUE.
  • Les noms des cookies peuvent être des tableaux de noms et seront disponibles dans vos scripts PHP sous la forme de tableaux mais des cookies différents seront placés sur le client. Utilisez explode() pour placer un cookie avec des noms et des valeurs multiples. Il n'est pas recommandé d'utiliser la fonction serialize() pour réaliser ceci, car cela peut conduire à des problèmes de sécurité.

Les appels multiples à la fonction setcookie() seront effectués dans l'ordre.

  

Voir aussi

Rechercher une fonction PHP

Version en cache

22/12/2024 14:17:33 Cette version de la page est en cache (à la date du 22/12/2024 14:17:33) afin d'accélérer le traitement. Vous pouvez activer le mode utilisateur dans le menu en haut pour afficher la dernère version de la page.

Document créé le 30/01/2003, dernière modification le 26/10/2018
Source du document imprimé : https://www.gaudry.be/php-rf-function.setcookie.html

L'infobrol est un site personnel dont le contenu n'engage que moi. Le texte est mis à disposition sous licence CreativeCommons(BY-NC-SA). Plus d'info sur les conditions d'utilisation et sur l'auteur.

Références

  1. Consulter le document html Langue du document :fr Manuel PHP : http://php.net

Ces références et liens indiquent des documents consultés lors de la rédaction de cette page, ou qui peuvent apporter un complément d'information, mais les auteurs de ces sources ne peuvent être tenus responsables du contenu de cette page.
L'auteur de ce site est seul responsable de la manière dont sont présentés ici les différents concepts, et des libertés qui sont prises avec les ouvrages de référence. N'oubliez pas que vous devez croiser les informations de sources multiples afin de diminuer les risques d'erreurs.

Table des matières Haut