browser-cookies
Tiny cookies library for the browser
!NPM Versionnpm-version-imagenpm-url
!NPM Downloadsnpm-downloads-imagenpm-url
!Build Statustravis-imagetravis-url
!Coveralls Statuscoveralls-imagecoveralls-url
Features
- Clean and easy to use API
- Small footprint (minified and gzipped ~ 0.5kB)
- No dependencies
- RFC6265 compliant
- Cross browser support
- Supports CommonJS (e.g. Browserify)
Browser compatibility
Cross browser support is verified on real browsers using automated testing: !Sauce Test Statussaucelabs-imagesaucelabs-url Or run the unit testsref-unittests right now in your current browser.Installation
Using NPMnpm install browser-cookies
Using Bower
bower install browser-cookies
Usage
```javascript var cookies = require('browser-cookies'); cookies.set('firstName', 'Lisa'); cookies.set('firstName', 'Lisa', {expires: 365}); // Expires after 1 year cookies.set('firstName', 'Lisa', {secure: true, domain: 'www.example.org'}); cookies.get('firstName'); // Returns cookie value (or null) cookies.erase('firstName'); // Removes cookie ``` More examplesAPI
API contents:- method cookies.get(
name)
- method cookies.all()
- property cookies.defaults
cookies.set(
name, value [, options])
Method to save a cookie. | argument | type | description |---------------|--------|------------ |
name | string | The name of the cookie to save.
| value | string | The value to save, percent encodingref-percent-encoding will automatically be applied.
| options | object | May contain any of the properties specified in options below. If an option is not specified, the value configured in cookies.defaults will be used.
cookies.get(
name)
Method that returns a cookie value, or null if the cookie is not found. Percent encodedref-percent-encoding values will automatically be decoded. | argument | type | description |---------------|--------|------------ |
name | string | The name of the cookie to retrieve.
cookies.erase(
name [, options ])
Method to remove a cookie. | argument | type | description |---------------|--------|------------ |
name | string | The name of the cookie to remove.
| options | object | May contain the domain and path properties specified in options below. If an option is not specified, the value configured in cookies.defaults will be used.
cookies.all()
Method to get all cookies. Returns an object containing all cookie values with the cookie names used as keys. Percent encoded names and values will automatically be decoded.
cookies.defaults
This object may be used to change the default value of each option specified in options below.
Options
The options shown in the table below may be set globally using cookies.defaults or passed as function argument to cookies.set() and cookies.erase(). Also check out the Examples further below. | Name | Type | Default | Description |------------|----------------------------|---------|-------- |expires | Number, Date, String | 0 | Configure when the cookie expires by using one of the following types as value:- A
Numberof days until the cookie expires. If set to0the cookie will expire at the end of the session. - A
Dateobject such asnew Date(2018, 3, 27). - A
Stringin a format recognized by Date.parse()ref-date-parse.
domain | String | "" | The domainref-cookie-domain from where the cookie is readable.- If set to
""the current domain will be used.
path | String | "/" | The path from where the cookie is readable.- The default value of
"/"allows the cookie to be readable from all paths. - If set to
""the cookie will only be readable from the current browser path. - Note that cookies don't support relative paths such as
"../../some/path"so paths must be absolute like"/some/path".
secure | Boolean | false | If true the cookie will only be transmitted over secure protocols like https.
| httponly | Boolean | false | If true the cookie may only be read by the web server.- This option may be set to prevent malicious scripts from accessing cookiesref-httponly, not all browsers support this feature yet.
samesite | String | "" | The samesite argument may be used to prevent cookies from being sent along with cross-site requestsref-samesite.- If set to
""the SameSite feature will not be used. - If set to
"Strict"the cookie will only be sent along with "same-site" requests. - If set to
"Lax"the cookie will be sent with "same-site" requests and with "cross-site" top-level navigations.
Examples
Count the number of a visits to a page: ```javascript var cookies = require('browser-cookies'); // Get cookie value var visits = cookies.get('count') || 0; console.log("You've been here " + parseInt(visits) + " times before!"); // Increment the counter and set (or update) the cookie cookies.set('count', parseInt(visits) + 1, {expires: 365}); ``` JSON may be saved by converting the JSON object into a string: ```javascript var cookies = require('browser-cookies'); // Store JSON data var user = {firstName: 'Sofia', lastName: 'Dueñas'}; cookies.set('user', JSON.stringify(user)) // Retrieve JSON data var userString = cookies.get('user'); alert('Hi ' + JSON.parse(userString).firstName); ``` The default cookie options may be changed: ```javascript var cookies = require('browser-cookies'); // Override defaults cookies.defaults.secure = true; cookies.defaults.expires = 7; // 'secure' option enabled and cookie expires in 7 days cookies.set('FirstName', 'John') // 'secure' option enabled and cookie expires in 30 days cookies.set('LastName', 'Smith', {expires: 30}) ``` Thecookies.all method can be used for more advanced functionality, for example to erase all cookies except one:
```javascript
var cookies = require('browser-cookies');
var cookieToKeep = 'FirstName'; // Name of the cookie to keep
// Get all cookies as an object
var allCookies = cookies.all();
// Iterate over all cookie names
for (var cookieName in allCookies) {
// Erase the cookie (except if it's the cookie that needs to be kept)
if(allCookies.hasOwnProperty(cookieName) && cookieName != cookieToKeep) {
cookies.erase(cookieName);How to use with PHP
Use setrawcookie()ref-php-setrawcookie instead ofsetcookie() to prevent PHP from replacing spaces with + characters:
```php
// Set cookie
setrawcookie('fullName', rawurlencode('Lisa Cuddy'));
// Get cookie
$COOKIE'fullName';
```
