# class HTTP::Cookie

- HTTP::Cookie
- Reference
- Object

##
Overview

Represents a cookie with all its attributes. Provides convenient access and modification of them.

NOTE To use `Cookie`, you must explicitly import it with `require "http/cookie"`

##
Defined in:

http/cookie.cr

##
Constructors

- .new(name : String, value : String, path : String | Nil = nil, expires : Time | Nil = nil, domain : String | Nil = nil, secure : Bool | Nil = nil, http_only : Bool = false, samesite : SameSite | Nil = nil, extension : String | Nil = nil, max_age : Time::Span | Nil = nil, creation_time : Time = Time.utc)

  Creates a new `Cookie` instance.

##
Instance Method Summary

- #==(other : self)

  Returns `true` if this reference is the same as other.

- #creation_time : Time
- #domain : String | Nil
- #domain=(domain : String | Nil)
- #expiration_time : Time | Nil

  Returns the expiration time of this cookie.

- #expire

  Expires the cookie.

- #expired?(time_reference = Time.utc) : Bool

  Returns the expiration status of this cookie as a `Bool`.

- #expires : Time | Nil
- #expires=(expires : Time | Nil)
- #extension : String | Nil
- #extension=(extension : String | Nil)
- #hash(hasher)

  See `Object#hash(hasher)`

- #http_only : Bool
- #http_only=(http_only : Bool)
- #inspect(io : IO) : Nil

  Returns an unambiguous string representation of this cookie.

- #max_age : Time::Span | Nil
- #max_age=(max_age : Time::Span | Nil)
- #name : String
- #name=(name : String)

  Sets the name of this cookie.

- #path : String | Nil
- #path=(path : String | Nil)
- #samesite : SameSite | Nil
- #samesite=(samesite : SameSite | Nil)
- #secure : Bool

  Returns `true` if this cookie has the Secure flag.

- #secure=(secure : Bool) : Bool
- #to_cookie_header(io) : Nil

  Returns a string representation of this cookie in the format used by the `Cookie` header of an HTTP request.

- #to_cookie_header : String

  Returns a string representation of this cookie in the format used by the `Cookie` header of an HTTP request.

- #to_s(io : IO) : Nil

  Returns a string representation of this cookie.

- #to_set_cookie_header(io : IO) : Nil

  Returns a string representation of this cookie in the format used by the `Set-Cookie` header of an HTTP response.

- #to_set_cookie_header : String

  Returns a string representation of this cookie in the format used by the `Set-Cookie` header of an HTTP response.

- #valid? : Bool

  Returns `false` if `#name` has a security prefix but the requirements are not met as per RFC 6265 bis §4.1.3, otherwise returns `true`.

- #validate! : self

  Raises `ArgumentError` if `self` is not `#valid?`.

- #value : String
- #value=(value : String)

  Sets the value of this cookie.

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

### Class methods inherited from class `Reference`

pre_initialize(address : Pointer) pre_initialize

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Constructor Detail

def self.new(name : String, value : String, path : String | Nil = nil, expires : Time | Nil = nil, domain : String | Nil = nil, secure : Bool | Nil = nil, http_only : Bool = false, samesite : SameSite | Nil = nil, extension : String | Nil = nil, max_age : Time::Span | Nil = nil, creation_time : Time = Time.utc) #

Creates a new `Cookie` instance.

Raises `IO::Error` if name or value are invalid as per RFC 6265 §4.1.1. Raises `ArgumentError` if name has a security prefix but the requirements are not met as per RFC 6265 bis §4.1.3. Alternatively, if name has a security prefix, and the related properties are `nil`, the prefix will automatically be applied to the cookie.

##
Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns `true` if this reference is the same as other. Invokes `same?`.

def creation_time : Time #
def domain : String | Nil #
def domain=(domain : String | Nil) #
def expiration_time : Time | Nil #

Returns the expiration time of this cookie.

def expire #

Expires the cookie.

Causes the cookie to be destroyed. Sets the value to the empty string and expires its lifetime.

    cookie = HTTP::Cookie.new("hello", "world")
    cookie.expire

    cookie.value    # => ""
    cookie.expired? # => true

def expired?(time_reference = Time.utc) : Bool #

Returns the expiration status of this cookie as a `Bool`.

time_reference can be passed to use a different reference time for comparison. Default is the current time (`Time.utc`).

def expires : Time | Nil #
def expires=(expires : Time | Nil) #
def extension : String | Nil #
def extension=(extension : String | Nil) #
def hash(hasher) #
Description copied from class Reference

See `Object#hash(hasher)`

def http_only : Bool #
def http_only=(http_only : Bool) #
def inspect(io : IO) : Nil #

Returns an unambiguous string representation of this cookie.

It uses the `Set-Cookie` serialization from `#to_set_cookie_header` which represents the full state of the cookie.

    HTTP::Cookie.new("foo", "bar").inspect                        # => HTTP::Cookie["foo=bar"]
    HTTP::Cookie.new("foo", "bar", domain: "example.com").inspect # => HTTP::Cookie["foo=bar; domain=example.com"]

def max_age : Time::Span | Nil #
def max_age=(max_age : Time::Span | Nil) #
def name : String #
def name=(name : String) #

Sets the name of this cookie.

Raises `IO::Error` if the value is invalid as per RFC 6265 §4.1.1.

def path : String | Nil #
def path=(path : String | Nil) #
def samesite : SameSite | Nil #
def samesite=(samesite : SameSite | Nil) #
def secure : Bool #

Returns `true` if this cookie has the Secure flag.

def secure=(secure : Bool) : Bool #
def to_cookie_header(io) : Nil #

Returns a string representation of this cookie in the format used by the `Cookie` header of an HTTP request. This includes only the `#name` and `#value`. All other attributes are left out.

    HTTP::Cookie.new("foo", "bar").to_cookie_header                        # => "foo=bar"
    HTTP::Cookie.new("foo", "bar", domain: "example.com").to_cookie_header # => "foo=bar

def to_cookie_header : String #

Returns a string representation of this cookie in the format used by the `Cookie` header of an HTTP request. This includes only the `#name` and `#value`. All other attributes are left out.

    HTTP::Cookie.new("foo", "bar").to_cookie_header                        # => "foo=bar"
    HTTP::Cookie.new("foo", "bar", domain: "example.com").to_cookie_header # => "foo=bar

def to_s(io : IO) : Nil #

Returns a string representation of this cookie.

It uses the `Set-Cookie` serialization from `#to_set_cookie_header` which represents the full state of the cookie.

    HTTP::Cookie.new("foo", "bar").to_s                        # => "foo=bar"
    HTTP::Cookie.new("foo", "bar", domain: "example.com").to_s # => "foo=bar; domain=example.com"

def to_set_cookie_header(io : IO) : Nil #

Returns a string representation of this cookie in the format used by the `Set-Cookie` header of an HTTP response.

    HTTP::Cookie.new("foo", "bar").to_set_cookie_header                        # => "foo=bar"
    HTTP::Cookie.new("foo", "bar", domain: "example.com").to_set_cookie_header # => "foo=bar; domain=example.com"

def to_set_cookie_header : String #

Returns a string representation of this cookie in the format used by the `Set-Cookie` header of an HTTP response.

    HTTP::Cookie.new("foo", "bar").to_set_cookie_header                        # => "foo=bar"
    HTTP::Cookie.new("foo", "bar", domain: "example.com").to_set_cookie_header # => "foo=bar; domain=example.com"

def valid? : Bool #

Returns `false` if `#name` has a security prefix but the requirements are not met as per RFC 6265 bis §4.1.3, otherwise returns `true`.

def validate! : self #

Raises `ArgumentError` if `self` is not `#valid?`.

def value : String #
def value=(value : String) #

Sets the value of this cookie.

Raises `IO::Error` if the value is invalid as per RFC 6265 §4.1.1.