NAME

TUWF::Request - Request parsing and handling for TUWF

DESCRIPTION

This module is responsible for parsing and handling the request data. This module is automatically loaded by TUWF and its methods can be used without requiring any special work.

This module can not be used outside of the TUWF framework.

METHODS

The following methods are added to the main TUWF object:

reqGet(name)

Get parameters from the query string. When name is not given or undef, returns a list of all parameter names (in no defined order). When used in array context and with name given, will return all values of the parameter in the order that they appear in the query string. When used in scalar context and with name given, will return the value of the first occurence of the parameter. When name is given, but there exists no parameter with that name, reqGet will return an empty list in array context or undef otherwise. Examples:

  # Let the query string be the following:
  #  "key=value&foo=bar1&foo=bar2"
  # Then:
  my @list = $self->reqGet();     # @list = ('key', 'foo')
  my $key = $self->reqGet('key'); # $key = 'value'
  my $foo = $self->reqGet('foo'); # $foo = 'bar1'
  my @foo = $self->reqGet('foo'); # @foo = ('bar1', 'bar2')
  my $no  = $self->reqGet('no');  # $no = undef
  my @no  = $self->reqGet('no');  # @no = ()

reqPost(name)

Behaves the same as reqGet(), but fetches the information from the POST data of the request instead. Unlike many CGI libraries, reqPost() will not return the file contents when the parameter comes from a file upload input element, instead, it will return the file name.

reqParam(name)

Combines reqGet() and reqPost(). The behaviour is the same as both functions, but reqParam() returns data from both the query string and POST data. In listings, POST parameters and values are always listed before the GET parameters and values, and in scalar context the value of the POST parameter has priotity over the GET value.

This function behaves similar to the param() function of many CGI libraries, with the exception that (like all other TUWF methods) reqParam() returns all data in Perls native unicode format and that for file uploads, the file name is returned instead of its contents.

reqUploadMIME(name)

When name is not given, returns a list of all parameter names that represent an uploaded file (in no particular order). In array context and when name is given, returns the MIME type of all uploaded files corresponding to the named parameter, in the order that they appear in the POST data. In scalar context and when name is given, will return the MIME type of the first uploaded file corresponding to the named parameter. When the named parameter does not exist or does not represent an uploaded file, reqUploadMIME() will return an empty list in array context or undef otherwise.

It is important to note that this function only works with parameters that actually represent an uploaded file. If a parameter comes from a file upload input element, but the user did not use it to actually upload a file (i.e. left it empty), then reqUploadMIME() will treat it as if the parameter did not exist at all. The parameter will then still show up in reqPost(), but with an empty string as "file name".

reqUploadRaw(name)

In list context, returns the contents of all uploaded files corresponding to the named parameter, in the order that they appear in the POST data. In scalar context, returns the contents of the first uploaded file.

Unlike all other methods, this method does NOT return the data in Perls native unicode format, but will return the data as a binary string. The reason for this is that TUWF has no way of knowing in which encoding the uploaded file is, and the file may not even represent text at all, but could be any binary file (e.g. a JPEG image).

reqSaveUpload(name, file)

Saves the contents of the first file uploaded with parameter name to file. Throws an error if it was unable to open file for writing.

reqCookie(name)

When name is not given, returns a list of all cookies names sent with the request, in no specific order. Otherwise, returns the value of the named cookie, or undef if the cookie does not exist.

If the cookie_prefix option is set, any cookies not having this prefix will not be listed when name is not given. The prefix is removed from all cookie names listed, and name should not have this prefix. For example:

  # at initialization
  TUWF::set(cookie_prefix => 'ex_');
  
  # ...later, when processing a request,
  my $auth = $self->reqCookie('auth');  # actually means 'ex_auth'
  
  # when assuming the 'ex_auth' cookie to be present,
  my @cookies = $self->reqCookie();     # @cookies = ('auth')

reqMethod()

Returns the HTTP request method. Can be either HEAD, GET or POST.

reqHeader(name)

When name is not given, returns a list of all headers passed with the request, in alphabetical order. Otherwise, returns the value of the named header or an empty string if the header is not present.

Header names are matched case-insensitive. The returned header names may not use the actual capitalization as used by the client. Some web servers may hide some request headers from the script. In particular, the Content-Type and Content-Length headers with POST requests may not be present, even when they have been sent by the client.

reqPath()

Returns the path part of the current page, relative to the base URI. Does not include a leading slash.

reqBaseURI()

Returns the base URI of the current page. That is, http(s):// plus hostname. Does not include a trailing slash.

reqURI()

Returns the full URI of the current page, including http(s):// and query string.

reqHost()

Returns the hostname (or domain name) of the website. Identical to reqHeader('Host').

reqIP()

Returns the IP address of the client. Note that this may be an IPv4 or IPv6 address, depending on the configuration of your webserver.

SEE ALSO

TUWF

COPYRIGHT

Copyright (c) 2008-2011 Yoran Heling.

This module is part of the TUWF framework and is free software available under the liberal MIT license. See the COPYING file in the TUWF distribution for the details.

AUTHOR

Yoran Heling <projects@yorhel.nl>

cpanm TUWF

perl -MCPAN -e shell
install TUWF