vendor/rails/actionpack/lib/action_controller/cookies.rb

   1 module ActionController #:nodoc:
   2   # Cookies are read and written through ActionController#cookies.
   3   #
   4   # The cookies being read are the ones received along with the request, the cookies
   5   # being written will be sent out with the response. Reading a cookie does not get
   6   # the cookie object itself back, just the value it holds.
   7   #
   8   # Examples for writing:
   9   #
  10   #   # Sets a simple session cookie.
  11   #   cookies[:user_name] = "david"
  12   #
  13   #   # Sets a cookie that expires in 1 hour.
  14   #   cookies[:login] = { :value => "XJ-122", :expires => 1.hour.from_now }
  15   #
  16   # Examples for reading:
  17   #
  18   #   cookies[:user_name] # => "david"
  19   #   cookies.size        # => 2
  20   #
  21   # Example for deleting:
  22   #
  23   #   cookies.delete :user_name
  24   #
  25   # Please note that if you specify a :domain when setting a cookie, you must also specify the domain when deleting the cookie:
  26   #
  27   #  cookies[:key] = {
  28   #    :value => 'a yummy cookie',
  29   #    :expires => 1.year.from_now,
  30   #    :domain => 'domain.com'
  31   #  }
  32   #
  33   #  cookies.delete(:key, :domain => 'domain.com')
  34   #
  35   # The option symbols for setting cookies are:
  36   #
  37   # * <tt>:value</tt> - The cookie's value or list of values (as an array).
  38   # * <tt>:path</tt> - The path for which this cookie applies.  Defaults to the root
  39   #   of the application.
  40   # * <tt>:domain</tt> - The domain for which this cookie applies.
  41   # * <tt>:expires</tt> - The time at which this cookie expires, as a Time object.
  42   # * <tt>:secure</tt> - Whether this cookie is a only transmitted to HTTPS servers.
  43   #   Default is +false+.
  44   # * <tt>:httponly</tt> - Whether this cookie is accessible via scripting or
  45   #   only HTTP. Defaults to +false+.
  46   module Cookies
  47     def self.included(base)
  48       base.helper_method :cookies
  49     end
  50
  51     protected
  52       # Returns the cookie container, which operates as described above.
  53       def cookies
  54         CookieJar.new(self)
  55       end
  56   end
  57
  58   class CookieJar < Hash #:nodoc:
  59     def initialize(controller)
  60       @controller, @cookies = controller, controller.request.cookies
  61       super()
  62       update(@cookies)
  63     end
  64
  65     # Returns the value of the cookie by +name+, or +nil+ if no such cookie exists.
  66     def [](name)
  67       super(name.to_s)
  68     end
  69
  70     # Sets the cookie named +name+. The second argument may be the very cookie
  71     # value, or a hash of options as documented above.
  72     def []=(key, options)
  73       if options.is_a?(Hash)
  74         options.symbolize_keys!
  75       else
  76         options = { :value => options }
  77       end
  78
  79       options[:path] = "/" unless options.has_key?(:path)
  80       super(key.to_s, options[:value])
  81       @controller.response.set_cookie(key, options)
  82     end
  83
  84     # Removes the cookie on the client machine by setting the value to an empty string
  85     # and setting its expiration date into the past. Like <tt>[]=</tt>, you can pass in
  86     # an options hash to delete cookies with extra data such as a <tt>:path</tt>.
  87     def delete(key, options = {})
  88       options.symbolize_keys!
  89       options[:path] = "/" unless options.has_key?(:path)
  90       super(key.to_s)
  91       @controller.response.delete_cookie(key, options)
  92     end
  93   end
  94 end