/ 
Plasp-1.09
River stage zero No dependents
/ Plasp::Request

NAME

Plasp::Request - $Request Object

SYNOPSIS

use Plasp::Request;

my $req = Plasp::Request->new(asp => $asp);
my $session_cookie = $req->Cookies('session');
my $host = $req->ServerVariables('HTTP_HOST');

DESCRIPTION

The request object manages the input from the client browser, like posts, query strings, cookies, etc. Normal return results are values if an index is specified, or a collection / perl hash ref if no index is specified. WARNING: the latter property is not supported in ActiveState PerlScript, so if you use the hashes returned by such a technique, it will not be portable.

A normal use of this feature would be to iterate through the form variables in the form hash...

$form = $Request->Form();
for(keys %{$form}) {
  $Response->Write("$_: $form->{$_}<br>\n");
}

Note that if a form POST or query string contains duplicate values for a key, those values will be returned through normal use of the $Request object:

@values = $Request->Form('key');

but you can also access the internal storage, which is an array reference like so:

$array_ref = $Request->{Form}{'key'};
@values = @{$array_ref};

Please read the PERLSCRIPT section for more information on how things like $Request->QueryString() & $Request->Form() behave as collections.

ATTRIBUTES

$Request->{Method}

API extension. Returns the client HTTP request method, as in GET or POST. Added in version 2.31.

$Request->{TotalBytes}

The amount of data sent by the client in the body of the request, usually the length of the form data. This is the same value as $Request->ServerVariables('CONTENT_LENGTH')

METHODS

$Request->BinaryRead([$length])

Returns a string whose contents are the first $length bytes of the form data, or body, sent by the client request. If $length is not given, will return all of the form data. This data is the raw data sent by the client, without any parsing done on it by Plasp.

Note that BinaryRead will not return any data for file uploads. Please see the $Request->FileUpload() interface for access to this data. $Request->Form() data will also be available as normal.

$Request->ClientCertificate()

Not implemented.

$Request->Cookies($name [,$key])

Returns the value of the Cookie with name $name. If a $key is specified, then a lookup will be done on the cookie as if it were a query string. So, a cookie set by:

Set-Cookie: test=data1=1&data2=2

would have a value of 2 returned by $Request->Cookies('test','data2').

If no name is specified, a hash will be returned of cookie names as keys and cookie values as values. If the cookie value is a query string, it will automatically be parsed, and the value will be a hash reference to these values.

When in doubt, try it out. Remember that unless you set the Expires attribute of a cookie with $Response->Cookies('cookie', 'Expires', $xyz), the cookies that you set will only last until you close your browser, so you may find your self opening & closing your browser a lot when debugging cookies.

For more information on cookies in ASP, please read $Response->Cookies()

$Request->FileUpload($form_field, $key)

API extension. The FileUpload interface to file upload data is stabilized. The internal representation of the file uploads is a hash of hashes, one hash per file upload found in the $Request->Form() collection. This collection of collections may be queried through the normal interface like so:

$Request->FileUpload('upload_file', 'ContentType');
$Request->FileUpload('upload_file', 'FileHandle');
$Request->FileUpload('upload_file', 'BrowserFile');
$Request->FileUpload('upload_file', 'Mime-Header');
$Request->FileUpload('upload_file', 'TempFile');

* note that TempFile must be use with the UploadTempFile configuration setting.

The above represents the old slow collection interface, but like all collections in Plasp, you can reference the internal hash representation more easily.

my $fileup = $Request->{FileUpload}{upload_file};
$fileup->{ContentType};
$fileup->{BrowserFile};
$fileup->{FileHandle};
$fileup->{Mime-Header};
$fileup->{TempFile};
$Request->Form($name)

Returns the value of the input of name $name used in a form with POST method. If $name is not specified, returns a ref to a hash of all the form data. One can use this hash to create a nice alias to the form data like:

# in global.asa
use vars qw( $Form );
sub Script_OnStart {
  $Form = $Request->Form;
}
# then in ASP scripts
<%= $Form->{var} %>

File upload data will be loaded into $Request->Form('file_field'), where the value is the actual file name of the file uploaded, and the contents of the file can be found by reading from the file name as a file handle as in:

while(read($Request->Form('file_field_name'), $data, 1024)) {};

For more information, please see the CGI / File Upload section, as file uploads are implemented via the CGI.pm module.

$Request->Params($name)

API extension. If RequestParams CONFIG is set, the $Request->Params object is created with combined contents of $Request->QueryString and $Request->Form. This is for developer convenience simlar to CGI.pm's param() method. Just like for $Response->Form, one could create a nice alias like:

# in global.asa
use vars qw( $Params );
sub Script_OnStart {
  $Params = $Request->Params;
}
$Request->QueryString($name)

Returns the value of the input of name $name used in a form with GET method, or passed by appending a query string to the end of a url as in http://localhost/?data=value. If $name is not specified, returns a ref to a hash of all the query string data.

$Request->ServerVariables($name)

Returns the value of the server variable / environment variable with name $name. If $name is not specified, returns a ref to a hash of all the server / environment variables data. The following would be a common use of this method:

$env = $Request->ServerVariables();
# %{$env} here would be equivalent to the cgi %ENV in perl.

SEE ALSO