In the Kitchen with Perl

To demonstrate setting, retrieving, and using cookie data with Perl, we've whipped up a little something from ingredients lying around the cupboard:

Our "Results page personalizer" is pure fiction, of course. But you can imagine a site that might allow the user to tailor search results by number and appearance, as well as selecting which result fields to display. This page is a standard HTML page with form fields. The names given to these form fields will be used in the Perl script that sets the cookie. Upon clicking "Save my preferences", this page triggers a CGI script, saveprefs.cgi.

saveprefs.cgi

#!/usr/bin/perl
#Save personalization preferences using a cookie

use CGI;
      
my $cgiobj=new CGI;
#Only need line below if CGI.pm module is earlier than version 2.57
#$cgiobj->use_named_parameters;

#store CGI parameter list in a hash
my %prefs=$cgiobj->Vars;

#construct cookie object
my $cookie=$cgiobj->cookie( 
	-name=>'searchprefs',
    -value=>\%prefs,
    -expires=>'+6M',
    -path=>'/cgi-bin',
    -domain=>'.mydomain.com'
   );
   
#output cookie header to browser
print $cgiobj->header(-cookie=>$cookie);
print "Your preferences have been saved.";

Creating cookies is easy because our trusty CGI module does most of the work. First, we create an instance of the CGI object, a familiar step from any of our Perl You Need to Know installments. The Vars method was introduced to the CGI object in version 2.50, and it dumps the CGI parameters into a Perl hash structure. A logical maneuver, really, since CGI parameters are simply key/value pairs, which is exactly what a Perl hash is. Our script here assumes that all of the CGI parameters are valuable for the cookie, hence we can simply rely on the Vars method.

In any case, we build a Perl hash with the key/value parameters that we want to store in the cookie. Next, we create a cookie object. This object has several available parameters. First, the name is crucial -- in this case, searchprefs, as we'll retrieve the cookie by this name later. The cookie value is specified as a reference to our hash. If you wanted only to assign a scalar value here, the reference syntax would not be necessary.

We need to choose an expiration time for the cookie; after this time, it will no longer exist. In this case, we've set the cookie to live for 6 months, represented by the "M" in the "+6M" value. You may replace the "M" with any of s,m,h,d,Y to specify seconds, minutes, hours, days, months, or years, respectively. Setting the expiration value to "now" will immediately expire the cookie -- this is how you can delete a cookie on demand, for instance. Omitting the expiration value entirely will create a session-long cookie, held in the browser's memory only until the browsing session is quit.

Cookies must be associated with the site for which they are valid. The path parameter lets you restrict the cookie to scripts within a certain path on the server; omit this and the path defaults to "/", or any script on the server. If you omit the domain parameter, the cookie will be good only for the host that served it. If you have multiple hosts on the same domain, such as machine1.mydomain.com and machine2.mydomain.com, setting the domain value to ".mydomain.com" will allow scripts in the specified path on either machine1 or machine2 to access this cookie. Of course, you cannot set the domain parameter different from the serving domain or broader than your domain -- ".com" will not work, for instance!

With the cookie object created, the cookie is sent to the browser via HTTP headers. In this case, the CGI module handles the work thanks to the header method. Once this header has been output, we can't output any additional headers to the page -- any further output will appear as page content, hence our closing "Your preferences have been saved" remark.

You're certainly welcome to send more than one cookie to the browser, but all must be sent at once in the header. Suppose you had created a second cookie object, $cookie2. The call to CGI's header method would then look like:

print $cgiobj->header(-cookie=>[$cookie,$cookie2]);

Keep in mind, though, that we've packed a number of pieces of data into the one cookie -- even though the cookie itself may see only one "value".

Statelessness Sophistication
The Perl You Need to Know
Out of the Oven