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:
reqGets(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). Otherwise it will return all values of the parameter in the order that they appear in the query string. In both cases an empty list may be returned if there are no parameters or if the named parameter does not exist. This method should not be used in scalar context.
Examples:
# Let the query string be the following:
# "key=value&foo=bar1&foo=bar2"
# Then:
my @list = tuwf->reqGets(); # @list = ('key', 'foo')
my @foo = tuwf->reqGets('foo'); # @foo = ('bar1', 'bar2')
my @no = tuwf->reqGets('no'); # @no = ()reqGet(name)
Get the first value of the named query string parameter. Roughly equivalent to (reqGets($name))[0]. The name argument is required. Since this method only ever returns a scalar value, it is safe to use when constructing lists:
my %stuff = (
name => tuwf->reqGet('name'),
);Don't do that with reqGets(), as it may leave you vulnerable to parameter injection!
reqPosts(name)
Behaves the same as reqGets(), but fetches the information from the body 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.
Contrary to its name, this method also works for PUT and PATCH requests, if they have a body with a supported content type,
reqPost(name)
Behaves the same as reqGet(), but for the request body.
reqParams(name)
Combines reqGets() and reqPosts(). The behaviour is the same as both functions, but reqParams() returns data from both the query string and POST data. POST parameters and values are always listed before the GET parameters and values.
This function behaves similar to the param() function of many CGI libraries, with the exception that (like all other TUWF methods) reqParams() returns all data in Perls native unicode format and that for file uploads, the file name is returned instead of its contents.
reqParam(name)
Behaves the same as reqGet(), but works on both POST and GET data. If a parameter is set in both the POST and GET data, only the value in the POST data is returned.
reqJSON()
Returns the decoded JSON object if the request body was of type application/json; Returns undef otherwise.
This requires either the JSON::XS, Cpanel::JSON::XS or JSON::PP module. If none of these modules is not available, any request with a JSON body will automatically get a 500 response.
reqUploadMIMEs(name)
When name is not given, returns a list of all parameter names that represent an uploaded file (in no particular order). 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. When the named parameter does not exist or does not represent an uploaded file, reqUploadMIMEs() will return an empty list.
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 reqUploadMIMEs() will treat it as if the parameter did not exist at all. The parameter will then still show up in reqPosts(), but with an empty string as "file name".
reqUploadMIME(name)
Behaves similarly to reqGet(), but works with the fields from reqUploadMIMEs().
reqUploadRaws(name)
Behaves similarly to reqUploadMIMEs(), but returns the file data instead of the MIME types.
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).
reqUploadRaw(name)
Behaves similarly to reqGet(), but works with the fields from reqUploadRaws().
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 = tuwf->reqCookie('auth'); # actually means 'ex_auth'
# when assuming the 'ex_auth' cookie to be present,
my @cookies = tuwf->reqCookie(); # @cookies = ('auth')reqMethod()
Returns the HTTP request method. Can be either DELETE, GET, HEAD, OPTIONS, PATCH, POST or PUT.
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. Includes a leading slash.
reqProtocol()
Returns the protocol used to perform the request, i.e. http or https.
Note that the detected protocol may be wrong if your website is running behind a reverse proxy that is either terminating or stripping HTTPS. As a workaround, you can manually set the correct HTTPS environment variable to 0 or 1 in your initialization code or, even better, in your web server configuration.
reqBaseURI()
Returns the base URI of the current page. That is, http(s):// plus hostname. Does not include a trailing slash.
reqQuery()
Returns the query string part of the current page, including leading question mark. Returns an empty string if the current page does not have a query part.
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.
reqFCGI()
Returns the FCGI::Request when running in FastCGI mode, or undef otherwise. See FCGI for more information. Mainly useful for calling the Detach() and Attach() methods to work around modules that do not work correctly with FCGI's filehandles. Calling any TUWF methods while the filehandles are detached might give weird results, so use with care.
SEE ALSO
COPYRIGHT
Copyright (c) 2008-2019 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>