Galletas

Una cookie HTTP (cookie web, cookie de navegador) es un pequeño fragmento de datos que un servidor envía al navegador web del usuario. El navegador puede almacenarlo y enviarlo de vuelta más tarde. solicitudes al mismo servidor. Normalmente, se utiliza para saber si dos solicitudes provienen de el mismo navegador, manteniendo a un usuario conectado, por ejemplo. Recuerda información con estado para el protocolo HTTP sin estado.

Las cookies se utilizan principalmente con tres finalidades:

Gestión de sesiones: inicios de sesión, carritos de compras, puntuaciones de juegos o cualquier otra cosa que el servidor deba recordar
Personalización: preferencias de usuario, temas y otras configuraciones
Seguimiento: Registrar y analizar el comportamiento del usuario

Para ayudarle a enviar cookies de manera eficiente a los navegadores, Higgs proporciona la clase Higgs\Cookie\Cookie para abstraer el interacción de cookies.

Creando cookies 

Actualmente existen cuatro (4) formas de crear un nuevo objeto de valor Cookie.

<?php

use Higgs\Cookie\Cookie;
use DateTime;

// Using the constructor
$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'expires'  => new DateTime('+2 hours'),
        'prefix'   => '__Secure-',
        'path'     => '/',
        'domain'   => '',
        'secure'   => true,
        'httponly' => true,
        'raw'      => false,
        'samesite' => Cookie::SAMESITE_LAX,
    ]
);

// Supplying a Set-Cookie header string
$cookie = Cookie::fromHeaderString(
    'remember_token=f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6; Path=/; Secure; HttpOnly; SameSite=Lax',
    false, // raw
);

// Using the fluent builder interface
$cookie = (new Cookie('remember_token'))
    ->withValue('f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6')
    ->withPrefix('__Secure-')
    ->withExpires(new DateTime('+2 hours'))
    ->withPath('/')
    ->withDomain('')
    ->withSecure(true)
    ->withHTTPOnly(true)
    ->withSameSite(Cookie::SAMESITE_LAX);

// Using the global function `cookie` which implicitly calls `new Cookie()`
$cookie = cookie('remember_token', 'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6');

Al construir el objeto Cookie, solo se requiere el atributo nombre. Todo lo demás es opcional. Si los atributos opcionales no se modifican, sus valores se completarán con los valores predeterminados guardados en la clase Cookie.

Anulación de valores predeterminados 

Para anular los valores predeterminados actualmente almacenados en la clase, puede pasar una Config\Cookie instancia o una matriz de valores predeterminados al método estático Cookie::setDefaults().

<?php

use Higgs\Cookie\Cookie;
use Config\Cookie as CookieConfig;

// pass in a Config\Cookie instance before constructing a Cookie class
Cookie::setDefaults(new CookieConfig());
$cookie = new Cookie('login_token');

// pass in an array of defaults
$myDefaults = [
    'expires'  => 0,
    'samesite' => Cookie::SAMESITE_STRICT,
];
Cookie::setDefaults($myDefaults);
$cookie = new Cookie('login_token');

Pasar la instancia Config\Cookie o una matriz a Cookie::setDefaults() efectivamente sobrescribirá sus valores predeterminados y persistirá hasta que se pasen nuevos valores predeterminados.

Cambiar los valores predeterminados por un tiempo limitado

Si no quieres esto comportamiento pero solo desea cambiar los valores predeterminados por un tiempo limitado, puede aprovechar Cookie::setDefaults() devuelve la matriz de valores predeterminados anterior.

<?php

use Higgs\Cookie\Cookie;
use Config\Cookie as CookieConfig;

$oldDefaults = Cookie::setDefaults(new CookieConfig());
$cookie      = new Cookie('my_token', 'muffins');

// return the old defaults
Cookie::setDefaults($oldDefaults);

Accediendo a los atributos de las cookies 

Una vez creada una instancia, puede acceder fácilmente al atributo de una Cookie utilizando uno de sus métodos de obtención.

<?php

use Higgs\Cookie\Cookie;
use DateTime;
use DateTimeZone;

$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'expires'  => new DateTime('2025-02-14 00:00:00', new DateTimeZone('UTC')),
        'prefix'   => '__Secure-',
        'path'     => '/',
        'domain'   => '',
        'secure'   => true,
        'httponly' => true,
        'raw'      => false,
        'samesite' => Cookie::SAMESITE_LAX,
    ]
);

$cookie->getName();             // 'remember_token'
$cookie->getPrefix();           // '__Secure-'
$cookie->getPrefixedName();     // '__Secure-remember_token'
$cookie->getExpiresTimestamp(); // UNIX timestamp
$cookie->getExpiresString();    // 'Fri, 14-Feb-2025 00:00:00 GMT'
$cookie->isExpired();           // false
$cookie->getMaxAge();           // the difference from time() to expires
$cookie->isRaw();               // false
$cookie->isSecure();            // true
$cookie->getPath();             // '/'
$cookie->getDomain();           // ''
$cookie->isHTTPOnly();          // true
$cookie->getSameSite();         // 'Lax'

// additional getter
$cookie->getId(); // '__Secure-remember_token;;/'

// when using `setcookie()`'s alternative signature on PHP 7.3+
// you can easily use the `getOptions()` method to supply the
// $options parameter
$cookie->getOptions();

Cookies inmutables 

Una nueva instancia de Cookie es una representación de objeto de valor inmutable de una cookie HTTP. siendo inmutable, modificar cualquiera de los atributos de la instancia no afectará la instancia original. La modificación siempre devuelve una nueva instancia. Debe conservar esta nueva instancia para poder utilizarla.

<?php

use Higgs\Cookie\Cookie;

$cookie = new Cookie('login_token', 'admin');
$cookie->getName(); // 'login_token'

$cookie->withName('remember_token');
$cookie->getName(); // 'login_token'

$new = $cookie->withName('remember_token');
$new->getName(); // 'remember_token'

Envío de cookies 

Establezca los objetos Cookie en el CookieStore del objeto Response, y el marco enviará automáticamente las cookies.

Utilice Higgs\HTTP\Response::setCookie() para configurar:

<?php

use Higgs\Cookie\Cookie;
use Config\Services;

$response = Services::response();

$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'max-age' => 3600 * 2, // Expires in 2 hours
    ]
);

$response->setCookie($cookie);

También puedes usar la función auxiliar set_cookie():

<?php

use Higgs\Cookie\Cookie;

helper('cookie');

$cookie = new Cookie(
    'remember_token',
    'f699c7fd18a8e082d0228932f3acd40e1ef5ef92efcedda32842a211d62f0aa6',
    [
        'max-age' => 3600 * 2, // Expires in 2 hours
    ]
);

set_cookie($cookie);

Usando la tienda de cookies 

Nota

Normally, there is no need to use CookieStore directly.

La clase CookieStore representa una colección inmutable de objetos Cookie.

Obtener la tienda a partir de la respuesta 

La Tienda de cookies Se puede acceder a la instancia desde el objeto Respuesta actual.

<?php

use Config\Services;

$cookieStore = Services::response()->getCookieStore();

Creando tienda de cookies 

Higgs proporciona otras tres (3) formas de crear una nueva instancia de CookieStore.

<?php

use Higgs\Cookie\Cookie;
use Higgs\Cookie\CookieStore;

// Passing an array of `Cookie` objects in the constructor
$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);

// Passing an array of `Set-Cookie` header strings
$store = CookieStore::fromCookieHeaders([
    'remember_token=me; Path=/; SameSite=Lax',
    'login_token=admin; Path=/; SameSite=Lax',
]);

// using the global `cookies` function
$store = cookies([new Cookie('login_token')], false);

// retrieving the `CookieStore` instance saved in our current `Response` object
$store = cookies();

Nota

When using the global cookies() function, the passed Cookie array will only be considered si el segundo argumento, $getGlobal, está establecido en false.

Comprobación de cookies en la tienda 

Para comprobar si existe un objeto Cookie en la instancia CookieStore, puede utilizar varias formas:

<?php

use Higgs\Cookie\Cookie;
use Higgs\Cookie\CookieStore;
use Config\Services;

// check if cookie is in the current cookie collection
$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);
$store->has('login_token');

// check if cookie is in the current Response's cookie collection
cookies()->has('login_token');
Services::response()->hasCookie('remember_token');

// using the cookie helper to check the current Response
// not available to v7.1.1 and lower
helper('cookie');
has_cookie('login_token');

Obtener cookies en la tienda 

Recuperar una instancia de Cookie en una colección de cookies es muy fácil:

<?php

use Higgs\Cookie\Cookie;
use Higgs\Cookie\CookieStore;
use Config\Services;

// getting cookie in the current cookie collection
$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);
$store->get('login_token');

// getting cookie in the current Response's cookie collection
cookies()->get('login_token');
Services::response()->getCookie('remember_token');

// using the cookie helper to get cookie from the Response's cookie collection
helper('cookie');
get_cookie('remember_token');

Al obtener una instancia de Cookie directamente de CookieStore, aparece un nombre no válido arrojará una CookieException.

<?php

// throws CookieException
$store->get('unknown_cookie');

Al obtener una instancia de Cookie de la colección de cookies de la Respuesta actual, un nombre no válido simplemente devolverá «nulo».

<?php

cookies()->get('unknown_cookie'); // null

Si no se proporcionan argumentos al obtener cookies de Respuesta, todos los objetos Cookie en la tienda se mostrará.

<?php

use Config\Services;

cookies()->get(); // array of Cookie objects

// alternatively, you can use the display method
cookies()->display();

// or even from the Response
Services::response()->getCookies();

Nota

The helper function get_cookie() gets the cookie from the current Request object, not de Respuesta. Esta función verifica la matriz $_COOKIE si esa cookie está configurada y la recupera de inmediato.

Agregar/eliminar cookies en la tienda 

Como se mencionó anteriormente, los objetos CookieStore son inmutables. Necesitas guardar la instancia modificada. para poder trabajar en ello. La instancia original no se modifica.

<?php

use Higgs\Cookie\Cookie;
use Higgs\Cookie\CookieStore;
use Config\Services;

$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);

// adding a new Cookie instance
$new = $store->put(new Cookie('admin_token', 'yes'));

// removing a Cookie instance
$new = $store->remove('login_token');

Nota

Removing a cookie from the store DOES NOT delete it from the browser. Si pretendes eliminar una cookie del navegador, debes poner un valor vacío cookie con el mismo nombre a la tienda.

Al interactuar con las cookies almacenadas en el objeto Respuesta actual, puede agregar o eliminar de forma segura cookies sin preocuparse por la naturaleza inmutable de la colección de cookies. El objeto Respuesta reemplazará la instancia con la instancia modificada.

<?php

use Config\Services;

Services::response()->setCookie('admin_token', 'yes');
Services::response()->deleteCookie('login_token');

// using the cookie helper
helper('cookie');
set_cookie('admin_token', 'yes');
delete_cookie('login_token');

Envío de cookies en la tienda 

Obsoleto desde la versión 4.1.6.

Importante

This method is deprecated. It will be removed in future releases.

La mayoría de las veces, no necesita preocuparse por enviar cookies manualmente. Higgs hará esto para ti. Sin embargo, si realmente necesita enviar cookies manualmente, puede utilizar el método dispatch. Al igual que Al enviar otros encabezados, debe asegurarse de que los encabezados aún no se hayan enviado verificando el valor. de headers_sent().

<?php

use Higgs\Cookie\Cookie;
use Higgs\Cookie\CookieStore;

$store = new CookieStore([
    new Cookie('login_token'),
    new Cookie('remember_token'),
]);

$store->dispatch(); // After dispatch, the collection is now empty.

Personalización de cookies 

Ya existen valores predeterminados sensatos dentro de la clase Cookie para garantizar la creación fluida de cookies. objetos. Sin embargo, es posible que desee definir sus propios ajustes cambiando los siguientes ajustes en el Clase Config\Cookie en el archivo app/Config/Cookie.php.

En tiempo de ejecución, puede proporcionar manualmente un nuevo valor predeterminado utilizando el método Cookie::setDefaults().

Referencia de clase 

class Higgs\Cookie\CookieStore

static fromCookieHeaders(array $headers[, bool $raw = false])

Parámetros:

$header (array) – Matriz de encabezados Set-Cookie
$raw (bool) – si no se debe utilizar codificación URL

Tipo del valor devuelto:

Tienda de cookies

Devuelve:

instancia CookieStore

Lanza:

CookieException

Crea un CookieStore a partir de una serie de encabezados Set-Cookie.

__construct(array $cookies)

Parámetros:

$cookies (array) – Matriz de objetos Cookie

Tipo del valor devuelto:

Tienda de cookies

Devuelve:

instancia CookieStore

Lanza:

CookieException

has(string $name[, string $prefix = ''[, ?string $value = null]]) → bool

Parámetros:

$nombre (string) – nombre de la cookie
$prefijo (string) – Prefijo de cookie
$ (string|valor nulo) – valor de cookie

Tipo del valor devuelto:

booleano

Devuelve:

Comprueba si un objeto Cookie identificado por nombre y prefijo está presente en la colección.

get(string $name[, string $prefix = '']) → Cookie

Parámetros:

$nombre (string) – nombre de la cookie
$prefijo (string) – Prefijo de cookie

Tipo del valor devuelto:

Cookie

Devuelve:

Recupera una instancia de Cookie identificada por un nombre y prefijo.

Lanza:

CookieException

put(Cookie $cookie) → CookieStore

Parámetros:

$cookie (Cookie) – Un objeto Cookie

Tipo del valor devuelto:

Tienda de cookies

Devuelve:

nueva instancia CookieStore

Almacene una nueva cookie y devuelva una nueva colección. La colección original se mantiene sin cambios.

remove(string $name[, string $prefix = '']) → CookieStore

Parámetros:

$nombre (string) – nombre de la cookie
$prefijo (string) – Prefijo de cookie

Tipo del valor devuelto:

Tienda de cookies

Devuelve:

nueva instancia CookieStore

Elimina una cookie de una colección y devuelve una colección actualizada. La colección original se mantiene sin cambios.

dispatch() → void

Tipo del valor devuelto:: nulo

Envía todas las cookies en la tienda.

display() → array

Tipo del valor devuelto:: matriz
Devuelve:: Devuelve todas las instancias de cookies en la tienda.

clear() → void

Tipo del valor devuelto:: nulo

Borra la colección de cookies.