Cook results from the CPAN

CGI-Tiny

=item * 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.

=item * 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.

=back

Most applications are better written in a L<PSGI>-compatible framework (e.g.
L<Dancer2> or L<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 L</"COMPARISON TO CGI.PM">.

=head1 USAGE

=for Pod::Coverage cgi

CGI::Tiny's interface is the C<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 C<$_> set to a CGI::Tiny object, which
L</"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 L</"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 C<cgi> block. To load
CGI::Tiny without triggering this cleanup mechanism or making the C<cgi> block
available (such as to use convenience L</"FUNCTIONS"> in non-CGI code), load
the module with C<use CGI::Tiny ();> or C<require CGI::Tiny;>.

B<NOTE:> The C<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 C<CGI::Tiny::cgi>, don't rely on C<@_> being set, and don't use C<return>
to exit the block; use C<exit> to end a CGI script early after rendering a
response.

See L<CGI::Tiny::Cookbook> for advanced usage examples.

=head1 DATA SAFETY

CGI::Tiny does not provide any special affordances for
L<taint mode|perlsec/"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:

=over

=item * System commands

Do not interpolate arbitrary data into a shell command, such as with C<system>
or backticks. Data can be safely passed as command arguments using methods that
bypass the shell, such as the list form of C<system>, or modules like
L<IPC::System::Simple>, L<IPC::ReadpipeX>, and L<IPC::Run3>. If shell features
are needed, data can be escaped for bourne-style shells with
L<String::ShellQuote>.

=item * Database queries

Do not interpolate arbitrary data into database queries. Data can be safely
passed to database queries using
L<placeholders|https://metacpan.org/pod/DBI#Placeholders-and-Bind-Values>.

=item * Regex

Do not interpolate arbitrary data into regular expressions, such as the C<m//>
or C<s///> operators, or the first argument to C<split>. Data can be safely
included in a regex to match it as an exact string by escaping it with
the C<quotemeta> function or equivalent C<\Q> escape sequence.

=item * HTML

Do not interpolate arbitrary data into HTML. Data can be safely included in
HTML by escaping it with L</"escape_html">, or passing it to an HTML template
engine with an auto-escape feature; see L<CGI::Tiny::Cookbook/"Templating">.

=back

=head1 METHODS

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

=head2 Setup

=head3 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
L</"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.

B<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 L<Syntax::Keyword::Try> or L<Feature::Compat::Try>
(which will use the new C<try> feature if available).

=head3 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 C<CGI_TINY_REQUEST_BODY_BUFFER> environment
variable or 262144 (256 KiB). A value of 0 will use the default value.

=head3 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
C<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

lib/CGI/Tiny.pod view on Meta::CPAN

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
L<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 C<200 OK> if no response status is set.

=head3 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 C<Content-Disposition> header to indicate how the client
should present the response, with an optional filename specified in Unicode
characters. C<attachment> suggests to download the content as a file, and
C<inline> suggests to display the content inline (the default behavior). No
effect after response headers have been rendered.

=head3 set_response_type

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

Sets the response C<Content-Type> header, to override autodetection in
L</"render"> or L</"render_chunk">. C<undef> will remove the override. No
effect after response headers have been rendered.

=head3 set_response_charset

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

Set charset to use when rendering C<text>, C<html>, or C<xml> response content,
defaults to C<UTF-8>.

=head3 add_response_header

  $cgi = $cgi->add_response_header('Content-Language' => 'en');

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

B<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.

=head3 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 C<Set-Cookie> response header. No effect after response headers have
been rendered.

Cookie values should consist only of simple ASCII text; see
L<CGI::Tiny::Cookbook/"Cookies"> 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.

=over

=item Domain

Domain for which cookie is valid. Defaults to the host of the current document
URL, not including subdomains.

=item Expires

Expiration date string for cookie. Defaults to persisting for the current
browser session. L</"epoch_to_date"> can be used to generate the appropriate
date string format.

=item HttpOnly

If set to a true value, the cookie will be restricted from client-side scripts.

=item Max-Age

Max age of cookie before it expires, in seconds, as an alternative to
specifying C<Expires>.

=item Path

URL path for which cookie is valid.

=item SameSite

C<Strict> to restrict the cookie to requests from the same site, C<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.

=item Secure

If set to a true value, the cookie will be restricted to HTTPS requests.

=back

=head3 reset_response_headers

  $cgi = $cgi->reset_response_headers;

Remove any pending response headers set by L</"add_response_header"> or
L</"add_response_cookie">. No effect after response headers have been rendered.

=head3 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 L</"set_response_status"> or an error occurring. Defaults
to C<200>.

=head3 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

lib/CGI/Tiny.pod view on Meta::CPAN

is no more appropriate value. It will be set even if no content is passed to
the first C<render_chunk> call, in case content is rendered in subsequent
calls.

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

If the L</"request_method"> is C<HEAD>, any provided response content will be
ignored.

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

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

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

C<redirect> responses must be rendered with L</"render">.

=head1 FUNCTIONS

The following convenience functions are provided but not exported.

=head2 epoch_to_date

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

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

=head2 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 L<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
C<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';

=head2 escape_html

  my $escaped = CGI::Tiny::escape_html $text;

Escapes characters that are unsafe for embedding in HTML text. The characters
C<&E<lt>E<gt>"'> will each be replaced with the corresponding HTML character
reference (HTML entity).

This functionality is built into most HTML template engines; see
L<CGI::Tiny::Cookbook/"Templating">. For more general HTML entity escaping and
unescaping use L<HTML::Entities>.

=head1 ENVIRONMENT

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

=over

=item CGI_TINY_REQUEST_BODY_BUFFER

Default value for L</"set_request_body_buffer">.

=item CGI_TINY_REQUEST_BODY_LIMIT

Default value for L</"set_request_body_limit">.

=item CGI_TINY_RESPONSE_BODY_BUFFER

Default value for L</"set_response_body_buffer">.

=back

=head1 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 C<get>, C<head>, C<post>, C<put>, and C<delete> commands will emulate a
request of the specified L</"request_method">. A following URL parameter will
be passed as the L</"path_info"> and L</"query_string"> if present.

Request content may be provided through STDIN but the C<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:

=over

=item --content=<string>, -c <string>

Passes the string value as request body content and sets the C<Content-Length>
request header to its size.

lib/CGI/Tiny.pod view on Meta::CPAN


Exceptions within the C<cgi> block are handled by default by rendering a server
error response and emitting the error as a warning. This can be customized with
L</"set_error_handler">.

=item *

Request parameter accessors in CGI::Tiny are not context sensitive, as context
sensitivity can lead to surprising behavior and
L<vulnerabilities|https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-1572>.
L</"param">, L</"query_param">, L</"body_param">, and L</"upload"> always
return a single value; L</"param_array">, L</"query_param_array">,
L</"body_param_array">, and L</"upload_array"> must be used to retrieve
multi-value parameters.

=item *

CGI::Tiny's L</"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 L</"query_param"> and L</"body_param"> respectively.

=item *

CGI::Tiny's L</"param"> accessor only retrieves text parameters; uploaded
files and their metadata are accessed with L</"upload"> and related methods.

=item *

CGI::Tiny decodes request parameters to Unicode characters automatically, and
L</"render">/L</"render_chunk"> provide methods to encode response content from
Unicode characters to UTF-8 by default.

=item *

In CGI.pm, response headers must be printed manually before any response
content is printed to avoid malformed responses. In CGI::Tiny, the L</"render">
or L</"render_chunk"> methods are used to print response content, and
automatically print response headers when first called. C<redirect> responses
are also handled by L</"render">.

=item *

In CGI::Tiny, a custom response status is set by calling
L</"set_response_status"> before the first L</"render"> or L</"render_chunk">,
which only requires the status code and will add the appropriate human-readable
status message itself.

=item *

Response setters are distinct methods from request accessors in CGI::Tiny.
L</"content_type">, L</"header">, and L</"cookie"> are used to access request
data, and L</"set_response_type">, L</"add_response_header">, and
L</"add_response_cookie"> are used to set response headers for the pending
response before the first call to L</"render"> or L</"render_chunk">.

=item *

CGI::Tiny does not provide any HTML generation helpers, as this functionality
is much better implemented by other robust implementations on CPAN; see
L<CGI::Tiny::Cookbook/"Templating">.

=item *

CGI::Tiny does not do any implicit encoding of cookie values or the C<Expires>
header or cookie attribute. See L<CGI::Tiny::Cookbook/"Cookies"> for examples
of encoding and decoding cookie values. The L</"epoch_to_date"> convenience
function is provided to render appropriate C<Expires> date values.

=back

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.

=over

=item *

L<CGI::Simple> shares all of the interface design problems of CGI.pm, though it
does not reimplement the HTML generation helpers.

=item *

L<CGI::Thin> is ancient and only implements parsing of request query or body
parameters, without decoding them to Unicode characters.

=item *

L<CGI::Minimal> has context-sensitive parameter accessors, and only implements
parsing of request query/body parameters (without decoding them to Unicode
characters) and uploads.

=item *

L<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.

=item *

L<CGI::Easy> has a robust interface, but pre-parses all request information.

=back

=head1 CAVEATS

CGI is an extremely simplistic protocol and relies particularly on the global
state of environment variables and the C<STDIN> and C<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,
C<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 C<multipartE<sol>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
L</"set_multipart_form_charset">. For best compatibility, form field names
should be ASCII without double quotes or semicolons.

=head1 BUGS

( run in 0.607 second using v1.01-cache-2.11-cpan-39bf76dae61 )