/ 
PAB3-3.201
River stage zero No dependents
1 ++
/ PAB3::CGI

NAME

PAB3::CGI - CGI module for the PAB3 environment or as standalone

SYNOPSIS

  # load module and export default functions and variables
  use PAB3::CGI qw(:default);
  
  # set some useful variables to the environment
  PAB3::CGI::setenv();
  
  # parse request and cookies and start the cgi output handler
  PAB3::CGI::init();
  
  if( $_REQUEST{'cmd'} eq 'showenv' ) {
      print_var( \%ENV );
  }
  elsif( $_REQUEST{'cmd'} eq 'redirect' ) {
      return redirect( 'http://myserver.com/' );
  }

DESCRIPTION

PAB3::CGI handles CGI requests. Some syntax is taken from PHP. Multipart content is based on the cgi-lib. Thank you for the great work.

EXAMPLES

Standard CGI output

  # load module and export default functions and variables
  use PAB3::CGI qw(:default);
  
  # parse request and cookies and start the cgi output handler
  PAB3::CGI::init();
  
  # start data output
  print "<h1>Environment</h1>\n";
  
  # print a human readable version of %ENV
  print_var( \%ENV );

CGI output with HTTP headers

  # load module and export default functions and variables
  use PAB3::CGI qw(:default);
  
  # parse request and cookies and start the cgi output handler
  PAB3::CGI::init();
  
  # set userdefined header
  header( "Content-Type: text/plain" );
  
  # start data output
  print "plain text comes here\n";

METHODS

init ( [%ARG] )

Initializes the CGI environment, parses request and cookies.

Available arguments are:

  request_max_size   => maximum allowed data to be sent to the server,
                        default value is 131072 (128kb)
  mpart_buffer_size  => size of buffer for reading files sent to
                        the server, default is 8192 (8kb)
  max_boundary       => maximum length of boundary in multipart
                        content, default is 10
  temp_dir           => directory to upload temporary files,
                        default value is '/tmp' on unix and %WINDOWS%\\Temp on
                        Win32
  save_to_file       => if TRUE, save uploaded files to disk
                        if FALSE, hold uploaded files in memory
                        default is TRUE

Example:

  PAB3::CGI::init();
setenv ()

Set some useful variables to the interpreters environment

these variables are:

  $ENV{'SCRIPT_PATH'}   : path to the main script
  $ENV{'SCRIPT'}        : name of the main script
  $ENV{'REMOTE_OS'}     : name of the remote operating system
setcookie ( $name )
setcookie ( $name, $value )
setcookie ( $name, $value, $expire )
setcookie ( $name, $value, $expire, $path )
setcookie ( $name, $value, $expire, $path, $domain )
setcookie ( $name, $value, $expire, $path, $domain, $secure )

setcookie() defines a cookie to be sent along with the rest of the HTTP headers. Like other headers, cookies must be sent before any other output. If output exists prior to calling this function, setcookie() will fail and return 0. If setcookie() successfully runs, it will return a true value. This does not indicate whether the remote user accepted the cookie. The first parameter $name defines the name of the cookie. The second parameter $value is stored on the clients computer. The third parameter defines the time the cookie expires. This is a Unix timestamp as number of seconds since the epoch. If $expire is undefined, the cookie will expire at the end of the session. The fourth parameter $path defines the path on the server in which the cookie will be available on. If path set to '/', the cookie will be available within the entire domain. If set to '/foo/', the cookie will only be available within the /foo/ directory and all sub- directories such as /foo/bar/ of domain. The default value is '/'. The fifth parameter $domain defines the domain that the cookie is available. To make the cookie available on all subdomains of example.com then you would set it to '.example.com'. The . is not required but makes it compatible with more browsers. Setting it to www.example.com will make the cookie only available in the www subdomain. The sixth parameter indicates that the cookie should only be transmitted over a secure HTTPS connection. When set to TRUE, the cookie will only be set if a secure connection exists. The default is FALSE.

header ( $header )
header ( $header, $overwrite )

header() is used to send raw HTTP headers. See the http://www.faqs.org/rfcs/rfc2616 specification for more information on HTTP headers.

Example:

  use PAB3::CGI qw(:default);
  
  # We'll be outputting a PDF
  header( 'Content-type: application/pdf' );
  # It will be called downloaded.pdf
  header( 'Content-Disposition: attachment; filename="downloaded.pdf"' );
  # Setting transfer encoding to binary
  header( 'Content-Transfer-Encoding: binary' );
  # Setting content length
  header( 'Content-Length: ' . ( -s 'original.pdf' ) );
  # Force proxies and clients to disable caching
  header( 'Pragma: no-cache, must-revalidate' );
  # Content expires now
  header( 'Expires: 0' );
  
  # Send the PDF to STDOUT
  open( FH '<original.pdf' );
  binmode( FH );
  while( read( FH, $buf, 8192 ) ) {
      print $buf;
  }
  close( FH );
redirect ( $location )
redirect ( $location, \%params )
redirect ( $location, \%params, $internal )

Redirects the client to $location. Optionally parameters can be defined in \%params. Inside modperl you can use an internal redirect by setting $internal to a TRUE value.

Example:

  &PAB3::CGI::redirect(
      'http://www.myserver.com/myscript',
      {
          'run' => 'login',
      }
  );
encode_uri_component ( $uri )

encode_uri_component escapes all characters except the following:

  alphabetic, decimal digits, - _ . ! ~ * ' ( )

For security reasons, you should call encode_uri_component() on any user-entered parameters that will be passed as part of a URI. For example, a user could type "Thyme &time=again" for a variable comment. Not using encode_uri_component on this variable will give comment=Thyme%20&time=again. Note that the ampersand and the equal sign mark a new key and value pair. So instead of having a POST comment key equal to "Thyme &time=again", you have two POST keys, one equal to "Thyme " and another (time) equal to again.

Example

  $uri = 'http://www.myserver.com/myscript?get='
      . encode_uri_component( 'My+Special&Designed:Argument' )
  ;
decode_uri_component ( $uri )

Decodes a Uniform Resource Identifier (URI) component previously created by encode_uri_component() or by a similar routine.

Replaces each escape sequence in the encoded URI component with the character that it represents.

encode_uri ( $uri )

Assumes that the URI is a complete URI, so does not encode reserved characters that have special meaning in the URI.

encode_uri() replaces all characters except the following with the appropriate UTF-8 escape sequences:

  Reserved characters   |  ; , / ? : @ & = + $
  ----------------------+-----------------------------------------------------
  Unescaped characters  |  alphabetic, decimal digits, - _ . ! ~ * ' ( )
  ----------------------+-----------------------------------------------------
  Score                 |  #

Note that encode_uri() by itself cannot form proper HTTP GET and POST requests, because "&", "+", and "=" are not encoded, which are treated as special characters in GET and POST requests. encode_uri_component(), however, does encode these characters.

decode_uri ( $uri )

Replaces each escape sequence in the encoded URI with the character that it represents.

Does not decode escape sequences that could not have been introduced by encode_uri().

Prints human-readable information about one or more variables

Example:

  &PAB3::CGI::print_r( \%ENV );
cleanup ()

Cleanup the PAB3::CGI environment, delete uploaded files and call the callback functions registered by cleanup_register().

cleanup() is called internally at the END block or inside ModPerl as cleanup callback at the end of each request. In other environments, like PerlEx or FastCGI, that do not support cleanup mechanism you need to call it at the end of your script.

cleanup_register ( $callback )
cleanup_register ( $callback, @arg )

Register cleanup callback to run

Parameters

$callback

A cleanup callback CODE reference or just a name of the subroutine (fully qualified unless defined in the current package).

@arg

If this optional arguments are passed, the $callback function will receive it as the arguments when executed.

VARIABLES

The hash %_COOKIE contains the cookies provided to the script via HTTP cookies.

%_GET

The hash %_GET contains the arguments provided to the script via GET input mechanismus. When running on the command line, this will also include the @ARGV entries.

%_POST

The hash %_POST contains the arguments provided to the script via POST input mechanismus.

%_REQUEST

The hash %_REQUEST contains the arguments provided to the script via GET and POST input mechanismus. When running on the command line, this will also include the @ARGV entries.

%_FILES

%_FILES is available in a multipart request. It contains the content or the temporary filename, the content-type, remote-filename and the content-length of uploaded files.

The following parameters are defined:

  name          => contains the remote filename
  size          => size of content
  type          => contains the content-type of the uploaded file
  tmp_name      => contains the temporary filename on the server

EXPORTS

By default the variables %_COOKIE, %_GET, %_POST, %_REQUEST and %_FILES are exported. To export variables and functions you can use the export tag ':default'.

AUTHORS

Christian Mueller <christian_at_hbr1.com>

COPYRIGHT

The PAB3::CGI module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.