Requests 2.0.0 API

Cookie
in package

Cookie storage object

Table of Contents

$attributes  : CaseInsensitiveDictionary|array<string|int, mixed>
Cookie attributes
$flags  : array<string|int, mixed>
Cookie flags
$name  : string
Cookie name.
$reference_time  : int
Reference time for relative calculations
$value  : string
Cookie value.
__construct()  : mixed
Create a new cookie object
__toString()  : mixed
Get the cookie value
domain_matches()  : bool
Check if a cookie is valid for a given domain
format_for_header()  : string
Format a cookie for a Cookie header
format_for_set_cookie()  : string
Format a cookie for a Set-Cookie header
is_expired()  : bool
Check if a cookie is expired.
normalize()  : bool
Normalize cookie and attributes
parse()  : Cookie
Parse a cookie string into a cookie object
parse_from_headers()  : array<string|int, mixed>
Parse all Set-Cookie headers from request headers
path_matches()  : bool
Check if a cookie is valid for a given path
uri_matches()  : bool
Check if a cookie is valid for a given URI
normalize_attribute()  : mixed
Parse an individual cookie attribute

Properties

$attributes

Cookie attributes

public CaseInsensitiveDictionary|array<string|int, mixed> $attributes = []

Valid keys are (currently) path, domain, expires, max-age, secure and httponly.

Array-like object

$flags

Cookie flags

public array<string|int, mixed> $flags = []

Valid keys are (currently) creation, last-access, persistent and host-only.

$name

Cookie name.

public string $name

$reference_time

Reference time for relative calculations

public int $reference_time = 0

This is used in place of time() when calculating Max-Age expiration and checking time validity.

$value

Cookie value.

public string $value

Methods

__construct()

Create a new cookie object

public __construct(string $name, string $value[, array<string|int, mixed>|CaseInsensitiveDictionary $attributes = [] ][, array<string|int, mixed> $flags = [] ][, int|null $reference_time = null ]) : mixed
Parameters
$name : string
$value : string
$attributes : array<string|int, mixed>|CaseInsensitiveDictionary = []

Associative array of attribute data

$flags : array<string|int, mixed> = []
$reference_time : int|null = null
Tags
throws
InvalidArgument

When the passed $name argument is not a string.

throws
InvalidArgument

When the passed $value argument is not a string.

throws
InvalidArgument

When the passed $attributes argument is not an array or iterable object with array access.

throws
InvalidArgument

When the passed $flags argument is not an array.

throws
InvalidArgument

When the passed $reference_time argument is not an integer or null.

Return values
mixed

__toString()

Get the cookie value

public __toString() : mixed

Attributes and other data can be accessed via methods.

Return values
mixed

domain_matches()

Check if a cookie is valid for a given domain

public domain_matches(string $domain) : bool
Parameters
$domain : string

Domain to check

Return values
bool

Whether the cookie is valid for the given domain

format_for_header()

Format a cookie for a Cookie header

public format_for_header() : string

This is used when sending cookies to a server.

Return values
string

Cookie formatted for Cookie header

Format a cookie for a Set-Cookie header

public format_for_set_cookie() : string

This is used when sending cookies to clients. This isn't really applicable to client-side usage, but might be handy for debugging.

Return values
string

Cookie formatted for Set-Cookie header

is_expired()

Check if a cookie is expired.

public is_expired() : bool

Checks the age against $this->reference_time to determine if the cookie is expired.

Return values
bool

True if expired, false if time is valid.

normalize()

Normalize cookie and attributes

public normalize() : bool
Return values
bool

Whether the cookie was successfully normalized

parse()

Parse a cookie string into a cookie object

public static parse(string $cookie_header[, string $name = '' ][, int|null $reference_time = null ]) : Cookie

Based on Mozilla's parsing code in Firefox and related projects, which is an intentional deviation from RFC 2109 and RFC 2616. RFC 6265 specifies some of this handling, but not in a thorough manner.

Parameters
$cookie_header : string

Cookie header value (from a Set-Cookie header)

$name : string = ''
$reference_time : int|null = null
Tags
throws
InvalidArgument

When the passed $cookie_header argument is not a string.

throws
InvalidArgument

When the passed $name argument is not a string.

Return values
Cookie

Parsed cookie object

parse_from_headers()

Parse all Set-Cookie headers from request headers

public static parse_from_headers(Headers $headers[, Iri|null $origin = null ][, int|null $time = null ]) : array<string|int, mixed>
Parameters
$headers : Headers

Headers to parse from

$origin : Iri|null = null

URI for comparing cookie origins

$time : int|null = null

Reference time for expiration calculation

Return values
array<string|int, mixed>

path_matches()

Check if a cookie is valid for a given path

public path_matches(string $request_path) : bool

From the path-match check in RFC 6265 section 5.1.4

Parameters
$request_path : string

Path to check

Return values
bool

Whether the cookie is valid for the given path

uri_matches()

Check if a cookie is valid for a given URI

public uri_matches(Iri $uri) : bool
Parameters
$uri : Iri

URI to check

Return values
bool

Whether the cookie is valid for the given URI

normalize_attribute()

Parse an individual cookie attribute

protected normalize_attribute(string $name, string|bool $value) : mixed

Handles parsing individual attributes from the cookie values.

Parameters
$name : string

Attribute name

$value : string|bool

Attribute value (string value, or true if empty/flag)

Return values
mixed

Value if available, or null if the attribute value is invalid (and should be skipped)

Search results