Provided by: libcgi-tiny-perl_1.002-2_all 
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, $rendered) = @_;
warn $error;
unless ($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' or $method eq 'HEAD') {
$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->param('download')) {
$cgi->set_response_disposition(attachment => 'fribble.json');
}
$cgi->render(json => {fribble => $fribble});
};
DESCRIPTION
CGI::Tiny provides a modern interface to write CGI
<https://en.wikipedia.org/wiki/Common_Gateway_Interface> scripts to dynamically respond to
HTTP requests as defined in RFC 3875 <https://tools.ietf.org/html/rfc3875>. 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 follow best practices and
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".
USAGE
CGI::Tiny's interface is the "cgi" block.
use CGI::Tiny;
cgi {
my $cgi = $_;
# set up error handling on $cgi
# inspect request data via $cgi
# set response headers if needed via $cgi
# render response with $cgi->render or $cgi->render_chunk
};
The 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 block, or the 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.
The default server error will also be rendered if the process ends abnormally between
importing from CGI::Tiny and the start of the "cgi" block. To load CGI::Tiny without
triggering this cleanup mechanism or making the "cgi" block available (such as to use
convenience "FUNCTIONS" in non-CGI code), load the module with "use CGI::Tiny ();" or
"require CGI::Tiny;".
NOTE: 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. Don't call it as "CGI::Tiny::cgi", don't rely on
@_ being set, and don't use "return" to exit the block; use "exit" to end a CGI script
early after rendering a response.
See CGI::Tiny::Cookbook for advanced usage examples.
DATA SAFETY
CGI::Tiny does not provide any special affordances for taint mode as it is overeager,
imprecise, and can significantly impact performance. Web developers should instead
proactively take care not to use any request data (including request headers, form fields,
or other request content) directly in an unsafe manner, as it can make the program
vulnerable to injections that cause undesired or dangerous behavior. The most common
risks to watch out for include:
• System commands
Do not interpolate arbitrary data into a shell command, such as with "system" or
backticks. Data can be safely passed as command arguments using methods that bypass
the shell, such as the list form of "system", or modules like IPC::System::Simple,
IPC::ReadpipeX, and IPC::Run3. If shell features are needed, data can be escaped for
bourne-style shells with String::ShellQuote.
• Database queries
Do not interpolate arbitrary data into database queries. Data can be safely passed to
database queries using placeholders <https://metacpan.org/pod/DBI#Placeholders-and-
Bind-Values>.
• Regex
Do not interpolate arbitrary data into regular expressions, such as the "m//" or
"s///" operators, or the first argument to "split". Data can be safely included in a
regex to match it as an exact string by escaping it with the "quotemeta" function or
equivalent "\Q" escape sequence.
• HTML
Do not interpolate arbitrary data into HTML. Data can be safely included in HTML by
escaping it with "escape_html", or passing it to an HTML template engine with an auto-
escape feature; see "Templating" in CGI::Tiny::Cookbook.
METHODS
The following methods can be called on the CGI::Tiny object provided to the "cgi" block.
Setup
set_error_handler
$cgi = $cgi->set_error_handler(sub {
my ($cgi, $error, $rendered) = @_;
...
});
Sets an error handler to run in the event of an exception or if the script ends without
rendering a response. The handler will be called with the CGI::Tiny object, the error
value, and a boolean indicating whether response headers have been rendered yet.
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. If response
headers have not been rendered, error handlers may inspect "response_status_code" and/or
render some error response. The response status code will be set to 500 when this handler
is called if it has not been set to a specific 400- or 500-level error status.
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.
NOTE: The error handler is only meant for logging and customization of the final error
response in a failed request dispatch; to handle exceptions within standard application
flow without causing an error response, use an exception handling mechanism such as
Syntax::Keyword::Try or Feature::Compat::Try (which will use the new "try" feature if
available).
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_options
$cgi = $cgi->set_multipart_form_options({discard_files => 1, tempfile_args => [SUFFIX => '.dat']});
Set a hash reference of options to pass when parsing a "multipart/form-data" request body
with "parse_multipart_form_data" in CGI::Tiny::Multipart. No effect after the form data
has been parsed such as by calling "body_params" or "uploads" for the first time.
NOTE: Options like "parse_as_files" and "on_file_buffer" can alter the "content" and
"file" keys of the form field structure returned by "body_parts". Thus "uploads" may not
contain "file" and may instead contain "content", and "body_params" text field values may
be read from "file", which will be expected to be a seekable filehandle if present.
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 Environment
CGI::Tiny provides direct access to CGI request meta-variables
<https://tools.ietf.org/html/rfc3875#section-4.1> via methods that map to the equivalent
uppercase names (and a few short aliases). Since CGI does not distinguish between missing
and empty values, missing values will be normalized to an empty string.
auth_type
# AUTH_TYPE="Basic"
my $auth_type = $cgi->auth_type;
The authentication scheme used in the "Authorization" HTTP request header if any.
content_length
# CONTENT_LENGTH="42"
my $content_length = $cgi->content_length;
The size in bytes of the request body content if any.
content_type
# CONTENT_TYPE="text/plain;charset=UTF-8"
my $content_type = $cgi->content_type;
The MIME type of the request body content if any.
gateway_interface
# GATEWAY_INTERFACE="CGI/1.1"
my $gateway_inteface = $cgi->gateway_interface;
The CGI version used for communication with the CGI server.
path_info
path
# PATH_INFO="/foo/42"
my $path = $cgi->path_info;
my $path = $cgi->path;
The URL path following the "SCRIPT_NAME" in the request URL if any.
path_translated
# PATH_TRANSLATED="/var/www/html/foo/42"
my $path_translated = $cgi->path_translated;
A local file path derived from "PATH_INFO" by the CGI server, as if it were a request to
the document root, if it chooses to provide it.
query_string
query
# QUERY_STRING="foo=bar"
my $query = $cgi->query_string;
my $query = $cgi->query;
The query string component of the request URL.
remote_addr
# REMOTE_ADDR="8.8.8.8"
my $remote_addr = $cgi->remote_addr;
The IPv4 or IPv6 address of the requesting client.
remote_host
# REMOTE_HOST="example.com"
my $remote_host = $cgi->remote_host;
The domain name of the requesting client if available, or "REMOTE_ADDR".
remote_ident
# REMOTE_IDENT="someuser"
my $remote_ident = $cgi->remote_ident;
The identity of the client reported by an RFC 1413 ident request if available.
remote_user
# REMOTE_USER="someuser"
my $remote_user = $cgi->remote_user;
The user identity provided as part of an "AUTH_TYPE" authenticated request.
request_method
method
# REQUEST_METHOD="GET"
my $method = $cgi->request_method;
my $method = $cgi->method;
The HTTP request method verb.
script_name
# SCRIPT_NAME="/cgi-bin/script.cgi"
my $script_name = $cgi->script_name;
The host-relative URL path to the CGI script.
server_name
# SERVER_NAME="example.com"
my $server_name = $cgi->server_name;
The hostname of the server as the target of the request, such as from the "Host" HTTP
request header.
server_port
# SERVER_PORT="443"
my $server_port = $cgi->server_port;
The TCP port on which the server received the request.
server_protocol
# SERVER_PROTOCOL="HTTP/1.1"
my $server_protocol = $cgi->server_protocol;
The HTTP protocol version of the request.
server_software
# SERVER_SOFTWARE="Apache\/2.4.37 (centos)"
my $server_software = $cgi->server_software;
The name and version of the CGI server.
Request Parsing
headers
my $hashref = $cgi->headers;
Hash reference of available request header names and values. Header names are represented
in lowercase.
header
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, without duplication.
cookie
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.
params
my $pairs = $cgi->params;
Retrieve URL query string parameters and "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.
Query parameters are returned first, followed by body parameters. Use "query_params" or
"body_params" to retrieve query or body parameters separately.
NOTE: This will read the text form fields into memory as in "body_params".
param_names
my $arrayref = $cgi->param_names;
Retrieve URL query string parameter names and "application/x-www-form-urlencoded" or
"multipart/form-data" body parameter names, decoded to Unicode characters, as an ordered
array reference, without duplication.
Query parameter names are returned first, followed by body parameter names. Use
"query_param_names" or "body_param_names" to retrieve query or body parameter names
separately.
NOTE: This will read the text form fields into memory as in "body_params".
param
my $value = $cgi->param('foo');
Retrieve value of a named URL query string parameter or
"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 body parameter value if
any, otherwise the last query parameter value. Use "param_array" to get multiple values of
a parameter, or "query_param" or "body_param" to retrieve the last query or body parameter
value specifically.
NOTE: This will read the text form fields into memory as in "body_params".
param_array
my $arrayref = $cgi->param_array('foo');
Retrieve values of a named URL query string parameter or
"application/x-www-form-urlencoded" or "multipart/form-data" body parameter, decoded to
Unicode characters, as an ordered array reference.
Query parameter values will be returned first, followed by body parameter values. Use
"query_param_array" or "body_param_array" to retrieve query or body parameter values
separately.
NOTE: This will read the text form fields into memory as in "body_params".
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, without duplication.
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.
body
my $bytes = $cgi->body;
Retrieve the request body as bytes.
NOTE: 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_json
my $data = $cgi->body_json;
Decode an "application/json" request body from UTF-8-encoded JSON.
NOTE: 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_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: This will read the text form fields into memory, so make sure the
"set_request_body_limit" can fit well within the available memory. "multipart/form-data"
file uploads will be streamed to temporary files accessible via "uploads" and related
methods.
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, without duplication.
NOTE: This will read the text form fields into memory as in "body_params".
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: This will read the text form fields into memory as in "body_params".
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: This will read the text form fields into memory as in "body_params".
body_parts
my $parts = $cgi->body_parts;
Retrieve "multipart/form-data" request body parts as an ordered array reference using
"parse_multipart_form_data" in CGI::Tiny::Multipart. Most applications should retrieve
multipart form data through "body_params" and "uploads" (or related accessors) instead.
NOTE: 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 will be
streamed to temporary files.
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: 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, without duplication.
NOTE: This will read the text form fields into memory as in "uploads".
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: This will read the text form fields into memory as in "uploads".
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: This will read the text form fields into memory as in "uploads".
Response
set_nph
$cgi = $cgi->set_nph;
$cgi = $cgi->set_nph(1);
If set to a true value or called without a value before rendering response headers,
CGI::Tiny will act as a NPH (Non-Parsed Header)
<https://tools.ietf.org/html/rfc3875#section-5> 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" or "render_chunk". 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
<https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml> 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_disposition
$cgi = $cgi->set_response_disposition('attachment');
$cgi = $cgi->set_response_disposition(attachment => $filename);
$cgi = $cgi->set_response_disposition('inline'); # default behavior
$cgi = $cgi->set_response_disposition(inline => $filename);
Sets the response "Content-Disposition" header to indicate how the client should present
the response, with an optional filename specified in Unicode characters. "attachment"
suggests to download the content as a file, and "inline" suggests to display the content
inline (the default behavior). No effect after response headers have been rendered.
set_response_type
$cgi = $cgi->set_response_type('application/xml');
Sets the response "Content-Type" header, to override autodetection in "render" or
"render_chunk". "undef" will remove the override. 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 content, defaults to
"UTF-8".
add_response_header
$cgi = $cgi->add_response_header('Content-Language' => 'en');
Adds a custom response header. No effect after response headers have been rendered.
NOTE: 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.
Cookie values should consist only of simple ASCII text; see "Cookies" in
CGI::Tiny::Cookbook for methods of storing more complex strings and data structures.
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. Defaults to the host of the current document URL,
not including subdomains.
Expires
Expiration date string for cookie. Defaults to persisting for the current browser
session. "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.
reset_response_headers
$cgi = $cgi->reset_response_headers;
Remove any pending response headers set by "add_response_header" or "add_response_cookie".
No effect after response headers have been rendered.
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.
render
$cgi = $cgi->render; # default Content-Type:
$cgi = $cgi->render(text => $text); # text/plain;charset=$charset
$cgi = $cgi->render(html => $html); # text/html;charset=$charset
$cgi = $cgi->render(xml => $xml); # application/xml;charset=$charset
$cgi = $cgi->render(json => $ref); # application/json;charset=UTF-8
$cgi = $cgi->render(data => $bytes); # application/octet-stream
$cgi = $cgi->render(file => $filepath); # application/octet-stream
$cgi = $cgi->render(redirect => $url);
Renders response headers and then fixed-length response content of a type indicated by the
first parameter, if any. A "Content-Length" header will be set to the length of the
encoded response content, and further calls to "render" or "render_chunk" will throw an
exception. Use "render_chunk" instead to render without a "Content-Length" header.
The "Content-Type" response header will be set according to "set_response_type", or
autodetected depending on the data type of any non-empty response content passed.
The "Date" response header will be set to the current time as an HTTP date string if not
set manually.
If the "request_method" is "HEAD", any provided response content will be ignored (other
than redirect URLs) and "Content-Length" will be set to 0.
"text", "html", or "xml" 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.
"json" data structures will be encoded to JSON and UTF-8.
"data" or "file" will render bytes from a string or local file path respectively. A
"handle", or a "file" whose size cannot be determined accurately from the filesystem, must
be rendered using "render_chunk" since its "Content-Length" cannot be determined
beforehand.
"redirect" will set a "Location" header to redirect the client to another URL. The
response status will be set to 302 Found unless a different 300-level status has been set
with "set_response_status". It will set a "Content-Length" of 0, and it will not set a
"Content-Type" response header.
render_chunk
$cgi = $cgi->render_chunk; # default Content-Type:
$cgi = $cgi->render_chunk(text => $text); # text/plain;charset=$charset
$cgi = $cgi->render_chunk(html => $html); # text/html;charset=$charset
$cgi = $cgi->render_chunk(xml => $xml); # application/xml;charset=$charset
$cgi = $cgi->render_chunk(json => $ref); # application/json;charset=UTF-8
$cgi = $cgi->render_chunk(data => $bytes); # application/octet-stream
$cgi = $cgi->render_chunk(file => $filepath); # application/octet-stream
$cgi = $cgi->render_chunk(handle => $filehandle); # application/octet-stream
Renders response headers the first time it is called, and then chunked response content of
a type indicated by the first parameter, if any. No "Content-Length" header will be set,
and "render_chunk" may be called additional times with more response content.
"render_chunk" does not impose a chunked response, it simply does not generate a
"Content-Length" header. For content where the total encoded content length is known in
advance but the content can't be passed to a single "render" call, a "Content-Length"
header can be set manually with "add_response_header", and then "render_chunk" may be used
to render each part.
The "Content-Type" response header will be set according to "set_response_type", or
autodetected depending on the data type passed in the first call to "render_chunk", or to
"application/octet-stream" if there is no more appropriate value. It will be set even if
no content is passed to the first "render_chunk" call, in case content is rendered in
subsequent calls.
The "Date" response header will be set to the current time as an HTTP date string if not
set manually.
If the "request_method" is "HEAD", any provided response content will be ignored.
"text", "html", or "xml" 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.
"json" data structures will be encoded to JSON and UTF-8.
"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.
"redirect" responses must be rendered with "render".
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 <https://tools.ietf.org/html/rfc7231#section-7.1.1.1>, 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';
escape_html
my $escaped = CGI::Tiny::escape_html $text;
Escapes characters that are unsafe for embedding in HTML text. The characters "&<>"'" will
each be replaced with the corresponding HTML character reference (HTML entity).
This functionality is built into most HTML template engines; see "Templating" in
CGI::Tiny::Cookbook. For more general HTML entity escaping and unescaping use
HTML::Entities.
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".
DEBUGGING COMMANDS
CGI::Tiny scripts can be executed from the commandline for debugging purposes. A command
can be passed as the first argument to help set up the CGI environment.
These commands are considered a development interface and come with no stability
guarantee.
$ ./script.cgi get '/?foo=bar'
$ ./script.cgi head
$ ./script.cgi post '/form' -C 'one=value' -C 'two=value' --content='foo=bar+baz'
-H 'Content-Type: application/x-www-form-urlencoded'
$ ./script.cgi put -H "Content-Length: $(stat --printf='%s' foo.dat)"
-H "Content-Type: $(file -bi foo.dat)" <foo.dat
$ ./script.cgi delete -v '/item/42'
The "get", "head", "post", "put", and "delete" commands will emulate a request of the
specified "request_method". A following URL parameter will be passed as the "path_info"
and "query_string" if present.
Request content may be provided through STDIN but the "Content-Length" request header must
be set to the size of the input as required by the CGI spec.
The response will be printed to STDOUT as normal. You may wish to redirect the output of
the command to a file or hexdump program if the response is expected not to be printable
text in the character encoding of your terminal.
Options may follow the command:
--content=<string>, -c <string>
Passes the string value as request body content and sets the "Content-Length" request
header to its size.
--cookie=<string>, -C <string>
String values of the form "name=value" will be passed as request cookies. Can appear
multiple times.
--header=<string>, -H <string>
String values of the form "Name: value" will be passed as request headers. Can appear
multiple times. If the same header name is provided multiple times, the values will be
joined with commas, which is only valid for certain headers.
--verbose, -v
Includes response CGI headers (or HTTP headers in NPH mode) in the output before
response content. Enabled automatically for "head".
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 CGI::Tiny object constructor; the object is accessible within the "cgi"
block, only reads request data from the environment once it is accessed, and ensures
that a valid response is rendered to avoid gateway errors even in the event of an
exception or premature exit.
• 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 parameter accessors in CGI::Tiny are not context sensitive, as context
sensitivity can lead to surprising behavior and vulnerabilities
<https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-1572>. "param",
"query_param", "body_param", and "upload" always return a single value; "param_array",
"query_param_array", "body_param_array", and "upload_array" must be used to retrieve
multi-value parameters.
• CGI::Tiny's "param" accessor is also not method-sensitive; it accesses either query or
body request parameters with the same behavior regardless of request method, and query
and body request parameters can be accessed separately with "query_param" and
"body_param" respectively.
• CGI::Tiny's "param" accessor only retrieves text parameters; uploaded files and their
metadata are accessed with "upload" and related methods.
• CGI::Tiny decodes request parameters to Unicode characters automatically, and
"render"/"render_chunk" provide methods to encode response content from Unicode
characters to UTF-8 by default.
• In CGI.pm, response headers must be printed manually before any response content is
printed to avoid malformed responses. In CGI::Tiny, the "render" or "render_chunk"
methods are used to print response content, and automatically print response headers
when first 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" or "render_chunk", 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_type", "add_response_header", and "add_response_cookie" are used to set
response headers for the pending response before the first call to "render" or
"render_chunk".
• CGI::Tiny does not provide any HTML generation helpers, as this functionality is much
better implemented by other robust implementations on CPAN; see "Templating" in
CGI::Tiny::Cookbook.
• 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.
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2021 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
SEE ALSO
CGI::Alternatives, Mojolicious, Dancer2