http_cookie_monster

CookieMonster

CookieMonster is a Ruby library to work with HTTP Cookies. It allows to parse cookies from a HTTP header into an object and to convert the object back to a cookie string or response header.

Installation

Add this line to your application's Gemfile:

gem 'http_cookie_monster'

And then execute:

$ bundle

Or install it yourself as:

$ gem install http_cookie_monster

Usage

# include the gem into your code
#
require 'cookie_monster'

# a new cookie-monster object
#
cookie = CookieMonster.new

# a new cookie-monster object with initial attributes
#
cookie = CookieMonster.new({ :name => 'cookiename', :value => 'cookievalue', :httponly => true })

# a new cookie-monster object from a raw cookie HTTP request header
#
cookie = CookieMonster.new 'Cookie: name=value; domain=.domain.com; path=/; httponly'

# a new cookie-monster object from a cookie string
#
cookie = CookieMonster.new 'name=value; domain=.domain.com; path=/; httponly; secure'

#
# please note:
#
# name and value will be automatically URL decoded when parsed 
# and automatically URL encoded when being set
#

# the following cookie attributes can be set
#
cookie.name     = 'myShinyCookie'          # the name will be URL encoded
cookie.value    = 'test|123|zyx'           # the value will be URL encoded as well
cookie.path     = '/'
cookie.domain   = '.my.domain.com'
cookie.expires  = Time.now + 7*86400       # must be a Time object
cookie.httponly = true
cookie.secure   = true

# the attributes can be accessed like this
#
puts cookie.name
puts cookie.value
puts cookie.path
puts cookie.domain
puts cookie.expires
puts cookie.httponly
puts cookie.secure

# there are some helper methods available
#

# is_valid? does some basic checks: is the cookie name set and is the expiry a Time object (if it's defined)
if cookie.is_valid?
  puts ":-)"
else
  puts ":-("
end

# runs the validation and throws exceptions
#
cookie.validate!

# sets the cookie expiry
#
cookie.expires_in_seconds(60)      # in 60 seconds
cookie.expires_in_seconds(3600)    # in 1 hour
cookie.expires_in_seconds(86400)   # in 1 day
cookie.expires_in_seconds(-60)     # expires the cookie

# expire cookies
#
cookie.expire!      # sets the expire date to a date in the past
cookie.delete!      # removes the cookie value

# export the cookie object - runs validate! and throws a RuntimeError exception if the cookie is invalid!
#
cookie.to_s         # convert to a string
cookie.to_header    # convert to a HTTP response header

# ... so this would be better
#
begin
  puts cookie.to_header
rescue => ex
  puts "Failed to generate cookie: #{ex}"
end

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hirschnase/CookieMonster.

License

The gem is available as open source under the terms of the MIT License.