1 module ActionController
#:nodoc:
2 # Cookies are read and written through ActionController#cookies.
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.
8 # Examples for writing:
10 # # Sets a simple session cookie.
11 # cookies[:user_name] = "david"
13 # # Sets a cookie that expires in 1 hour.
14 # cookies[:login] = { :value => "XJ-122", :expires => 1.hour.from_now }
16 # Examples for reading:
18 # cookies[:user_name] # => "david"
21 # Example for deleting:
23 # cookies.delete :user_name
25 # Please note that if you specify a :domain when setting a cookie, you must also specify the domain when deleting the cookie:
28 # :value => 'a yummy cookie',
29 # :expires => 1.year.from_now,
30 # :domain => 'domain.com'
33 # cookies.delete(:key, :domain => 'domain.com')
35 # The option symbols for setting cookies are:
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
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.
44 # * <tt>:http_only</tt> - Whether this cookie is accessible via scripting or
45 # only HTTP. Defaults to +false+.
47 def self.included(base
)
48 base
.helper_method
:cookies
52 # Returns the cookie container, which operates as described above.
58 class CookieJar
< Hash
#:nodoc:
59 def initialize(controller
)
60 @controller, @cookies = controller
, controller
.request
.cookies
65 # Returns the value of the cookie by +name+, or +nil+ if no such cookie exists.
67 cookie
= @cookies[name
.to_s
]
68 if cookie
&& cookie
.respond_to
?(:value)
69 cookie
.size
> 1 ? cookie
.value
: cookie
.value
[0]
73 # Sets the cookie named +name+. The second argument may be the very cookie
74 # value, or a hash of options as documented above.
75 def []=(name
, options
)
76 if options
.is_a
?(Hash
)
77 options
= options
.inject({}) { |options
, pair
| options
[pair
.first
.to_s
] = pair
.last
; options
}
78 options
["name"] = name
.to_s
80 options
= { "name" => name
.to_s
, "value" => options
}
86 # Removes the cookie on the client machine by setting the value to an empty string
87 # and setting its expiration date into the past. Like <tt>[]=</tt>, you can pass in
88 # an options hash to delete cookies with extra data such as a <tt>:path</tt>.
89 def delete(name
, options
= {})
90 options
.stringify_keys
!
91 set_cookie(options
.merge("name" => name
.to_s
, "value" => "", "expires" => Time
.at(0)))
95 # Builds a CGI::Cookie object and adds the cookie to the response headers.
97 # The path of the cookie defaults to "/" if there's none in +options+, and
98 # everything is passed to the CGI::Cookie constructor.
99 def set_cookie(options
) #:doc:
100 options
["path"] = "/" unless options
["path"]
101 cookie
= CGI
::Cookie.new(options
)
102 @controller.logger
.info
"Cookie set: #{cookie}" unless @controller.logger
.nil?
103 @controller.response
.headers
["cookie"] << cookie