HTTP Request Handling

General Overview

This library provides handling of HTTP requests for uHTML. It pre-processes and normalizes HTTP-Request variables like e.g. path and directory names, handles GET and POST data, handles cookies, generates HTTP headers and translates uHTML in HTML. This documentation refers to the version 1.81 of the uHTML::request library.

The probably most useful function of uHTML::request is the invocation of module specific functions before and after each request processing. This allows other modules to process data provided with a HTTP-Request before and after the generation of HTML code, allowing to alter the content of the HTML content and the HTTP headers according to the data provided with the request.

To install the module project local, copy it into the uHTML subdirectory of the script-directory of the website. To install it globally, copy it into the uHTML subdirectory of a perl-library directory.

Terms of Use

It is allowed to use this library under the actual GNU Lesser General Public License. The name of this library and it's author is to be named in all derivations.

Requirements

This uHTML::request library requires besides of the uHTML library the libraries: LWP::MediaTypes, URI::Escape, IO::Handle, Time::Local and POSIX.

Invocation Example

The following full working examples show the basic invocation of uHTML::request. For matching configurations, more file examples, uHTML deployment details and additional explanations see the uHTML description.

uHTML::request with CGI

The first example addresses CGI servers. The hook.pl program must be called by the webserver via a appropriate server request analogous to the basic uHTML invocation, e.g. by redirecting the requests in a .htaccess file.

hook.pl 
 #!/usr/bin/perl
 
 use uHTML::request;
 # $uHTML::FileName = '' ;  # uncomment for production code
 uHTML::request->process() ;
 

uHTML::request with FCGI

The second example addresses FCGI servers. To simplify the server deployment PSGI with Plack is used. Plack expects a perl executable psgi which follows the PSGI specifications. This executable takes the place of the hook.pl in the first example.

psgi
 use strict;
 use uHTML::request;

 sub
 {
   my $env = shift ;

   $env->{'PATH_INFO'} = $env->{'URI'} ;  # nginx+PLACK needs it for the compability with Apache CGI
   # $uHTML::FileName = '' ;  # uncomment for production code

   my $request = uHTML::request->new( $env ) ;
   return [ 200,$request->Headers(),$request->HTML() ] if $request ;
   return [ 404,[ 'Content-Type' => 'text/plain' ],[ 'Not Found' ] ] ;
 }

The Plack PSGI server is started with plackup -s FCGI -S /tmp/uHTML -a /usr/lib/perl/*/uHTML/psgi. For the matching configuration of the nginx server see the uHTML description

uHTML::request package

Data Structure

uHTML::request data structure is intended to be manipulated only by uHTML::request methods, but may be helpful for read only access. Directly accessed values aren't necessary set or valid. The data structure may change any time and should be accessed for debug purposes only.

  • ENV: - current environment
  • Root: - effective document root
  • Path: - path as array reference, Path[0] contains the server name
  • path: - path as string
  • file: - current file with path
  • File: - name of current file
  • BaseName: - name of current file with no extensions
  • Request: - current HTTP request URI as array reference, Request[0] contains the server name
  • RequestFile: - current HTTP request file
  • RequestName: - current HTTP request file with no extensions
  • request: - current HTTP request as string
  • home: - server directory containing the site's data
  • length: - length of the HTTP response
  • HTML: - the HTTP response
  • Query: - HTTP Query data (GET)
  • Post: - HTTP Post data (POST)
  • Data: - combined HTTP Query and Post data
  • RecvCookie: - received cookie
  • SendCookie: - cookie to be sent
  • Head: - HTTP head data
  • PostString: - HTTP Post data (POST) as string
  • InitRequest: - functions called on $request->Init()
  • FinishRequest: - functions called on $request->Finish()
  • uHTML::request methods

    new, Init, Finish, ENV, QueryData, PostData, Data, Cookie, ContentType, Headers, setHeader, putHeader, FileData, codeFile, putFile, process, HTML, file, File, BaseName, Path, RequestPath, RequestName, Root, home, ServerPath

    Description of uHTML::request methods

    new($env)

    Overview

    The method new creates a new uHTML::request object.

    Parameters

    $env
    The optional parameter $env must refer to the environment hash associated with the actuall HTTP request. If missing, the current environment is used instead.

    Example

    my $request = uHTML::request->new( $env );
    up↑
    Init(\&initFunc)

    Overview

    The method Init initialises the HTTP request processing and calls all module specific init functions.

    Parameters

    &initFunc($request)
    The parameter &initFunc must refer to a function which will be called before the uHTML file gets processed. The function is called with the reference to the current uHTML::request ($request). Typically this function will process data sent to the website.

    Example

    $request->Init(\&initFunc);
    up↑
    Finish(\&finishFunc)

    Overview

    The method Finish ends the HTTP request processing and calls all module specific finish functions.

    Parameters

    &finishFunc($request)
    The parameter &finishFunc must refer to a function which will be called after the uHTML file gets processed and before the HTTP headers get generated. The function is called with the reference to the current uHTML::request ($request). Typically this function will finish processing of data sent to the website, update server files and databases and set cookies and data which will be sent to the browser.

    Example

    $request->Finish(\&finishFunc);
    up↑
    ENV()

    Overview

    The method ENV returns the current environment. By passing an argument the environment can be set as well, this shouldn't be done except one knows very well what one does.

    Example

    $env = $request->ENV();
    up↑
    QueryData($Name)

    Overview

    The method QueryData returns the query data associated with $Name, speak data that was transmitted in the URI with the GET method. It returns context depending either an array containing all values associated with $Name in list context or the “first” value in scalar context.

    Parameters

    $Name
    Name of the data.

    Example

    $Data = $request->QueryData($DataName);
    up↑
    PostData($Name)

    Overview

    The method PostData returns the post data associated with $Name, speak data that was transmitted with the POST method via STDIN. It returns context depending either an array containing all values associated with $Name in list context or the “first” value in scalar context.

    When the data was transmitted as multipart/form-data the returned value is a reference to a HASH (or and array of HASH references in list context) containing the data. The HASH has the following values:

  • name - name of the data
  • label - label provided with the data>
  • length - data length
  • data - the data itself
  • boundary - boundary used in multipart/form-data
  • Parameters

    $Name
    Name of the data.

    Example

    $Picture = $request->PostData($PicName);
    up↑
    Data($Name)

    Overview

    The method Data returns a combination of post and query data associated with $Name, speak data that was transmitted either with the GET or the POST method. It practically lifts the difference between GET and POST data. It returns context depending either an array containing all values associated with $Name in list context or the “first” value in scalar context.

    When the data was transmitted as multipart/form-data the returned value is a reference to a HASH (or and array of HASH references in list context) containing the data. The HASH has the following values:

  • name - name of the data
  • label - label provided with the data>
  • length - data length
  • data - the data itself
  • boundary - boundary used in multipart/form-data
  • Parameters

    $Name
    Name of the data.

    Example

    $Picture = $request->Data($PicName);
    up↑
    Cookie($Name,$Value,$expire,$path,$host,$JS)

    Overview

    The method Cookie reads and sets cookies. To set (or delete) a cookie $Value must be defined.

    Parameters

    $Name
    Cookie name.
    $Value
    Cookie value. A value of "" do not removes the cookie.
    $expire
    Cookie expiration time in seconds (suffix none or s), hours (suffix h), days (suffix d), months (suffix m), or years (suffix y). The value 0 deletes the cookie.
    $path
    Cookie path. If not defined the path “/” is used.
    $host
    The host associated with the cookie. If not defined, “$ENV{'SERVER_NAME'}” is used.
    $JS
    If true, then the cookie is available via JavaScript.

    Example

    $Cookie = $request->Cookie($Name);
    up↑
    ContentType($Type)

    Overview

    The method ContentType returns the data type of the request file. It relays rather on the name of the file than on the content. Optionally the content type can be enforced by passing a parameter.

    Parameters

    $Type
    The optional parameter $Type sets the content type used in the HTTP headers.

    Example

    $ContentType = $request->ContentType();
    up↑
    Headers($length)

    Overview

    The method Headers returns the HTTP headers in PSGI format, a simple array, where the name and the value of each header entry follow each other and the array consists of value pairs.

    Parameters

    $length
    If given it overrides the internally calculated length of the HTML output.

    Example

    $PSGI_head = $request->Headers();
    up↑
    putHeader($length)

    Overview

    The method putHeader sends the HTTP headers to the STDOUT.

    Parameters

    $length
    If given it overrides the internally calculated length of the HTML output.

    Example

    $request->putHeader();
    up↑
    setHeader($name,$value)

    Overview

    The method setHeader ads a HTTP header.

    Parameters

    $name
    Header name. Must be given.
    $value
    Header value. Is set to ' ' if missing.

    Example

    $request->setHeader( 'x-PITarget',$request->Data('PITarget') );
    up↑
    FileData()

    Overview

    The method FileData gives access to the content of the uHTML file.

    Example

    $FData = $request->FileData();
    up↑
    codeFile()

    Overview

    The method codeFile translates internally uHTML into HTML.

    Example

    $request->codeFile();
    up↑
    process($env)

    Overview

    The method process processes a CGI HTTP request and sends the result to STDOUT. It can be either invoked as a method of an existing request or as package function. In the latter case process creates an own new uHTML::request and uses it to process the (CGI) HTTP request .

    Parameters

    $env
    The optional parameter $env is only used if a new uHTML::request is created. It must refer to the environment hash associated with the actuall HTTP request. If missing, the current environment is used instead.

    Example

    $request->process();
    uHTML::request->process( $env );
    up↑
    putFile()

    Overview

    The method putFile sends if existent the processed file content to STDOUT. If the processed content is missing, it sends the original file to STDOUT.

    Example

    $request->putFile();
    up↑
    file()

    Overview

    The method file returns the complete name including the path of the current request file.

    Example

    $FName = $request->file();
    up↑
    File($name)

    Overview

    The method File returns the name of the current request file without the path .

    Parameters

    $name
    Optional name of a new input file. If the $name starts with '/' the name is interpreted as relative to the effective document directory $request->{'Root'}. Otherwise it is interpreted as relative to the current directory. If the file is not found, the parameter is ignored.

    Example

    $FName = $request->File('/index.uhtml');
    up↑
    BaseName()

    Overview

    The method BaseName returns the name of the current file without the path and without extension.

    Example

    $Name = $request->BaseName();
    up↑
    Path($idx)

    Overview

    The method Path returns the path of the current request. It returns context depending either an array containing the all path elements in list context or a string in scalar context.

    Parameters

    $idx
    The optional parameter $idx indicates the desired part of the Path. It can contain a range. The value 0 returns the name of the host.

    Example

    $Path = $request->Path();
    up↑
    RequestPath($idx)

    Overview

    The method RequestPath returns the path used in the current HTTP request. It returns context depending either an array containing the all path elements in list context or a string in scalar context.

    Parameters

    $idx
    The optional parameter $idx indicates the desired part of the Request Path. It can contain a range. The value 0 returns the name of the website.

    Example

    $Path = $request->RequestPath();
    up↑
    RequestName()

    Overview

    The method RequestName returns the name of the current request file without the path and without extension.

    Example

    $Name = $request->RequestName();
    up↑
    Root()

    Overview

    The method Root returns the current document directory.

    Example

    $Docs = $request->Root();
    up↑
    ServerPath($Path)

    Overview

    The method ServerPath calculates the actual path on the server from a given $Path according to the uHTML path name conventions. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.

    Parameters

    $Path
    Path to convert.

    Example

    $File = $request->ServerPath('/index.uhtml');
    up↑