NAME

PSA::Request::CGI - Encapsulate a Cursed Gateway Interface Request

SYNOPSIS

 my $request = PSA::Request::CGI->fetch();

 my $sid = $request->sid;
 my $momma = $request->param("momma");

 my $login_name = $request->cookie->{"login_name"}->value();

 my $uri = $request->uri();

DESCRIPTION

This module decodes CGI requests into an encapsulated object, and provides functions for convenient session management.

METHODS

fetch(option => value, [...])

This is the main constructor for PSA::Request::CGI objects.

This function extracts all the standard CGI globals from the environment, and extracts the session ID from a variety of places, as described above.

Available options:

env

The environment to extract information out of. Defaults to the program environment (%ENV).

fh

The filehandle to read POST and PUT data from. Defaults to standard input.

param("name" [, "name" [...])

Fetch a named parameter (or list of named parameters) to the request.

Setting the same CGI parameter multiple times within the same query string (eg http://www.foo.com/script.cgi?yin=empty&yin=without) is possible, but not advised. If you want to get them out, then make sure you call param in list context and exactly one parameter name.

filename()

Returns the PATH_INFO of this request, with the session ID and other parameters removed. Also, if present the BASE uri (as set by $request->set_base()) is removed.

uri("option" [,...])

This returns a URI suitable for using in links and form targets. If given no parameters, it will return a string that takes you back to the same page using relative links, which may or may not contain a query component.

Specify any of the following keywords to modify the URI that is returned:

absolute

Ensures that the URI is complete - eg http://hostname/script.cgi/page.pl.

post

Ensures that the URI is suitable for POSTing. This means there will be no query component. If we didn't get a valid SID from a cookie, the SID will be placed in the path.

query

Ensures that the uri ends in a query component

flat

Specifies that the file is a flat resource; return a URL to what we suppose is our docroot.

nosid

Don't try and encode the session ID in the URL.

self

Ensures that the uri points to yourself. This is a default option.

/\./, or "call", "page.pl"

It is a URI to another page within PSA. Specify the relative path to that page as a parameter. Any parameter containing a dot is assumed to mean a link.

SESSION TRACKING

This module looks for session IDs in the following places when you call fetch():

HTTP Cookie

If there is a cookie called "SID", then that is taken to mean the session ID. If you want to call your cookie something else, see cookie_name.

PATH_INFO

The PATH_INFO is often a handy place to put the SID. It just doesn't have the headaches of many other places, but of course you lose the ability to cut and paste document URLs. Caveat emptor.

To make it clear, the PATH_INFO is everything after the name of the script; that is, in this url:

  http://meat.shop/cgi-bin/script.cgi/1234/hello

Assuming that /cgi-bin/script.cgi refers to a valid CGI script, then the PATH_INFO will be /1234/hello.

For this to work, we have to know what session IDs look like. Most session ids are either a long string of numbers or hex digits, so I use the regular expression qr/[0-9a-f]{12,32}/i by default to mean a session ID. If your session ID does not match that regular expression, you'll have to define the sid_re attribute.

Note that this sid_re regular expression is used to sanity check all SIDs received. If it doesn't match the expression, it is IGNORED.

QUERY_STRING

If there is a query parameter called "SID", then that is taken to mean the session ID. The attribute sid_query_param overrides this.

CGI ENVIRONMENT VARIABLES

Common Gateway Interface version 1.1 is defined at http://hoohoo.ncsa.uiuc.edu/cgi/env.html; It defines (amongst other arbitrary and crap things) some standard environment variables that are passed to CGI programs. Apache embraces and extends this list to contain exotic bullshit environment variables useful for writing one line shell scripts. Do not be seduced by these environment variables, they are as bad as not having `use strict' at the top of your programs.

This module deals with that rubbish for you. It extracts all of the information out of the environment and presents them as methods of the request object. This allows for the actual mechanism by which requests come in to alter its form without you having to rewrite all your scripts; they merely need implement an interface equivalent to this one.

The following functions are defined for the nostalgic and impatient; note that these are effectively carried over cruft from the CGI specification; by using them, you are importing that crap directly into your program.

Much better to use the functions above, which are more generic.

server_software

The software that the web server is running - Software/version

gateway_interface

probably "CGI/1.1"

server_name

The server name that was used in the HTTP request

server_protocol

HTTP/1.1

server_port

80

request_method

GET, PUT, POST, etc.

path_info

Everything after the script name in the URL

path_translated

$0 . $path_info

script_name

Everything up to the script name in the URL

query_string

Everything after the ? in the URL

remote_host

the other end of this connection

remote_addr

Remote IP address of the client

auth_type

??

remote_user

presumably the HTTP user name

remote_ident

?

content_type

The MIME content type of the input

content_length

The number of octets of the input

http_referer

The full URL of the referring page; this environment variable is not officially part of the CGI spec, but it is usually set.

SEE ALSO

PSA, PSA::Acceptor::AutoCGI

cpanm PSA

perl -MCPAN -e shell
install PSA