browser-cookies v1.2.0

browser-cookies

Tiny cookies library for the browser

• Features
• Browser compatibility
• Installation
• Usage
• API
• Options
• Examples
• How to use with PHP

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:

Or run the unit tests right now in your current browser.

Installation

Using NPM
npm install browser-cookies

Using Bower
bower install browser-cookies

Usage

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 examples

API

API contents:

• method cookies.set(name, value [, options])
• method cookies.get(name)
• method cookies.erase(name, [, options])
• method cookies.all()
• property cookies.defaults

cookies.set(name, value [, options]) Method to save a cookie.

cookies.get(name) Method that returns a cookie value, or null if the cookie is not found. Percent encoded values will automatically be decoded.

cookies.erase(name [, options ]) Method to remove a cookie.

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.

Examples

Count the number of a visits to a page:

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:

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:

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

The cookies.all method can be used for more advanced functionality, for example to erase all cookies except one:

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() instead of setcookie() to prevent PHP from replacing spaces with + characters:

// Set cookie
setrawcookie('fullName', rawurlencode('Lisa Cuddy'));

// Get cookie
$_COOKIE['fullName'];

Development

The design goal is to provide the smallest possible size (when minified and gzipped) for the given API while remaining compliant to RFC6265 and providing cross-browser compatibility and consistency.

Development setup (requires node and git to be installed):

git clone https://github.com/voltace/browser-cookies.git
cd browser-cookies
npm install         # Install dev dependencies
npm run test:local  # Run unit tests locally (takes ~5 seconds)
npm run build       # Create minified version

Feel free to submit an issue on GitHub for any question, bug or feature requesst you may have.

License

Public Domain (UNLICENSE)