NAME

CGI::Tiny - Common Gateway Interface, with no frills

SYNOPSIS

#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use CGI::Tiny;

cgi {
  my $cgi = $_;
  $cgi->set_error_handler(sub {
    my ($cgi, $error) = @_;
    warn $error;
    unless ($cgi->headers_rendered) {
      if ($cgi->response_status_code == 413) {
        $cgi->render(json => {error => 'Request body limit exceeded'});
      } elsif ($cgi->response_status_code == 400) {
        $cgi->render(json => {error => 'Bad request'});
      } else {
        $cgi->render(json => {error => 'Internal server error'});
      }
    }
  });

  my $method = $cgi->method;
  my $fribble;
  if ($method eq 'GET') {
    $fribble = $cgi->query_param('fribble');
  } elsif ($method eq 'POST') {
    $fribble = $cgi->body_param('fribble');
  } else {
    $cgi->set_response_status(405)->render;
    exit;
  }
  die "Invalid fribble parameter" unless length $fribble;

  if ($cgi->query_param('download')) {
    $cgi->set_response_download('fribble.json');
  }
  $cgi->render(json => {fribble => $fribble});
};

DESCRIPTION

CGI::Tiny provides a modern interface to write CGI scripts to dynamically respond to HTTP requests as defined in RFC 3875. It is intended to be:

Minimal

CGI::Tiny contains a small amount of code and (on modern Perls) no non-core requirements. No framework needed.
Simple

CGI::Tiny is straightforward to use, avoids anything magical or surprising, and provides easy access to the most commonly needed features.
Robust

CGI::Tiny's interface is designed to help the developer avoid common pitfalls and vulnerabilities by default.
Lazy

CGI::Tiny only loads code or processes information once it is needed, so simple requests can be handled without unnecessary overhead.
Restrained

CGI::Tiny is designed for the CGI protocol which executes the program again for every request. It is not suitable for persistent protocols like FastCGI or PSGI.
Flexible

CGI::Tiny can be used with other modules to handle tasks like routing and templating, and doesn't impose unnecessary constraints to reading input or rendering output.

Most applications are better written in a PSGI-compatible framework (e.g. Dancer2 or Mojolicious) and deployed in a persistent application server so that the application does not have to start up again every time it receives a request. CGI::Tiny, and the CGI protocol in general, is only suited for restricted deployment environments that can only run CGI scripts, or applications that don't need to scale.

See "COMPARISON TO CGI.PM".

This module's interface is currently EXPERIMENTAL and may be changed incompatibly if needed.

USAGE

CGI::Tiny's interface is a regular function called cgi exported by default.

cgi {
  my $cgi = $_;
  # set up error handling on $cgi
  # inspect request data via $cgi
  # set response headers if needed via $cgi
  # render response data with $cgi->render
};

The code block is immediately run with $_ set to a CGI::Tiny object, which "METHODS" can be called on to read request information and render a response.

If an exception is thrown within the code block, or the code block does not render a response, it will run the handler set by "set_error_handler" if any, or by default emit the error as a warning and (if nothing has been rendered yet) render a 500 Internal Server Error.

Note that the cgi block's current implementation as a regular exported subroutine is an implementation detail, and future implementations reserve the right to provide it as an XSUB or keyword for performance reasons. You should not rely on @_ to be set, and you should not use return to exit the block; use exit to end a CGI script early after rendering a response.

EXTENDING

CGI::Tiny is a minimal interface to the CGI protocol, but can be extended with the use of other CPAN modules.

Fatpacking

App::FatPacker can be used to pack CGI::Tiny, as well as any other pure-perl dependencies, into a CGI script so that it can be deployed to other systems without having to install the dependencies there. As a bonus, this means the script doesn't have to load those modules separately from disk on every execution.

Just keep in mind that the script will have to be repacked to update those dependencies, and CGI scripts greatly benefit from efficient XS tools which cannot be packed this way.

$ fatpack pack script.source.cgi > script.cgi

To pack in optional modules, such as JSON support for Perls older than 5.14:

$ fatpack trace --use=JSON::PP script.source.cgi
$ fatpack packlists-for $(cat fatpacker.trace) > packlists
$ fatpack tree $(cat packlists)
$ fatpack file script.source.cgi > script.cgi

JSON

CGI::Tiny has built in support for parsing and rendering JSON content with JSON::PP. CGI scripts that deal with JSON content will greatly benefit from installing Cpanel::JSON::XS version 4.09 or newer for efficient encoding and decoding, which will be used automatically if available.

Files

Modules like Path::Tiny and MIME::Types can help with file responses. Be aware that Perl and some operating systems work with filenames in encoded bytes, so non-ASCII filenames make things trickier.

#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use CGI::Tiny;
use Path::Tiny;
use MIME::Types;

cgi {
  my $cgi = $_;

  my $filename = $cgi->query_param('filename');
  unless (length $filename) {
    $cgi->set_response_status(404)->render(text => 'Not Found');
    exit;
  }

  # get files from public/ next to cgi-bin/
  my $public_dir = path(__FILE__)->realpath->parent->sibling('public');
  my $filepath = $public_dir->child($filename);

  # ensure file exists, is readable, and is not a directory
  unless (-r $filepath and !-d _) {
    $cgi->set_response_status(404)->render(text => 'Not Found');
    exit;
  }

  # ensure file path doesn't escape the public/ directory
  unless ($public_dir->subsumes($filepath->realpath)) {
    $cgi->set_response_status(404)->render(text => 'Not Found');
    exit;
  }

  my $mime = MIME::Types->new->mimeTypeOf($filepath->basename);
  $cgi->set_response_content_type($mime->type) if defined $mime;
  $cgi->set_response_download($filepath->basename)->render(file => $filepath);
};

Templating

HTML and XML responses are most easily managed with templating. A number of CPAN modules provide this capability.

Text::Xslate is an efficient template engine designed for HTML/XML.

#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use CGI::Tiny;
use Text::Xslate;
use Data::Section::Simple 'get_data_section';

cgi {
  my $cgi = $_;
  my $foo = $cgi->query_param('foo');
  my $tx = Text::Xslate->new(path => ['templates'], cache => 0);

  # from templates/
  $cgi->render(html => $tx->render('index.tx', {foo => $foo}));

  # from __DATA__
  my $template = get_data_section 'index.tx';
  $cgi->render(html => $tx->render_string($template, {foo => $foo}));
};

__DATA__
@@ index.tx
<html><body><h1><: $foo :></h1></body></html>

Mojo::Template is a lightweight HTML/XML template engine in the Mojo toolkit.

#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use CGI::Tiny;
use Mojo::Template;
use Mojo::File 'curfile';
use Mojo::Loader 'data_section';

cgi {
  my $cgi = $_;
  my $foo = $cgi->query_param('foo');
  my $mt = Mojo::Template->new(auto_escape => 1, vars => 1);

  # from templates/
  my $template_path = curfile->sibling('templates', 'index.html.ep');
  $cgi->render(html => $mt->render_file($template_path, {foo => $foo}));

  # from __DATA__
  my $template = data_section __PACKAGE__, 'index.html.ep';
  $cgi->render(html => $mt->render($template, {foo => $foo}));
};

__DATA__
@@ index.html.ep
<html><body><h1><%= $foo %></h1></body></html>

Routing

Web applications use routing to serve multiple types of requests from one application. Routes::Tiny can be used to organize this with CGI::Tiny, using REQUEST_METHOD and PATH_INFO (which is the URL path after the CGI script name).

#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use CGI::Tiny;
use Routes::Tiny;

my %dispatch = (
  foos => sub {
    my ($cgi) = @_;
    my $method = $cgi->method;
    ...
  },
  get_foo => sub {
    my ($cgi, $captures) = @_;
    my $id = $captures->{id};
    ...
  },
  put_foo => sub {
    my ($cgi, $captures) = @_;
    my $id = $captures->{id};
    ...
  },
);

cgi {
  my $cgi = $_;

  my $routes = Routes::Tiny->new;
  # /script.cgi/foo
  $routes->add_route('/foo', name => 'foos');
  # /script.cgi/foo/42
  $routes->add_route('/foo/:id', method => 'GET', name => 'get_foo');
  $routes->add_route('/foo/:id', method => 'PUT', name => 'put_foo');

  if (defined(my $match = $routes->match($cgi->path, method => $cgi->method))) {
    $dispatch{$match->name}->($cgi, $match->captures);
  } else {
    $cgi->set_response_status(404)->render(text => 'Not Found');
  }
};

METHODS

The following methods can be called on the CGI::Tiny object provided to the cgi code block.

Setup

set_error_handler

$cgi = $cgi->set_error_handler(sub {
  my ($cgi, $error) = @_;
  ...
});

Sets an error handler to run in the event of an exception. If the response status has not been set by "set_response_status" or rendering headers, it will default to 500 when this handler is called.

The error value can be any exception thrown by Perl or user code. It should generally not be included in any response rendered to the client, but instead warned or logged.

Exceptions may occur before or after response headers have been rendered, so error handlers should render some response if "headers_rendered" is false. "response_status_code" may be set by some errors and can be inspected if headers have not been rendered yet.

If the error handler itself throws an exception, that error and the original error will be emitted as a warning. If no response has been rendered after the error handler completes or dies, a default error response will be rendered.

set_request_body_buffer

$cgi = $cgi->set_request_body_buffer(256*1024);

Sets the buffer size (number of bytes to read at once) for reading the request body. Defaults to the value of the CGI_TINY_REQUEST_BODY_BUFFER environment variable or 262144 (256 KiB). A value of 0 will use the default value.

set_request_body_limit

$cgi = $cgi->set_request_body_limit(16*1024*1024);

Sets the limit in bytes for the request body. Defaults to the value of the CGI_TINY_REQUEST_BODY_LIMIT environment variable or 16777216 (16 MiB). A value of 0 will remove the limit (not recommended unless you have other safeguards on memory usage).

Since the request body is not parsed until needed, methods that parse the request body like "body" or "upload" will set the response status to 413 Payload Too Large and throw an exception if the content length is over the limit. Files uploaded through a multipart/form-data request body also count toward this limit, though they are streamed to temporary files when parsed.

set_multipart_form_charset

$cgi = $cgi->set_multipart_form_charset('UTF-8');

Sets the default charset for decoding multipart/form-data forms, defaults to UTF-8. Parameter and upload field names, upload filenames, and text parameter values that don't specify a charset will be decoded from this charset. Set to an empty string to disable this decoding, effectively interpreting such values in ISO-8859-1.

set_input_handle

$cgi = $cgi->set_input_handle($fh);

Sets the input handle to read the request body from. If not set, reads from STDIN. The handle will have binmode applied before reading to remove any translation layers.

set_output_handle

$cgi = $cgi->set_output_handle($fh);

Sets the output handle to print the response to. If not set, prints to STDOUT. The handle will have binmode applied before printing to remove any translation layers.

Request

auth_type

content_length

content_type

gateway_interface

path_info

path_translated

query_string

remote_addr

remote_host

remote_ident

remote_user

request_method

script_name

server_name

server_port

server_protocol

server_software

my $auth_type      = $cgi->auth_type;         # AUTH_TYPE
my $content_length = $cgi->content_length;    # CONTENT_LENGTH
my $content_type   = $cgi->content_type;      # CONTENT_TYPE
my $gateway        = $cgi->gateway_interface; # GATEWAY_INTERFACE
my $path           = $cgi->path_info;         # PATH_INFO
my $file_path      = $cgi->path_translated;   # PATH_TRANSLATED
my $query          = $cgi->query_string;      # QUERY_STRING
my $remote_addr    = $cgi->remote_addr;       # REMOTE_ADDR
my $remote_host    = $cgi->remote_host;       # REMOTE_HOST
my $remote_ident   = $cgi->remote_ident;      # REMOTE_IDENT
my $remote_user    = $cgi->remote_user;       # REMOTE_USER
my $method         = $cgi->request_method;    # REQUEST_METHOD
my $script_name    = $cgi->script_name;       # SCRIPT_NAME
my $hostname       = $cgi->server_name;       # SERVER_NAME
my $port           = $cgi->server_port;       # SERVER_PORT
my $protocol       = $cgi->server_protocol;   # SERVER_PROTOCOL
my $server         = $cgi->server_software;   # SERVER_SOFTWARE

Access to request meta-variables of the equivalent uppercase names. Since CGI does not distinguish between missing and empty values, missing values will be normalized to an empty string.

method

path

query

my $method = $cgi->method; # REQUEST_METHOD
my $path   = $cgi->path;   # PATH_INFO
my $query  = $cgi->query;  # QUERY_STRING

Short aliases for a few request meta-variables.

query_params

my $pairs = $cgi->query_params;

Retrieve URL query string parameters as an ordered array reference of name/value pairs, represented as two-element array references. Names and values are decoded to Unicode characters.

query_param_names

my $arrayref = $cgi->query_param_names;

Retrieve URL query string parameter names, decoded to Unicode characters, as an ordered array reference.

query_param

my $value = $cgi->query_param('foo');

Retrieve value of a named URL query string parameter, decoded to Unicode characters. If the parameter name was passed multiple times, returns the last value. Use "query_param_array" to get multiple values of a parameter.

query_param_array

my $arrayref = $cgi->query_param_array('foo');

Retrieve values of a named URL query string parameter, decoded to Unicode characters, as an ordered array reference.

headers

my $hashref = $cgi->headers;

Hash reference of available request header names and values. Header names are represented in lowercase.

my $value = $cgi->header('Accept-Language');

Retrieve the value of a request header by name (case insensitive). CGI request headers can only contain a single value, which may be combined from multiple values.

cookies

my $pairs = $cgi->cookies;

Retrieve request cookies as an ordered array reference of name/value pairs, represented as two-element array references.

cookie_names

my $arrayref = $cgi->cookie_names;

Retrieve request cookie names as an ordered array reference.

my $value = $cgi->cookie('foo');

Retrieve the value of a request cookie by name. If multiple cookies were passed with the same name, returns the last value. Use "cookie_array" to get multiple values of a cookie name.

cookie_array

my $arrayref = $cgi->cookie_array('foo');

Retrieve values of a request cookie name as an ordered array reference.

body

my $bytes = $cgi->body;

Retrieve the request body as bytes.

Note that this will read the whole request body into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

Not available after calling "body_parts", "body_params", or "uploads" (or related accessors) on a multipart/form-data request, since this type of request body is not retained in memory after parsing.

body_params

my $pairs = $cgi->body_params;

Retrieve application/x-www-form-urlencoded or multipart/form-data body parameters as an ordered array reference of name/value pairs, represented as two-element array references. Names and values are decoded to Unicode characters.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

body_param_names

my $arrayref = $cgi->body_param_names;

Retrieve application/x-www-form-urlencoded or multipart/form-data body parameter names, decoded to Unicode characters, as an ordered array reference.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

body_param

my $value = $cgi->body_param('foo');

Retrieve value of a named application/x-www-form-urlencoded or multipart/form-data body parameter, decoded to Unicode characters. If the parameter name was passed multiple times, returns the last value. Use "body_param_array" to get multiple values of a parameter.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

body_param_array

my $arrayref = $cgi->body_param_array('foo');

Retrieve values of a named application/x-www-form-urlencoded or multipart/form-data body parameter, decoded to Unicode characters, as an ordered array reference.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

body_json

my $data = $cgi->body_json;

Decode an application/json request body from UTF-8-encoded JSON.

Note that this will read the whole request body into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

body_parts

my $parts = $cgi->body_parts;

Retrieve multipart/form-data request body parts as an ordered array reference. Most applications should retrieve multipart form data through "body_params" and "uploads" (or related accessors) instead.

Body parts are represented as hash references containing:

headers: Hash reference of part headers. Header names are represented in lowercase.
name: Form field name from Content-Disposition header, undecoded.
filename: Filename from Content-Disposition header if present, undecoded.
size: Size of part contents in bytes.
content: Part contents as undecoded bytes, for parts without a defined filename. File uploads are stored in a temporary file instead.
file: File::Temp object referencing temporary file containing the part contents, for parts with a defined filename.

uploads

my $pairs = $cgi->uploads;

Retrieve multipart/form-data file uploads as an ordered array reference of name/upload pairs, represented as two-element array references. Names are decoded to Unicode characters.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

File uploads are represented as a hash reference containing the following keys:

filename: Original filename supplied to file input. An empty filename may indicate that no file was submitted.
content_type: Content-Type of uploaded file, undef if unspecified.
size: File size in bytes.
file: File::Temp object storing the file contents in a temporary file, which will be cleaned up when the CGI script ends by default. The filehandle will be open with the seek pointer at the start of the file for reading.

upload_names

my $arrayref = $cgi->upload_names;

Retrieve multipart/form-data file upload names, decoded to Unicode characters, as an ordered array reference.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

upload

my $upload = $cgi->upload('foo');

Retrieve a named multipart/form-data file upload. If the upload name was passed multiple times, returns the last value. Use "upload_array" to get multiple uploads with the same name.

See "uploads" for details on the representation of the upload.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

upload_array

my $arrayref = $cgi->upload_array('foo');

Retrieve all multipart/form-data file uploads of the specified name as an ordered array reference.

See "uploads" for details on the representation of the uploads.

Note that this will read the text form fields into memory, so make sure the "set_request_body_limit" can fit well within the available memory.

Response

set_nph

$cgi = $cgi->set_nph(1);

If set to a true value before rendering response headers, CGI::Tiny will act as a NPH (Non-Parsed Header) script and render full HTTP response headers. This may be required for some CGI servers, or enable unbuffered responses or HTTP extensions not supported by the CGI server.

No effect after response headers have been rendered.

set_response_body_buffer

$cgi = $cgi->set_response_body_buffer(128*1024);

Sets the buffer size (number of bytes to read at once) for streaming a file or handle response body with "render". Defaults to the value of the CGI_TINY_RESPONSE_BODY_BUFFER environment variable or 131072 (128 KiB). A value of 0 will use the default value.

set_response_status

$cgi = $cgi->set_response_status(404);
$cgi = $cgi->set_response_status('500 Internal Server Error');

Sets the response HTTP status code. A full status string including a human-readable message will be used as-is. A bare status code must be a known HTTP status code and will have the standard human-readable message appended.

No effect after response headers have been rendered.

The CGI protocol assumes a status of 200 OK if no response status is set.

set_response_content_type

$cgi = $cgi->set_response_content_type('application/xml');

Sets the response Content-Type header, to override autodetection in "render". No effect after response headers have been rendered.

set_response_charset

$cgi = $cgi->set_response_charset('UTF-8');

Set charset to use when rendering text, html, or xml response data, defaults to UTF-8.

set_response_download

$cgi = $cgi->set_response_download;
$cgi = $cgi->set_response_download($filename);

Sets the response Content-Disposition header to indicate to the client that the response is a file download, with an optional filename specified in Unicode characters. No effect after response headers have been rendered.

add_response_header

$cgi = $cgi->add_response_header('Content-Disposition' => 'attachment');

Adds a custom response header. No effect after response headers have been rendered.

Note that header names are case insensitive and CGI::Tiny does not attempt to deduplicate or munge headers that have been added manually. Headers are printed in the response in the same order added, and adding the same header multiple times will result in multiple instances of that response header.

add_response_cookie

$cgi = $cgi->add_response_cookie($name => $value,
  Expires   => 'Sun, 06 Nov 1994 08:49:37 GMT',
  HttpOnly  => 1,
  'Max-Age' => 3600,
  Path      => '/foo',
  SameSite  => 'Strict',
  Secure    => 1,
);

Adds a Set-Cookie response header. No effect after response headers have been rendered.

Note that cookie values should only consist of ASCII characters and may not contain any control characters, space characters, or the characters ",;\. More complex values can be encoded to UTF-8 and base64 for transport.

use Unicode::UTF8 'encode_utf8';
use MIME::Base64 'encode_base64';
my $encoded_value = encode_base64 encode_utf8($value), '';
$cgi->add_response_cookie(foo => $encoded_value, %attrs);

use Unicode::UTF8 'decode_utf8';
use MIME::Base64 'decode_base64';
my $value = decode_utf8 decode_base64 $cgi->cookie('foo');

Data structures can be encoded to JSON and base64 for transport.

use Cpanel::JSON::XS 'encode_json';
use MIME::Base64 'encode_base64';
my $encoded_value = encode_base64 encode_json(\%hash), '';
$cgi->add_response_cookie(foo => $encoded_value, %attrs);

use Cpanel::JSON::XS 'decode_json';
use MIME::Base64 'decode_base64';
my $hashref = decode_json decode_base64 $cgi->cookie('foo');

Optional cookie attributes are specified in key-value pairs after the cookie name and value. Cookie attribute names are case-insensitive.

Domain: Domain for which cookie is valid.
Expires: Expiration date string for cookie. "epoch_to_date" can be used to generate the appropriate date string format.
HttpOnly: If set to a true value, the cookie will be restricted from client-side scripts.
Max-Age: Max age of cookie before it expires, in seconds, as an alternative to specifying Expires.
Path: URL path for which cookie is valid.
SameSite: Strict to restrict the cookie to requests from the same site, Lax to allow it additionally in certain cross-site requests. This attribute is currently part of a draft specification so its handling may change, but it is supported by most browsers.
Secure: If set to a true value, the cookie will be restricted to HTTPS requests.

response_status_code

my $code = $cgi->response_status_code;

Numerical response HTTP status code that will be sent when headers are rendered, as set by "set_response_status" or an error occurring. Defaults to 200.

headers_rendered

my $bool = $cgi->headers_rendered;

Returns true if response headers have been rendered, such as by the first call to "render".

render

$cgi->render;
$cgi->render(html     => $html);
$cgi->render(xml      => $xml);
$cgi->render(text     => $text);
$cgi->render(data     => $bytes);
$cgi->render(file     => $filepath);
$cgi->render(handle   => $filehandle);
$cgi->render(json     => $ref);
$cgi->render(redirect => $url);

Renders response data of a type indicated by the first parameter, if any. The first time it is called will render response headers and set "headers_rendered", and it may be called additional times with more response data.

The Content-Type response header will be set according to "set_response_content_type", or autodetected depending on the data type passed in the first call to render, or to application/octet-stream if there is no more appropriate value.

html, xml, or text data is expected to be decoded Unicode characters, and will be encoded according to "set_response_charset" (UTF-8 by default). Unicode::UTF8 will be used for efficient UTF-8 encoding if available.

data, file, or handle will render bytes from a string, local file path, or open filehandle respectively. A handle will have binmode applied to remove any translation layers, and its contents will be streamed until EOF.

json data structures will be encoded to JSON and UTF-8.

redirect will set a Location header if response headers have not yet been rendered, and will set a response status of 302 if none has been set by "set_response_status". It will not set a Content-Type response header. If response headers have already been rendered a warning will be emitted.

The Date response header will be set to the current time as an HTTP date string if not set manually.

FUNCTIONS

The following convenience functions are provided but not exported.

epoch_to_date

my $date = CGI::Tiny::epoch_to_date $epoch;

Convert a Unix epoch timestamp, such as returned by time, to a RFC 1123 HTTP date string suitable for use in HTTP headers such as Date and Expires.

date_to_epoch

my $epoch = CGI::Tiny::date_to_epoch $date;

Parse a RFC 1123 HTTP date string to a Unix epoch timestamp. For compatibility as required by RFC 7231, legacy RFC 850 and ANSI C asctime date formats are also recognized. Returns undef if the string does not parse as any of these formats.

# RFC 1123
my $epoch = CGI::Tiny::date_to_epoch 'Sun, 06 Nov 1994 08:49:37 GMT';

# RFC 850
my $epoch = CGI::Tiny::date_to_epoch 'Sunday, 06-Nov-94 08:49:37 GMT';

# asctime
my $epoch = CGI::Tiny::date_to_epoch 'Sun Nov  6 08:49:37 1994';

ENVIRONMENT

CGI::Tiny recognizes the following environment variables, in addition to the standard CGI environment variables.

CGI_TINY_REQUEST_BODY_BUFFER

Default value for "set_request_body_buffer".

CGI_TINY_REQUEST_BODY_LIMIT

Default value for "set_request_body_limit".

CGI_TINY_RESPONSE_BODY_BUFFER

Default value for "set_response_body_buffer".

COMPARISON TO CGI.PM

Traditionally, the CGI module (referred to as CGI.pm to differentiate it from the CGI protocol) has been used to write Perl CGI scripts. This module fills a similar need but has a number of interface differences to be aware of.

There is no global CGI::Tiny object; the object is constructed for the scope of the cgi block, only reads request data from the environment once it is accessed, and once the block completes (normally or abnormally), it ensures that a valid response is rendered to avoid gateway errors.
Instead of global variables like $CGI::POST_MAX, global behavior settings are applied to the CGI::Tiny object inside the cgi block.
Exceptions within the cgi block are handled by default by rendering a server error response and emitting the error as a warning. This can be customized with "set_error_handler".
Request query and body parameter accessors in CGI::Tiny are not context sensitive, as context sensitivity can lead to surprising behavior and vulnerabilities. "query_param", "body_param", and "upload" always return a single value; "query_param_array", "body_param_array", and "upload_array" must be used to retrieve multi-value parameters.
CGI::Tiny does not have a method-sensitive param accessor; query and body request parameters are accessed with "query_param" and "body_param" respectively. Uploaded files and their metadata are accessed with "upload" and do not affect the text parameter accessors.
CGI::Tiny decodes request query and body parameters to Unicode characters automatically, and "render" provides methods to encode response data from Unicode characters to UTF-8 by default.
In CGI.pm, response headers must be printed manually before any response data is printed to avoid malformed responses. In CGI::Tiny, the "render" method is used to print response data, and automatically prints response headers the first time it is called. redirect responses are also handled by "render".
In CGI::Tiny, a custom response status is set by calling "set_response_status" before the first "render", which only requires the status code and will add the appropriate human-readable status message itself.
Response setters are distinct methods from request accessors in CGI::Tiny. "content_type", "header", and "cookie" are used to access request data, and "set_response_content_type", "add_response_header", and "add_response_cookie" are used to set response headers for the pending response before the first call to "render".
CGI::Tiny does not provide any HTML generation helpers, as this functionality is much better implemented by other robust implementations on CPAN; see "Templating".
CGI::Tiny does not do any implicit encoding of cookie values or the Expires header or cookie attribute. The "epoch_to_date" convenience function is provided to render appropriate Expires date values.

There are a number of alternatives to CGI.pm but they do not sufficiently address the design issues; primarily, none of them gracefully handle exceptions or failure to render a response, and several of them have no features for rendering responses.

CGI::Simple shares all of the interface design problems of CGI.pm, though it does not reimplement the HTML generation helpers.
CGI::Thin is ancient and only implements parsing of request query or body parameters, without decoding them to Unicode characters.
CGI::Minimal has context-sensitive parameter accessors, and only implements parsing of request query/body parameters (without decoding them to Unicode characters) and uploads.
CGI::Lite has context-sensitive parameter accessors, and only implements parsing of request query/body parameters (without decoding them to Unicode characters), uploads, and cookies.
CGI::Easy has a robust interface, but pre-parses all request information.

CAVEATS

CGI is an extremely simplistic protocol and relies particularly on the global state of environment variables and the STDIN and STDOUT standard filehandles. CGI::Tiny does not prevent you from messing with these interfaces directly, but it may result in confusion.

CGI::Tiny eschews certain sanity checking for performance reasons. For example, Content-Type and other header values set for the response should only contain ASCII text with no control characters, but CGI::Tiny does not verify this (though it does verify they do not contain newline characters to protect against HTTP response splitting).

Field names and filenames in multipart/form-data requests do not have a well-defined escape mechanism for special characters, so CGI::Tiny will not attempt to decode these names from however the client passes them aside from "set_multipart_form_charset". For best compatibility, form field names should be ASCII without double quotes or semicolons.

TODO

Debugging tools

BUGS

Report any issues on the public bugtracker.

AUTHOR

Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)