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

    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.

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

    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.

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

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.

 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}));
    
        # or 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}));
    
        # or 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>

 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 (usually UTF-8), but this module works with parameters in
    Unicode characters, 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;
      use Unicode::UTF8 qw(encode_utf8 decode_utf8);
    
      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 $encoded_filename = encode_utf8 $filename;
        my $filepath = $public_dir->child($encoded_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 $basename = decode_utf8 $filepath->basename;
        my $mime = MIME::Types->new->mimeTypeOf($basename);
        $cgi->set_response_type($mime->type) if defined $mime;
        $cgi->set_response_disposition(attachment => $basename)->render(file => $filepath);
      };

 Sessions

    Basic authentication
    <https://en.wikipedia.org/wiki/Basic_access_authentication> has
    historically been used to provide a simplistic login session mechanism
    which relies on the client to send the credentials with every
    subsequent request in that browser session. However, it does not have a
    reliable logout or session expiration mechanism.

      #!/usr/bin/perl
      use strict;
      use warnings;
      use utf8;
      use CGI::Tiny;
      use MIME::Base64 qw(encode_base64 decode_base64);
      use Unicode::UTF8 'decode_utf8';
    
      cgi {
        my $cgi = $_;
    
        my $authed_user;
        if (defined(my $auth = $cgi->header('Authorization'))) {
          if (my ($hash) = $auth =~ m/^Basic (\S+)/i) {
            my ($user, $pass) = split /:/, decode_utf8(decode_base64($hash)), 2;
            $authed_user = $user if verify_password($user, $pass);
          }
        }
    
        unless (defined $authed_user) {
          $cgi->add_response_header('WWW-Authenticate' => 'Basic realm="My Website", charset="UTF-8"');
          $cgi->set_response_status(401)->render;
          exit;
        }
    
        # do authed stuff
      };

    A more sophisticated login session mechanism is to store a session
    cookie in the client, associated with a server-side session stored in a
    file or database. Login credentials only need to be validated once per
    session, and subsequently the session ID stored in the cookie will be
    sent by the client with each request. This type of session can be ended
    by expiring the session cookie and invalidating the session data on the
    server.

      #!/usr/bin/perl
      use strict;
      use warnings;
      use utf8;
      use CGI::Tiny;
    
      cgi {
        my $cgi = $_;
    
        my ($authed_user, $session_id);
        if ($cgi->path eq '/login') {
          if ($cgi->method eq 'GET' or $cgi->method eq 'HEAD') {
            $cgi->render(html => login_form_template(login_failed => 0));
            exit;
          } elsif ($cgi->method eq 'POST') {
            my $user = $cgi->body_param('login_user');
            my $pass = $cgi->body_param('login_pass');
            if (verify_password($user, $pass)) {
              $session_id = store_new_session($user);
              $authed_user = $user;
            } else {
              $cgi->render(html => login_form_template(login_failed => 1));
              exit;
            }
          }
        } elsif (defined($session_id = $cgi->cookie('myapp_session'))) {
          if ($cgi->path eq '/logout') {
            invalidate_session($session_id);
            # expire session cookie
            $cgi->add_response_cookie(myapp_session => $session_id, 'Max-Age' => 0, Path => '/', HttpOnly => 1);
            $cgi->render(redirect => $cgi->script_name . '/login');
            exit;
          } else {
            $authed_user = get_session_user($session_id);
          }
        }
    
        unless (defined $authed_user) {
          $cgi->render(redirect => $cgi->script_name . '/login');
          exit;
        }
    
        # set/refresh session cookie
        $cgi->add_response_cookie(myapp_session => $session_id, 'Max-Age' => 3600, Path => '/', HttpOnly => 1);
    
        # do authed stuff
      };

    Regardless of the session mechanism, login credentials should only be
    sent over HTTPS, and passwords should be stored on the server using a
    secure one-way hash, such as with Crypt::Passphrase.

 Logging

    CGI scripts can usually log errors directly to STDERR with the warn
    function, and rely on the CGI server to log them to a file, but you
    will likely need to encode errors to UTF-8 if you expect them to
    contain non-ASCII text.

    Minimal loggers like Log::Any can also be used to redirect errors and
    warnings to a file or other logging mechanism specific to the CGI
    script, encode them to bytes automatically, and also log debugging
    information when the log level is set to debug. Just make sure the CGI
    server has permission to create and write to the logging target.

      #!/usr/bin/perl
      use strict;
      use warnings;
      use utf8;
      use CGI::Tiny;
      use Log::Any;
      use Log::Any::Adapter
        {category => 'cgi-script'}, # only log our category here
        File => '/path/to/log/file.log',
        binmode => ':encoding(UTF-8)',
        log_level => $ENV{MY_CGI_LOG_LEVEL} || 'info';
    
      my $log = Log::Any->get_logger(category => 'cgi-script');
    
      local $SIG{__WARN__} = sub {
        my ($warning) = @_;
        chomp $warning;
        $log->warn($warning);
      };
    
      cgi {
        my $cgi = $_;
    
        $cgi->set_error_handler(sub {
          my ($cgi, $error, $rendered) = @_;
          chomp $error;
          $log->error($error);
        });
    
        # only logged if MY_CGI_LOG_LEVEL=debug set in CGI server environment
        $log->debugf('Method: %s, Path: %s, Query: %s', $cgi->method, $cgi->path, $cgi->query);
    
        # handle the actual request
      };

 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, $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 that 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_discard_form_files

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

    If set to a true value or called without a value before parsing a
    multipart/form-data request body, file upload contents will be
    discarded and thus "uploads" will not contain a file. Defaults to the
    value of the CGI_TINY_DISCARD_FORM_FILES environment variable.

  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.

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

    Query parameter names are returned first, followed by body parameter
    names (without duplication). Use "query_param_names" or
    "body_param_names" to retrieve query or body parameter names
    separately.

    Note that 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 that 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 that 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.

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

    Note that 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 that 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 that 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 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 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 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 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 that 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 that 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 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.

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

      * 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