Cookie
view release on metacpan or search on metacpan
}
- `debug`
Optional. If set with a positive integer, this will activate verbose debugging message
## add
Provided with an hash or hash reference of cookie parameters (see [Cookie](https://metacpan.org/pod/Cookie)) and this will create a new [cookie](https://metacpan.org/pod/Cookie) and add it to the cookie repository.
Alternatively, you can also provide directly an existing [cookie object](https://metacpan.org/pod/Cookie)
my $c = $jar->add( $cookie_object ) || die( $jar->error );
## add\_cookie\_header
This is an alias for ["add\_request\_header"](#add_request_header) for backward compatibility with [HTTP::Cookies](https://metacpan.org/pod/HTTP%3A%3ACookies)
## add\_request\_header
Provided with a request object, such as, but not limited to [HTTP::Request](https://metacpan.org/pod/HTTP%3A%3ARequest) and this will add all relevant cookies in the repository into the `Cookie` http request header. The object method needs to have th...
As long as the object provided supports the `uri` and `header` method, you can provide any class of object you want.
Please refer to the [rfc6265](https://datatracker.ietf.org/doc/html/rfc6265) for more information on the applicable rule when adding cookies to the outgoing request header.
Basically, it will add, for a given domain, first all cookies whose path is longest and at path equivalent, the cookie creation date is used, with the earliest first. Cookies who have expired are not sent, and there can be cookies bearing the same na...
## add\_response\_header
# Adding cookie to the repository
$jar->add(
name => 'session',
value => 'lang=en-GB',
path => '/',
secure => 1,
same_site => 'Lax',
) || die( $jar->error );
# then placing it onto the response header
$jar->add_response_header;
This is the alter ego to ["add\_request\_header"](#add_request_header), in that it performs the equivalent function, but for the server side.
You can optionally provide, as unique argument, an object, such as but not limited to, [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse), as long as that class supports the `header` method
Alternatively, if an [Apache object](https://metacpan.org/pod/Apache2%3A%3ARequestRec) has been set upon object instantiation or later using the ["request"](#request) method, then it will be used to set the outgoing `Set-Cookie` headers (there is one...
If no response, nor Apache2 object were set, then this will simply return a list of `Set-Cookie` in list context, or a string of possibly multiline `Set-Cookie` headers, or an empty string if there is no cookie found to be sent.
Be careful not to do the following:
# get cookies sent by the http client
$jar->fetch || die( $jar->error );
# set the response headers with the cookies from our repository
$jar->add_response_header;
Why? Well, because ["fetch"](#fetch) retrieves the cookies sent by the http client and store them into the repository. However, cookies sent by the http client only contain the cookie name and value, such as:
GET /my/path/ HTTP/1.1
Host: www.example.org
Cookie: session_token=eyJleHAiOjE2MzYwNzEwMzksImFsZyI6IkhTMjU2In0.eyJqdGkiOiJkMDg2Zjk0OS1mYWJmLTRiMzgtOTE1ZC1hMDJkNzM0Y2ZmNzAiLCJmaXJzdF9uYW1lIjoiSm9obiIsImlhdCI6MTYzNTk4NDYzOSwiYXpwIjoiNGQ0YWFiYWQtYmJiMy00ODgwLThlM2ItNTA0OWMwZTczNjBlIiwiaXNzIjoi...
As you can see, 3 cookies were sent: `session_token`, `csrf_token` and `site_prefs`
So, when ["fetch"](#fetch) creates an object for each one and store them, those cookies have no `path` value and no other attribute, and when ["add\_response\_header"](#add_response_header) is then called, it stringifies the cookies and create a `Set...
The http client, when receiving those cookies will derive the missing cookie path to be `/my/path`, i.e. the current uri path, and will create a duplicate cookie from the previously stored cookie with the same name for that host, but that had the pa...
So you can create a repository and use it to store the cookies sent by the http client using ["fetch"](#fetch), but in preparation of the server response, either use a separate repository with, for example, `my $jar_out = Cookie::Jar->new` or use ["s...
# Add Set-Cookie header for that cookie, but do not add cookie to repository
$jar->set( $cookie_object );
## algo
String. Sets or gets the algorithm to use when loading or saving the cookie jar.
## autosave
Boolean. Sets or gets the boolean value for automatically saving the cookie jar to the given file specified with ["file"](#file)
## delete
Given a cookie name, an optional host and optional path or a [Cookie](https://metacpan.org/pod/Cookie) object, and this will remove it from the cookie repository.
It returns an [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) upon success, or ["undef" in perlfunc](https://metacpan.org/pod/perlfunc#undef) and sets an [error](https://metacpan.org/pod/Module%3A%3AGeneric#error). Note that t...
However, this will NOT remove it from the web browser by sending a Set-Cookie header. For that, you might want to look at the ["elapse" in Cookie](https://metacpan.org/pod/Cookie#elapse) method.
It returns an [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) of cookie objects removed.
my $arr = $jar->delete( 'my-cookie' );
# alternatively
my $arr = $jar->delete( 'my-cookie' => 'www.example.org' );
# or
my $arr = $jar->delete( $my_cookie_object );
printf( "%d cookie(s) removed.\n", $arr->length );
print( "Cookie value removed was: ", $arr->first->value, "\n" );
If you are interested in telling the http client to remove all your cookies, you can set the `Clear-Site-Data` header:
Clear-Site-Data: "cookies"
You can instruct the http client to remove other data like local storage:
Clear-Site-Data: "cookies", "cache", "storage", "executionContexts"
Although this is widely supported, there is no guarantee the http client will actually comply with this request.
See [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Clear-Site-Data) for more information.
## do
Provided with an anonymous code or reference to a subroutine, and this will call that code for every cookie in the repository, passing it the cookie object as the sole argument. Also, that cookie object is accessible using `$_`.
If the code return `undef`, it will end the loop, and if the code returns true, this will have the current cookie object added to an [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) returned upon completion of the loop.
my $found = $jar->do(sub
{
# Part of the path
if( index( $path, $_->path ) == 0 )
{
return(1);
print( "Found cookies: ", $found->map(sub{$_->name})->join( ',' ), "\n" );
## encrypt
Boolean. Sets or gets the boolean value for whether to encrypt or not the cookie jar when saving it, or whether to decrypt it when loading cookies from it.
This defaults to false.
## exists
Given a cookie name, this will check if it exists.
It returns 1 if it does, or 0 if it does not.
## extract
Provided with a response object, such as, but not limited to [HTTP::Response](https://metacpan.org/pod/HTTP%3A%3AResponse), and this will retrieve any cookie sent from the remote server, parse them and add their respective to the repository.
As per the [rfc6265, section 5.3.11 specifications](https://datatracker.ietf.org/doc/html/rfc6265#section-5.3) if there are duplicate cookies for the same domain and path, only the last one will be retained.
If the cookie received does not contain any `Domain` specification, then, in line with rfc6265 specifications, it will take the root of the current domain as the default domain value. Since finding out what is the root for a domain name is a non-triv...
## extract\_cookies
This is an alias for ["extract"](#extract) for backward compatibility with [HTTP::Cookies](https://metacpan.org/pod/HTTP%3A%3ACookies)
## extract\_one
This method takes a cookie string, which can be found in the `Set-Cookie` header, parse it, and returns a [Cookie](https://metacpan.org/pod/Cookie) object if successful, or sets an [error](https://metacpan.org/pod/Module%3A%3AGeneric#error) and retur...
It also takes an hash or hash reference of options.
The following options are supported:
- `host`
If provided, it will be used to find out the host's root domain, and to set the cookie object `domain` property if none is specified in the cookie string.
- `path`
If provided, it will be used to set the cookie object `path` property.
- `port`
If provided, it will be used to set the cookie object `port` property.
## fetch
This method does the equivalent of ["extract"](#extract), but for the server.
It retrieves all possible cookies from the http request received from the web browser.
It takes an optional hash or hash reference of parameters, such as `host`. If it is not provided, the value set with ["host"](#host) is used instead.
If the parameter `request` containing an http request object, such as, but not limited to [HTTP::Request](https://metacpan.org/pod/HTTP%3A%3ARequest), is provided, it will use it to get the `Cookie` header value. The object method needs to have the `...
Alternatively, if a value for ["request"](#request) has been set, it will use it to get the `Cookie` header value from Apache modperl.
You can also provide the `Cookie` string to parse by providing the `string` option to this method.
$jar->fetch( string => q{foo=bar; site_prefs=lang%3Den-GB} ) ||
die( $jar->error );
Ultimately, if none of those are available, it will use the environment variable `HTTP_COOKIE`
If the option `store` is true (by default it is true), this method will add the fetched cookies to the [repository](#repo).
It returns an hash reference of cookie key => [cookie object](https://metacpan.org/pod/Cookie)
A cookie key is made of the host (possibly empty), the path and the cookie name separated by `;`
# Cookies added to the repository
$jar->fetch || die( $jar->error );
# Cookies returned, but NOT added to the repository
my $cookies = $jar->fetch || die( $jar->error );
## file
Sets or gets the file path to the cookie jar file.
If provided upon instantiation, and if the file exists on the filesystem and is not empty, `Cookie::Jar` will load all the cookies from it.
If ["autosave"](#autosave) is set to a true, `Cookie::Jar` will automatically save all cookies to the specified cookie jar file, possibly encrypting it if ["algo"](#algo) and ["secret"](#secret) are set.
## get
Given a cookie name, an optional host and an optional path, this will retrieve its corresponding [cookie object](https://metacpan.org/pod/Cookie) and return it.
If not found, it will try to return a value with just the cookie name.
If nothing is found, this will return and empty list in list context or `undef` in scalar context.
You can `get` multiple cookie object and this method will return a list in list context and the first cookie object found in scalar context.
# Wrong, an undefined returned value here only means there is no such cookie
my $c = $jar->get( 'my-cookie' );
die( $jar->error ) if( !defined( $c ) );
# Correct
my $c = $jar->get( 'my-cookie' ) || die( "No cookie my-cookie found\n" );
# Possibly get multiple cookie object for the same name
my @cookies = $jar->get( 'my_same_name' ) || die( "No cookies my_same_name found\n" );
# or
my @cookies = $jar->get( 'my_same_name' => 'www.example.org', '/private' ) || die( "No cookies my_same_name found\n" );
## get\_by\_domain
Provided with a host and an optional hash or hash reference of parameters, and this returns an [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) of [cookie objects](https://metacpan.org/pod/Cookie) matching the domain specified.
If a `sort` parameter has been provided and its value is true, this will sort the cookies by path alphabetically. If the sort value exists, but is false, this will sort the cookies by path but in a reverse alphabetical order.
By default, the cookies are sorted.
## host
Sets or gets the default host. This is especially useful for cookies repository used on the server side.
## key
Provided with a cookie name and an optional host and this returns a key used to add an entry in the hash repository.
If no host is provided, the key is just the cookie, otherwise the resulting key is the cookie name and host separated just by `;`
value => $secret_value,
path => '/',
secure => 1,
http_only => 1,
same_site => 'Lax',
key => Bytes::Random::Secure::random_bytes(32),
algo => $algo,
encrypt => 1,
) || die( $jar->error );
# or as an hash reference of parameters
my $c = $jar->make({
name => 'session',
value => $secret_value,
path => '/',
secure => 1,
http_only => 1,
same_site => 'Lax',
key => Bytes::Random::Secure::random_bytes(32),
algo => $algo,
encrypt => 1,
}) || die( $jar->error );
## merge
Provided with another [Cookie::Jar](https://metacpan.org/pod/Cookie%3A%3AJar) object, or at least an object that supports the ["do"](#do) method, which takes an anonymous code as argument, and that calls that code passing it each cookie object found ...
$jar->merge( $other_jar ) || die( $jar->error );
If the cookie objects passed to the anonymous code in this method, are not [Cookie](https://metacpan.org/pod/Cookie) object, then at least they must support the methods `name`, `value`, `domain`, `path`, `port`, `secure`, `max_age`, `secure`, `same_s...
This method also takes an hash or hash reference of options:
- `die` boolean
If true, the anonymous code passed to the `do` method called, will die upon error. Default to false.
By default, if an error occurs, `undef` is returned and the [error](https://metacpan.org/pod/Module%3A%3AGeneric#error) is set.
- `overwrite` boolean
If true, when an existing cookie is found it will be overwritten by the new one. Default to false.
use Nice::Try;
try
{
$jar->merge( $other_jar, die => 1, overwrite => 1 );
}
catch( $e )
{
die( "Failed to merge cookies repository: $e\n" );
}
Upon success this will return the current object, and if there was an error, this returns ["undef" in perlfunc](https://metacpan.org/pod/perlfunc#undef) and sets an [error](https://metacpan.org/pod/Module%3A%3AGeneric#error)
## parse
This method is used by ["fetch"](#fetch) to parse cookies sent by http client. Parsing is much simpler than for http client receiving cookies from server.
It takes the raw `Cookie` string sent by the http client, and returns an hash reference (possibly empty) of cookie name to cookie value pairs.
my $cookies = $jar->parse( 'foo=bar; site_prefs=lang%3Den-GB' );
# You can safely do as well:
my $cookies = $jar->parse( '' );
## purge
Thise takes no argument and will remove from the repository all cookies that have expired. A cookie that has expired is a [Cookie](https://metacpan.org/pod/Cookie) that has its `expires` property set and whose value is in the past.
This returns an [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) of all the cookies thus removed.
my $all = $jar->purge;
printf( "Cookie(s) removed were: %s\n", $all->map(sub{ $_->name })->join( ',' ) );
# or
printf( "%d cookie(s) removed from our repository.\n", $jar->purge->length );
## replace
Provided with a [Cookie](https://metacpan.org/pod/Cookie) object, and an optional other [Cookie](https://metacpan.org/pod/Cookie) object, and this method will replace the former cookie provided in the second parameter with the new one provided in the...
If only one parameter is provided, the cookies to be replaced will be derived from the replacement cookie's properties, namely: `name`, `domain` and `path`
It returns an [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) of cookie objects replaced upon success, or `undef` and set an [error](https://metacpan.org/pod/Module%3A%3AGeneric#error) upon error.
## repo
Set or get the [array object](https://metacpan.org/pod/Module%3A%3AGeneric%3A%3AArray) used as the cookie jar repository.
printf( "%d cookies found\n", $jar->repo->length );
## request
Set or get the [Apache2::RequestRec](https://metacpan.org/pod/Apache2%3A%3ARequestRec) object. This object is used to set the `Set-Cookie` header within modperl.
## save
$jar->save( '/home/joe/cookies.json' ) ||
die( "Failed to save cookies: ", $jar->error );
# or saving the cookies file encrypted
$jar->save( '/home/joe/cookies_encrypted.json',
{
encrypt => 1,
key => $key,
iv => $iv,
algo => 'AES',
}) || die( $jar->error );
Provided with a file, and an hash or hash reference of options, and this will save the repository of cookies as json data.
The hash saved to file contains 2 top properties: `updated_on` containing the last update date and `cookies` containing an hash of cookie name to cookie properties pairs.
It returns the current object. If an error occurred, it will return `undef` and set an [error](https://metacpan.org/pod/Module%3A%3AGeneric#error)
Supported options are:
- `algo` string
Algorithm to use to encrypt the cookie file.
It can be any of [AES](https://metacpan.org/pod/Crypt%3A%3ACipher%3A%3AAES), [Anubis](https://metacpan.org/pod/Crypt%3A%3ACipher%3A%3AAnubis), [Blowfish](https://metacpan.org/pod/Crypt%3A%3ACipher%3A%3ABlowfish), [CAST5](https://metacpan.org/pod/...
( run in 1.372 second using v1.01-cache-2.11-cpan-8f98c5d2c55 )