Skip to content

README.md

Latest commit

 

History

History
642 lines (467 loc) · 14.5 KB

README.md

File metadata and controls

642 lines (467 loc) · 14.5 KB
Raw

PHP Cookie library

Latest Stable Version License Total Downloads CI CodeCov PSR1 PSR4 PSR12

Traducciones: English

Biblioteca PHP para el manejo de cookies.

Requisitos

  • Sistema operativo: Linux.

  • Versiones de PHP: 8.1 | 8.2 | 8.3.

Instalación

La mejor forma de instalar esta extensión es a través de Composer.

Para instalar PHP Cookie library, simplemente escribe:

composer require josantonius/cookie

El comando anterior sólo instalará los archivos necesarios, si prefieres descargar todo el código fuente puedes utilizar:

composer require josantonius/cookie --prefer-source

También puedes clonar el repositorio completo con Git:

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

Clases disponibles

Clase Cookie

Josantonius\Cookie\Cookie

Establece las opciones de las cookies:

/**
 * Opciones:
 * 
 * domain:   Dominio para el que estará disponible la cookie.
 * expires:  Cuándo expirará la cookie.
 * httpOnly: Si la cookie sólo estará disponible a través del protocolo HTTP.
 * path:     Ruta para la que estará disponible la cookie.
 * raw:      Si la cookie se enviará como una cadena sin procesar.
 * sameSite: Impone el uso de una política samesite laxa o estricta.
 * secure:   Si la cookie sólo estará disponible a través del protocolo HTTPS.
 * 
 * Estos ajustes se utilizarán para crear y eliminar 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
);

Establece una cookie por nombre:

/**
 * @throws CookieException si las cabeceras ya han sido enviadas.
 * @throws CookieException si falla el análisis de la cadena de fecha/hora.
 */
public function set(
    string $name,
    mixed $value,
    null|int|string|DateTime $expires = null
): void;

Establece varias cookies a la vez:

/**
 * Si las cookies existen se sustituyen, si no existen se crean.
 *
 * @throws CookieException si las cabeceras ya han sido enviadas.
 */
public function replace(
    array $data,
    null|int|string|DateTime $expires = null
): void;

Obtiene una cookie por su nombre:

/**
 * Opcionalmente define un valor por defecto cuando la cookie no existe.
 */
public function get(string $name, mixed $default = null): mixed;

Obtiene todas las cookies:

public function all(): array;

Comprueba si existe una cookie:

public function has(string $name): bool;

Elimina una cookie por su nombre y devuelve su valor:

/**
 * Opcionalmente define un valor por defecto cuando la cookie no existe.
 * 
 * @throws CookieException si las cabeceras ya han sido enviadas.
 */
public function pull(string $name, mixed $default = null): mixed;

Borra una cookie por su nombre:

/**
 * @throws CookieException si las cabeceras ya han sido enviadas.
 * @throws CookieException si falla el análisis de la cadena de fecha/hora.
 */
public function remove(string $name): void;

Fachada Cookie

Josantonius\Cookie\Facades\Cookie

Establece las opciones de las cookies:

/**
 * Opciones:
 * 
 * domain:   Dominio para el que estará disponible la cookie.
 * expires:  Cuándo expirará la cookie.
 * httpOnly: Si la cookie sólo estará disponible a través del protocolo HTTP.
 * path:     Ruta para la que estará disponible la cookie.
 * raw:      Si la cookie se enviará como una cadena sin procesar.
 * sameSite: Impone el uso de una política samesite laxa o estricta.
 * secure:   Si la cookie sólo estará disponible a través del protocolo HTTPS.
 * 
 * Estos ajustes se utilizarán para crear y eliminar 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;

Establece una cookie por nombre:

/**
 * @throws CookieException si las cabeceras ya han sido enviadas.
 * @throws CookieException si falla el análisis de la cadena de fecha/hora.
 */
public static function set(
    string $name,
    mixed $value,
    null|int|string|DateTime $expires = null
): void;

Establece varias cookies a la vez:

/**
 * Si las cookies existen se sustituyen, si no existen se crean.
 *
 * @throws CookieException si las cabeceras ya han sido enviadas.
 */
public static function replace(
    array $data,
    null|int|string|DateTime $expires = null
): void;

Obtiene una cookie por su nombre:

/**
 * Opcionalmente define un valor por defecto cuando la cookie no existe.
 */
public static function get(string $name, mixed $default = null): mixed;

Obtiene todas las cookies:

public static function all(): array;

Comprueba si existe una cookie:

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

Elimina una cookie por su nombre y devuelve su valor:

/**
 * Opcionalmente define un valor por defecto cuando la cookie no existe.
 * 
 * @throws CookieException si las cabeceras ya han sido enviadas.
 */
public static function pull(string $name, mixed $default = null): mixed;

Borra una cookie por su nombre:

/**
 * @throws CookieException si las cabeceras ya han sido enviadas.
 * @throws CookieException si falla el análisis de la cadena de fecha/hora.
 */
public static function remove(string $name): void;

Excepciones utilizadas

use Josantonius\Cookie\Exceptions\CookieException;

Uso

Ejemplos de uso de esta biblioteca:

Crear una instancia de Cookie con opciones por defecto

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();
use Josantonius\Cookie\Facades\Cookie;

Cookie::options();

Crear una instancia de Cookie con opciones personalizadas

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,
);

Establece una cookie por nombre

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->set('foo', 'bar');
use Josantonius\Cookie\Facades\Cookie;

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

Establece una cookie por nombre modificando el tiempo de caducidad

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'));

Establece varias cookies a la vez

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);

Establece varias cookies a la vez modificando el tiempo de caducidad

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);

Obtiene una cookie por su nombre

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->get('foo'); // null si la cookie no existe
use Josantonius\Cookie\Facades\Cookie;

Cookie::get('foo'); // null si la cookie no existe

Obtiene una cookie por su nombre con valor por defecto si la cookie no existe

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->get('foo', false); // false si la cookie no existe
use Josantonius\Cookie\Facades\Cookie;

Cookie::get('foo', false); // false si la cookie no existe

Obtiene todas las cookies

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->all();
use Josantonius\Cookie\Facades\Cookie;

Cookie::all();

Comprueba si existe una cookie

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->has('foo');
use Josantonius\Cookie\Facades\Cookie;

Cookie::has('foo');

Elimina una cookie por su nombre y devuelve su valor

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->pull('foo'); // null si el atributo no existe
use Josantonius\Cookie\Facades\Cookie;

Cookie::pull('foo'); // null si el atributo no existe

Elimina una cookie y devuelve su valor o el valor por defecto no existe

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->pull('foo', false); // false si el atributo no existe
use Josantonius\Cookie\Facades\Cookie;

Cookie::pull('foo', false); // false si el atributo no existe

Borra una cookie por su nombre

use Josantonius\Cookie\Cookie;

$cookie = new Cookie();

$cookie->remove('foo');
use Josantonius\Cookie\Facades\Cookie;

Cookie::remove('foo');

Sobre la caducidad de las cookies

  • El parámetro expires utilizado en varios métodos de esta biblioteca acepta los siguientes tipos: int|string|DateTime.

    • Enteros se manejarán como tiempo en unix excepto el cero.

    • Cadenas se manejarán como formatos de fecha/hora. Ver Formatos de fecha y hora soportados para más información.

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

      Sería similar a:

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

    • Los objetos DateTime serán utilizados para obtener el tiempo en unix.

  • Si el parámetro expires se utiliza en los métodos set o replace, se utilizará este en lugar del valor de expires establecido en las opciones de la cookie.

    $cookie = new Cookie(
    expires: 'now +1 minute'
);

$cookie->set('foo', 'bar');                        // Caduca en 1 minuto

$cookie->set('bar', 'foo', 'now +8 days');         // Caduca en 8 días

$cookie->replace(['foo' => 'bar']);                // Caduca en 1 minuto

$cookie->replace(['foo' => 'bar'], time() + 3600); // Caduca en 1 hora

  • Si el parámetro expires pasado en las opciones es una cadena de fecha/hora, se formateará cuando se utiliza el método set o replace y no cuando se establecen las opciones.

    $cookie = new Cookie(
    expires: 'now +1 minute', // Todavía no se formateará como tiempo unix
);

$cookie->set('foo', 'bar');   // Se formateará ahora y expirará en 1 minuto

Tests

Para ejecutar las pruebas necesitarás Composer y seguir los siguientes pasos:

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

Ejecutar pruebas unitarias con PHPUnit:

composer phpunit

Ejecutar pruebas de estándares de código con PHPCS:

composer phpcs

Ejecutar pruebas con PHP Mess Detector para detectar inconsistencias en el estilo de codificación:

composer phpmd

Ejecutar todas las pruebas anteriores:

composer tests

Tareas pendientes

  • Añadir nueva funcionalidad
  • Mejorar pruebas
  • Mejorar documentación
  • Mejorar la traducción al inglés en el archivo README
  • Refactorizar código para las reglas de estilo de código deshabilitadas (ver phpmd.xml y phpcs.xml)

Registro de Cambios

Los cambios detallados de cada versión se documentan en las notas de la misma.

Contribuir

Por favor, asegúrate de leer la Guía de contribución antes de hacer un pull request, comenzar una discusión o reportar un issue.

¡Gracias por colaborar! ❤️

Patrocinar

Si este proyecto te ayuda a reducir el tiempo de desarrollo, puedes patrocinarme para apoyar mi trabajo 😊

Licencia

Este repositorio tiene una licencia MIT License.

Copyright © 2016-actualidad, Josantonius