PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

public package Foswiki::Request is a CGI

Class to encapsulate request data.

Fields:

• action action requested (view, edit, save, ...)
• cookies hashref whose keys are cookie names and values are CGI::Cookie objects
• headers hashref whose keys are header name
• method request method (GET, HEAD, POST)
• param hashref of parameters, both query and body ones
• param_list arrayref with parameter names in received order
• path_info path_info of request (eg. /WebName/TopciName)
• remote_address Client's IP address
• remote_user Remote HTTP authenticated user
• secure Boolean value about use of encryption
• server_port Port that the webserver listens on
• uploads hashref whose keys are parameter name of uploaded files
• uri the request uri

ClassMethod new([$initializer])

Constructs a Foswiki::Request object.

• $initializer - may be a filehandle or hashref.
  • If it's a filehandle, it'll be used to reload the Foswiki::Request object. See save method. Note: Restore only parameters
  • It can be a hashref whose keys are parameter names. Values may be arrayref's to multivalued parameters. Same note as above.

ObjectMethod action([$action]) → $action

Gets/Sets action requested (view, edit, save, ...)

ObjectMethod base_action() → $action

Get the first action ever set in this request object. This remains unchanged even if a request cache is unwrapped on to of this request. The idea is that callers can always find out the action that initiated the HTTP request. This is required for (for example) checking access controls.

ObjectMethod method( [ $method ] ) → $method

Sets/Gets request method (GET, HEAD, POST).

ObjectMethod pathInfo( [ $path ] ) → $path

Sets/Gets request path info.

Called without parameters returns current pathInfo.

There is a path_info() alias for compatibility with CGI.

Note that the string returned is a URL encoded byte string i.e. it will only contain characters -A-Za-z0-9_.~!*\'();:@&=+$,/?%#[] If you intend to analyse it, you will probably have to Foswiki::urlDecode it first.

ObjectMethod protocol() → $protocol

Returns 'https' if secure connection. 'http' otherwise.

ObjectMethod uri( [$uri] ) → $uri

Gets/Sets request uri.

ObjectMethod queryString() → $query_string

Returns query_string part of request uri, if any.

query_string() alias provided for compatibility with CGI.

Note that the string returned is a URL encoded byte string i.e. it will only contain characters -A-Za-z0-9_.~!*\'();:@&=+$,/?%#[] If you intend to analyse it, you will probably have to Foswiki::urlDecode it first.

ObjectMethod url( [-full → 1,

-base => 1, -absolute => 1, -relative => 1, -path => 1, -query => 1] ) -> $url

Returns many url info.

• If called without parameters or with -full => 1 returns full url, e.g. http://mysite.net/view
• If called with -base => 1 returns base url, e.g. http://foswiki.org
• -absolute => 1 returns absolute action path, e.g. /cgi-bin/view
• -relative => 1 returns relative action path, e.g. view
• -path => 1, -query => 1 also includes path info and query string respectively

Note that the path and query components are returned as a URL encoded byte string You will most likely need to Foswiki::urlDecode it for use.

Reasonably compatible with CGI corresponding method. Doesn't support -rewrite. See Item5914.

ObjectMethod secure( [$secure] ) → $secure

Gets/Sets connection's secure flag.

ObjectMethod remoteAddress( [$ip] ) → $ip

Gets/Sets client IP address.

remote_addr() alias for compatibility with CGI.

ObjectMethod remoteUser( [$userName] ) → $userName

Gets/Sets remote user's name.

remote_user() alias for compatibility with CGI.

ObjectMethod serverPort( [$userName] ) → $userName

Gets/Sets server user's name.

server_port() alias for compatibility with CGI.

ObjectMethod queryParam( [-name → $name, -value => $value |

-name => $name, -values => [ $v1, $v2, ... ] | $name, $v1, $v2, ... | name, [ $v1, $v2, ... ] ] ) -> @paramNames | @values | $firstValue

This method is used by engines, during its prepare phase. Should not be used anywhere else. Since bodyParam must exist and it has different semantics from param method, this one exists for symmetry, and could be modified in the future, so it could be possible to get query and body parameters independently.

ObjectMethod bodyParam( [-name → $name, -value => $value |

-name => $name, -values => [ $v1, $v2, ... ] | $name, $v1, $v2, ... | name, [ $v1, $v2, ... ] ] ) -> @paramNames | @values | $firstValue

Adds parameters passed within request body to the object. Should be called only by engines. Otherwise use param() method.

ObjectMethod param( [-name → $name, -value => $value |

-name => $name, -values => [ $v1, $v2, ... ] | $name, $v1, $v2, ... | name, [ $v1, $v2, ... ] ] ) -> @paramNames | @values | $firstValue

• Called without parameters returns all parameter names
• Called only with parameter name or with -name => 'name'
  • In list context returns all associated values (maybe empty list)
  • In scalar context returns first value (maybe undef)
• Called with name and list of values or with -name => 'name', -value => 'value' or -name => 'name', -values => [ ... ] sets parameter value
• Returns parameter values as UTF-8 encoded binary strings

Resonably compatible with CGI.

NOTE this method will assert if it is called in a list context. A list context might be:

• in a list of parameters e.g. my_function( $query->param( ...
• assigning to a list e.g. my @l = $query->param(...
• in a loop condition e.g. foreach ($query->param(...

The following are scalar contexts:

• defined($query->param( ... is OK
• lc($query->param( ... is OK
• ... if ( $query->param( ... is OK

In a list context, you should call multi_param (fully compatible) to retrieve list parameters.

ObjectMethod cookie($name [, $value, $path, $secure, $expires]) → $value

• If called without parameters returns a list of cookie names.
• If called only with $name parameter returns value of cookie with that name or undef if it doesn't exist.
• If called with defined $value and other parameters returns a CGI::Cookie object created with those parameters. Doesn't store this new created cookie within request object. This way for compatibility with CGI.

ObjectMethod cookies( \%cookies ) -> $hashref

Gets/Sets cookies hashref. Keys are cookie names and values CGI::Cookie objects.

ObjectMethod delete( @paramNames )

Deletes parameters from request.

Delete() alias provided for compatibility with CGI

ObjectMethod deleteAll()

Deletes all parameter name and value(s).

delete_all() alias provided for compatibility with CGI.

ObjectMethod header([-name → $name, -value => $value |

-name => $name, -values => [ $v1, $v2, ... ] | $name, $v1, $v2, ... | name, [ $v1, $v2, ... ] ] ) -> @paramNames | @values | $firstValue

Gets/Sets a header field:

• Called without parameters returns all header field names
• Called only with header field name or with -name => 'name'
  • In list context returns all associated values (maybe empty list)
  • In scalar context returns the first value (maybe undef)
• Called with name and list of values or with -name => 'name', -value => 'value' or -name => 'name', -values => [ ... ] sets header field value

Not compatible with CGI, since CGI correspondent is a response write method. CGI scripts obtain headers from %ENV or http method. %ENV is not available and must be replaced by calls to this and other methods of this class. http is provided for compatibility, but is deprecated. Use this one instead.

Calls to CGI header method must be replaced by calls to Foswiki::Response header method.

ObjectMethod save( $fh )

Saves object state to filehandle. Object may be loaded later passing $fh to new constructor or by calling load().

ObjectMethod load( $fh )

Loads object state from filehandle, probably created with a previous save().

ObjectMethod upload( $name ) → $handle

Called with file name parameter returns an open filehandle to uploaded file.

ObjectMethod uploadInfo( $fname ) → $headers

Returns a hashref to information about uploaded files as sent by browser.

ObjectMethod tmpFileName( $fname ) → $tmpFileName

Returns the name of temporarly created file to store uploaded $fname.

$fname may be obtained by calling param() with form field name.

ObjectMethod uploads( [ \%uploads ] ) → $hashref

Gets/Sets request uploads field. Keys are uploaded file names, as sent by browser, and values are Foswiki::Request::Upload objects.

ObjectMethod http( [$header] ) → $value DEPRECATED

Called without parameters returns a list of all available header filed names.

Given a field name returns value associated.

http('HTTP_USER_AGENT'); http('User-Agent') and http('User_Agent') are equivalent.

Please, use header() instead. Present only for compatibility with CGI.

ObjectMethod https( [$name] ) → $value || $secure DEPRECATED

Similar to http() method above. Called with no parameters returns secure flag.

Please, use header() and secure() instead. Present only for compatibility with CGI.

ObjectMethod userAgent() → $userAgent;

Convenience method to get User-Agent string.

user_agent() alias provided for compatibility with CGI.

ObjectMethod referer()

Convenience method to get Referer uri.