1HTTP::CookieMonster(3)User Contributed Perl DocumentationHTTP::CookieMonster(3)
2
3
4

NAME

6       HTTP::CookieMonster - Easy read/write access to your jar of
7       HTTP::Cookies
8

VERSION

10       version 0.11
11

SYNOPSIS

13           # Use the functional interface for quick read-only access
14           use HTTP::CookieMonster qw( cookies );
15           use WWW::Mechanize;
16
17           my $mech = WWW::Mechanize->new;
18           my $url = 'https://www.nytimes.com';
19           $mech->get( $url );
20
21           my @cookies = cookies( $mech->cookie_jar );
22           my $cookie  = cookies( $mech->cookie_jar, 'RMID' );
23           print $cookie->val;
24
25           # Use the OO interface for read/write access
26
27           use HTTP::CookieMonster;
28
29           my $monster = HTTP::CookieMonster->new( $mech->cookie_jar );
30           my $cookie = $monster->get_cookie('RMID');
31           print $cookie->val;
32
33           $cookie->val('random stuff');
34           $monster->set_cookie( $cookie );
35
36           # now fetch page using mangled cookie
37           $mech->get( $url );
38

DESCRIPTION

40       This module was created because messing around with HTTP::Cookies is
41       non-trivial.  HTTP::Cookies a very useful module, but using it is not
42       always as easy and clean as it could be. For instance, if you want to
43       find a particular cookie, you can't just ask for it by name.  Instead,
44       you have to use a callback:
45
46           $cookie_jar->scan( \&callback )
47
48       The callback will be invoked with 11 positional parameters:
49
50           0 version
51           1 key
52           2 val
53           3 path
54           4 domain
55           5 port
56           6 path_spec
57           7 secure
58           8 expires
59           9 discard
60           10 hash
61
62       That's a lot to remember and it doesn't make for very readable code.
63
64       Now, let's say you want to save or update a cookie. Now you're back to
65       the many positional params yet again:
66
67           $cookie_jar->set_cookie( $version, $key, $val, $path, $domain, $port, $path_spec, $secure, $maxage, $discard, \%rest )
68
69       Also not readable. Unless you have an amazing memory, you may find
70       yourself checking the docs regularly to see if you did, in fact, get
71       all those params in the correct order etc.
72
73       HTTP::CookieMonster gives you a simple interface for getting and
74       setting cookies. You can fetch an ARRAY of all your cookies:
75
76           my @all_cookies = $monster->all_cookies;
77           foreach my $cookie ( @all_cookies ) {
78               print $cookie->key;
79               print $cookie->val;
80               print $cookie->secure;
81               print $cookie->domain;
82               # etc
83           }
84
85       Or, if you know for a fact exactly what will be in your cookie jar, you
86       can fetch a cookie by name.
87
88           my $cookie = $monster->get_cookie( 'plack_session' );
89
90       This gives you fast access to a cookie without a callback, iterating
91       over a list etc. It's good for quick hacks and you can dump the cookie
92       quite easily to inspect its contents in a highly readable way:
93
94           use Data::Printer;
95           p $cookie;
96
97       If you want to mangle the cookie before the next request, that's easy
98       too.
99
100           $cookie->val('woohoo');
101           $monster->set_cookie( $cookie );
102           $mech->get( $url );
103
104       Or, add an entirely new cookie to the jar:
105
106           use HTTP::CookieMonster::Cookie;
107           my $cookie = HTTP::CookieMonster::Cookie->new(
108               key       => 'cookie-name',
109               val       => 'cookie-val',
110               path      => '/',
111               domain    => '.somedomain.org',
112               path_spec => 1,
113               secure    => 0,
114               expires   => 1376081877
115           );
116
117           $monster->set_cookie( $cookie );
118           $mech->get( $url );
119
120   new
121       new() takes just one required parameter, which is cookie_jar, a valid
122       HTTP::Cookies object.
123
124           my $monster = HTTP::CookieMonster->new( $mech->cookie_jar );
125
126   cookie_jar
127       A reader which returns an HTTP::Cookies object.
128
129   all_cookies
130       Returns an ARRAY of all cookies in the cookie jar, represented as
131       HTTP::CookieMonster::Cookie objects.
132
133           my @cookies = $monster->all_cookies;
134           foreach my $cookie ( @cookies ) {
135               print $cookie->key;
136           }
137
138   set_cookie( $cookie )
139       Sets a cookie and updates the cookie jar.  Requires a
140       HTTP::CookieMonster::Cookie object.
141
142           my $monster = HTTP::CookieMonster->new( $mech->cookie_jar );
143           my $s = $monster->get_cookie('session');
144           $s->val('random_string');
145
146           $monster->set_cookie( $s );
147
148           # You can also add an entirely new cookie to the jar via this method
149
150           use HTTP::CookieMonster::Cookie;
151           my $cookie = HTTP::CookieMonster::Cookie->new(
152               key       => 'cookie-name',
153               val       => 'cookie-val',
154               path      => '/',
155               domain    => '.somedomain.org',
156               path_spec => 1,
157               secure    => 0,
158               expires   => 1376081877
159           );
160
161           $monster->set_cookie( $cookie );
162
163   delete_cookie( $cookie )
164       Deletes a cookie and updates the cookie jar.  Requires a
165       HTTP::CookieMonster::Cookie object.
166
167   get_cookie( $name )
168       Be aware that this method may surprise you by what it returns.  When
169       called in scalar context, get_cookie() returns the first cookie which
170       exactly matches the name supplied.  In many cases this will be exactly
171       what you want, but that won't always be the case.
172
173       If you are spidering multiple web sites with the same UserAgent object,
174       be aware that you'll likely have cookies from multiple sites in your
175       cookie jar.  In this case asking for get_cookie('session') in scalar
176       context may not return the cookie which you were expecting.  You will
177       be safer calling get_cookie() in list context:
178
179           $monster = HTTP::CookieMonster->new( $mech->cookie_jar );
180
181           # first cookie with this name
182           my $first_session = $monster->get_cookie('session');
183
184           # all cookies with this name
185           my @all_sessions  = $monster->get_cookie('session');
186

FUNCTIONAL/PROCEDURAL INTERFACE

188   cookies
189       This function will DWIM.  Here are some examples:
190
191           use HTTP::CookieMonster qw( cookies );
192
193           # get all cookies in your jar
194           my @cookies = cookies( $mech->cookie_jar );
195
196           # get all cookies of a certain name/key
197           my @session_cookies = cookies( $mech->cookie_jar, 'session_cookie_name' );
198
199           # get the first cookie of a certain name/key
200           my $first_session_cookie = cookies( $mech->cookie_jar, 'session_cookie_name' );
201

AUTHOR

203       Olaf Alders <olaf@wundercounter.com>
204
206       This software is copyright (c) 2012 by Olaf Alders.
207
208       This is free software; you can redistribute it and/or modify it under
209       the same terms as the Perl 5 programming language system itself.
210
211
212
213perl v5.32.1                      2021-01-27            HTTP::CookieMonster(3)
Impressum