PHP Cookie library
, (*1)
Translations: Español, (*2)
PHP library for handling cookies., (*3)
Requirements
-
Operating System: Linux., (*4)
-
PHP versions: 8.1 | 8.2 | 8.3., (*5)
Installation
The preferred way to install this extension is through Composer., (*6)
To install PHP Cookie library, simply:, (*7)
composer require josantonius/cookie
The previous command will only install the necessary files,
if you prefer to download the entire source code you can use:, (*8)
composer require josantonius/cookie --prefer-source
You can also clone the complete repository with Git:, (*9)
git clone https://github.com/josantonius/php-cookie.git
Available Classes
Cookie Class
Josantonius\Cookie\Cookie, (*10)
Sets cookie options:, (*11)
/**
* 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
);
Sets a cookie by name:, (*12)
/**
* @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;
Sets several cookies at once:, (*13)
/**
* 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;
Gets a cookie by name:, (*14)
/**
* Optionally defines a default value when the cookie does not exist.
*/
public function get(string $name, mixed $default = null): mixed;
Gets all cookies:, (*15)
public function all(): array;
Check if a cookie exists:, (*16)
public function has(string $name): bool;
Deletes a cookie by name and returns its value:, (*17)
/**
* 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;
Deletes an cookie by name:, (*18)
/**
* @throws CookieException if headers already sent.
* @throws CookieException if failure in date/time string analysis.
*/
public function remove(string $name): void;
Cookie Facade
Josantonius\Cookie\Facades\Cookie, (*19)
Sets cookie options:, (*20)
/**
* 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;
Sets a cookie by name:, (*21)
/**
* @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;
Sets several cookies at once:, (*22)
/**
* 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;
Gets a cookie by name:, (*23)
/**
* Optionally defines a default value when the cookie does not exist.
*/
public static function get(string $name, mixed $default = null): mixed;
Gets all cookies:, (*24)
public static function all(): array;
Check if a cookie exists:, (*25)
public static function has(string $name): bool;
Deletes a cookie by name and returns its value:, (*26)
/**
* 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;
Deletes an cookie by name:, (*27)
/**
* @throws CookieException if headers already sent.
* @throws CookieException if failure in date/time string analysis.
*/
public static function remove(string $name): void;
Exceptions Used
use Josantonius\Cookie\Exceptions\CookieException;
Usage
Example of use for this library:, (*28)
Create Cookie instance with default options
use Josantonius\Cookie\Cookie;
$cookie = new Cookie();
use Josantonius\Cookie\Facades\Cookie;
Cookie::options();
Create Cookie instance with custom options
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,
);
Sets a cookie by name
use Josantonius\Cookie\Cookie;
$cookie = new Cookie();
$cookie->set('foo', 'bar');
use Josantonius\Cookie\Facades\Cookie;
Cookie::set('foo', 'bar');
Sets a cookie by name modifying the expiration time
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'));
Sets several cookies at once
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);
Sets several cookies at once modifying the expiration time
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);
Gets a cookie by name
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
Gets a cookie by name with default value if cookie does not exist
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
Gets all cookies
use Josantonius\Cookie\Cookie;
$cookie = new Cookie();
$cookie->all();
use Josantonius\Cookie\Facades\Cookie;
Cookie::all();
Check if a cookie exists
use Josantonius\Cookie\Cookie;
$cookie = new Cookie();
$cookie->has('foo');
use Josantonius\Cookie\Facades\Cookie;
Cookie::has('foo');
Deletes a cookie by name and returns its value
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
Deletes a cookie and returns its value or default value if does not exist
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
Deletes an cookie by name
use Josantonius\Cookie\Cookie;
$cookie = new Cookie();
$cookie->remove('foo');
use Josantonius\Cookie\Facades\Cookie;
Cookie::remove('foo');
About cookie expires
-
The expires parameter used in several methods of this library accepts the following types:
int|string|DateTime., (*29)
-
Integers will be handled as unix time except zero.
-
Strings will be handled as date/time formats.
See supported Date and Time Formats
for more information.
$cookie = new Cookie(
expires: '2016-12-15 +1 day'
);
It would be similar to:, (*30)
$cookie = new Cookie(
expires: new DateTime('2016-12-15 +1 day')
);
-
DateTime objects will be used to obtain the unix time.
-
If the expires parameter is used in the set or replace methods,
it will be taken instead of the expires value set in the cookie options., (*31)
$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
-
If the expires parameter passed in the options is a date/time string,
it is formatted when using the set or replace method and not when setting the options., (*32)
$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
Tests
To run tests you just need composer
and to execute the following:, (*33)
git clone https://github.com/josantonius/php-cookie.git
cd php-cookie
composer install
Run unit tests with PHPUnit:, (*34)
composer phpunit
Run code standard tests with PHPCS:, (*35)
composer phpcs
Run PHP Mess Detector tests to detect inconsistencies in code style:, (*36)
composer phpmd
Run all previous tests:, (*37)
composer tests
TODO
- [ ] Add new feature
- [ ] Improve tests
- [ ] Improve documentation
- [ ] Improve English translation in the README file
- [ ] Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)
Changelog
Detailed changes for each release are documented in the
release notes., (*38)
Contribution
Please make sure to read the Contributing Guide, before making a pull
request, start a discussion or report a issue., (*39)
Thanks to all contributors! :heart:, (*40)
If this project helps you to reduce your development time,
you can sponsor me to support my open source work :blush:, (*41)
License
This repository is licensed under the MIT License., (*42)
Copyright © 2016-present, Josantonius, (*43)
Wallogit.com
Josantonius