php cookie

bibliothèque php cookie

Traductions : espagnol

Bibliothèque PHP pour gérer les cookies.

---

• Exigences
• Installation
• Cours disponibles
  • Classe de cookies
  • Façade de cookies
• Exceptions utilisées
• Usage
• À propos de l'expiration des cookies
• Essais
• FAIRE
• Journal des modifications
• Contribution
• Parrainer
• Licence

---

Exigences

• Système d'exploitation : Linux.

• Versions PHP : 8.1 | 8.2 | 8.3.

Installation

La méthode préférée pour installer cette extension est via Composer.

Pour installer la bibliothèque php cookie , simplement :

 composer require josantonius/cookie

La commande précédente n'installera que les fichiers nécessaires, si vous préférez télécharger l'intégralité du code source, vous pouvez utiliser :

 composer require josantonius/cookie --prefer-source

Vous pouvez également cloner le dépôt complet avec Git :

 git clone https://github.com/josantonius/php-cookie.git 

Cours disponibles

Classe de cookies

JosantoniusCookieCookie

Définit les options des cookies :

 /**
 * Cookie options:
 * 
 * domain:   Domain for which the cookie is available.
 * expires:  The time the cookie will expire.
 * httpOnly: If cookie will only be available through the HTTP protocol.
 * path:     Path for which the cookie is available.
 * raw:      If cookie will be sent as a raw string.
 * sameSite: Enforces the use of a Lax or Strict SameSite policy.
 * secure:   If cookie will only be available through the HTTPS protocol.
 * 
 * These settings will be used to create and delete cookies.
 * 
 * @throws CookieException if $sameSite value is wrong.
 *
 * @see https://www.php.net/manual/en/datetime.formats.php for date formats.
 * @see https://www.php.net/manual/en/function.setcookie.php for more information.
 */
public function __construct(
    private string              $ domain   = '' ,
    private int | string | DateTime $ expires  = 0 ,
    private bool                $ httpOnly = false ,
    private string              $ path     = ' / ' ,
    private bool                $ raw      = false ,
    private null | string         $ sameSite = null ,
    private bool                $ secure   = false
);

Définit un cookie par son nom :

 /**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public function set(
    string $ name ,
    mixed $ value ,
    null | int | string | DateTime $ expires = null
): void ;

Définit plusieurs cookies à la fois :

 /**
 * If cookies exist they are replaced, if they do not exist they are created.
 *
 * @throws CookieException if headers already sent.
 */
public function replace(
    array $ data ,
    null | int | string | DateTime $ expires = null
): void ;

Obtient un cookie par nom :

 /**
 * Optionally defines a default value when the cookie does not exist.
 */
public function get( string $ name , mixed $ default = null ): mixed ;

Obtient tous les cookies :

 public function all(): array ;

Vérifiez si un cookie existe :

 public function has( string $ name ): bool ;

Supprime un cookie par son nom et renvoie sa valeur :

 /**
 * Optionally defines a default value when the cookie does not exist.
 * 
 * @throws CookieException if headers already sent.
 */
public function pull( string $ name , mixed $ default = null ): mixed ;

Supprime un cookie par son nom :

 /**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public function remove( string $ name ): void ;

Façade de cookies

JosantoniusCookieFacadesCookie

Définit les options des cookies :

 /**
 * Cookie options:
 * 
 * domain:   Domain for which the cookie is available.
 * expires:  The time the cookie will expire.
 * httpOnly: If cookie will only be available through the HTTP protocol.
 * path:     Path for which the cookie is available.
 * raw:      If cookie will be sent as a raw string.
 * sameSite: Enforces the use of a Lax or Strict SameSite policy.
 * secure:   If cookie will only be available through the HTTPS protocol.
 * 
 * These settings will be used to create and delete cookies.
 * 
 * @throws CookieException if $sameSite value is wrong.
 *
 * @see https://www.php.net/manual/en/datetime.formats.php for date formats.
 * @see https://www.php.net/manual/en/function.setcookie.php for more information.
 */
public static function options(
    string              $ domain   = '' ,
    int | string | DateTime $ expires  = 0 ,
    bool                $ httpOnly = false ,
    string              $ path     = ' / ' ,
    bool                $ raw      = false ,
    null | string         $ sameSite = null ,
    bool                $ secure   = false
): void ;

Définit un cookie par son nom :

 /**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public static function set(
    string $ name ,
    mixed $ value ,
    null | int | string | DateTime $ expires = null
): void ;

Définit plusieurs cookies à la fois :

 /**
 * If cookies exist they are replaced, if they do not exist they are created.
 *
 * @throws CookieException if headers already sent.
 */
public static function replace(
    array $ data ,
    null | int | string | DateTime $ expires = null
): void ;

Obtient un cookie par nom :

 /**
 * Optionally defines a default value when the cookie does not exist.
 */
public static function get( string $ name , mixed $ default = null ): mixed ;

Obtient tous les cookies :

 public static function all(): array ;

Vérifiez si un cookie existe :

 public static function has( string $ name ): bool ;

Supprime un cookie par son nom et renvoie sa valeur :

 /**
 * Optionally defines a default value when the cookie does not exist.
 * 
 * @throws CookieException if headers already sent.
 */
public static function pull( string $ name , mixed $ default = null ): mixed ;

Supprime un cookie par son nom :

 /**
 * @throws CookieException if headers already sent.
 * @throws CookieException if failure in date/time string analysis.
 */
public static function remove( string $ name ): void ;

Exceptions utilisées

 use Josantonius  Cookie  Exceptions  CookieException ;

Usage

Exemple d'utilisation de cette bibliothèque :

Créer une instance de cookie avec les options par défaut

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: options ();

Créer une instance de cookie avec des options personnalisées

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie (
    domain: ' example.com ' ,
    expires: time () + 3600 ,
    httpOnly: true ,
    path: ' /foo ' ,
    raw: true ,
    sameSite: ' Strict ' ,
    secure: true ,
);

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: options (
    expires: ' now +1 hour ' ,
    httpOnly: true ,
);

Définit un cookie par son nom

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> set ( ' foo ' , ' bar ' );

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: set ( ' foo ' , ' bar ' );

Définit un cookie par nom modifiant le délai d'expiration

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> set ( ' foo ' , ' bar ' , time () + 3600 );

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: set ( ' foo ' , ' bar ' , new DateTime ( ' now +1 hour ' ));

Définit plusieurs cookies à la fois

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> replace ([
    ' foo ' => ' bar ' ,
    ' bar ' => ' foo '
]);

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: replace ([
    ' foo ' => ' bar ' ,
    ' bar ' => ' foo '
], time () + 3600 );

Définit plusieurs cookies à la fois en modifiant le délai d'expiration

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> replace ([
    ' foo ' => ' bar ' ,
    ' bar ' => ' foo '
], time () + 3600 );

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: replace ([
    ' foo ' => ' bar ' ,
    ' bar ' => ' foo '
], time () + 3600 );

Obtient un cookie par son nom

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> get ( ' foo ' ); // null if the cookie does not exist 

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: get ( ' foo ' ); // null if the cookie does not exist

Obtient un cookie par nom avec une valeur par défaut si le cookie n'existe pas

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> get ( ' foo ' , false ); // false if cookie does not exist 

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: get ( ' foo ' , false ); // false if cookie does not exist

Obtient tous les cookies

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> all ();

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: all ();

Vérifier si un cookie existe

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> has ( ' foo ' );

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: has ( ' foo ' );

Supprime un cookie par son nom et renvoie sa valeur

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> pull ( ' foo ' ); // null if attribute does not exist 

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: pull ( ' foo ' ); // null if attribute does not exist

Supprime un cookie et renvoie sa valeur ou sa valeur par défaut s'il n'existe pas

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> pull ( ' foo ' , false ); // false if attribute does not exist 

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: pull ( ' foo ' , false ); // false if attribute does not exist

Supprime un cookie par son nom

 use Josantonius  Cookie  Cookie ;

$ cookie = new Cookie ();

$ cookie -> remove ( ' foo ' );

 use Josantonius  Cookie  Facades  Cookie ;

Cookie:: remove ( ' foo ' );

À propos de l'expiration du cookie

• Le paramètre expires utilisé dans plusieurs méthodes de cette bibliothèque accepte les types suivants : int|string|DateTime .

  • Integers seront traités comme du temps Unix sauf zéro.

  • Strings seront traitées comme des formats date/heure. Voir Formats de date et d'heure pris en charge pour plus d'informations.

     $ cookie = new Cookie (
        expires: ' 2016-12-15 +1 day '
    );

    Cela ressemblerait à :

     $ cookie = new Cookie (
        expires: new DateTime ( ' 2016-12-15 +1 day ' )
    );

  • Les objets DateTime seront utilisés pour obtenir l’heure Unix.

• Si le paramètre expires est utilisé dans les méthodes set ou replace , il sera pris à la place de la valeur expires définie dans les options du cookie.

   $ cookie = new Cookie (
      expires: ' now +1 minute '
  );
  
  $ cookie -> set ( ' foo ' , ' bar ' );                        // Expires in 1 minute
  
  $ cookie -> set ( ' bar ' , ' foo ' , ' now +8 days ' );         // Expires in 8 days
  
  $ cookie -> replace ([ ' foo ' => ' bar ' ]);                // Expires in 1 minute
  
  $ cookie -> replace ([ ' foo ' => ' bar ' ], time () + 3600 ); // Expires in 1 hour

• Si le paramètre expires passé dans les options est une chaîne date/heure, il est formaté lors de l'utilisation de la méthode set ou replace et non lors de la définition des options.

   $ cookie = new Cookie (
      expires: ' now +1 minute ' , // It will not be formatted as unix time yet
  );
  
  $ cookie -> set ( ' foo ' , ' bar ' );   // It is will formatted now and expires in 1 minute 

Essais

Pour exécuter des tests, vous avez juste besoin de composer et d'exécuter ce qui suit :

 git clone https://github.com/josantonius/php-cookie.git 

 cd php-cookie 

 composer install

Exécutez des tests unitaires avec PHPUnit :

 composer phpunit

Exécutez des tests standards de code avec PHPCS :

 composer phpcs

Exécutez les tests PHP Mess Detector pour détecter les incohérences dans le style de code :

 composer phpmd

Exécutez tous les tests précédents :

 composer tests 

FAIRE

• Ajouter une nouvelle fonctionnalité
• Améliorer les tests
• Améliorer la documentation
• Améliorer la traduction anglaise dans le fichier README
• Refactoriser le code pour les règles de style de code désactivées (voir phpmd.xml et phpcs.xml)

Journal des modifications

Les modifications détaillées pour chaque version sont documentées dans les notes de version.

Contribution

Veuillez vous assurer de lire le guide de contribution avant de faire une pull request, de démarrer une discussion ou de signaler un problème.

Merci à tous les contributeurs ! ❤️

Parrainer

Si ce projet vous aide à réduire votre temps de développement, vous pouvez me sponsoriser pour soutenir mon travail open source ?

Licence

Ce référentiel est sous licence MIT.

Copyright © 2016-présent, Josantonius