NAME

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

SYNOPSIS

      #!/usr/bin/perl
      use strict;
      use warnings;
      use CGI::Tiny;
    
      cgi {
        my $cgi = $_;
        $cgi->set_error_handler(sub {
          my ($cgi, $error) = @_;
          warn $error;
          $cgi->render(json => {error => 'Internal Error'}) unless $cgi->headers_rendered;
        });
        my $method = $cgi->method;
        my $fribble;
        if ($method eq 'GET') {
          $fribble = $cgi->query_param('fribble');
        } elsif ($method eq 'POST') {
          $fribble = $cgi->body_param('fribble');
        } else {
          $cgi->set_response_status(405);
          $cgi->render;
          exit;
        }
        die "Invalid fribble parameter" unless length $fribble;
        $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. It is intended to be:

      * Minimal

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

      * Simple

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

      * Robust

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

      * Lazy

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

      * Restrained

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

      * Flexible

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

    See "COMPARISON TO CGI.PM".

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

USAGE

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

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

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

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

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

EXTENDING

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

 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}));
    
        # from __DATA__
        my $template = get_data_section 'index.tx';
        $cgi->render(html => $tx->render_string($template, {foo => $foo}));
      };
    
      __DATA__
      @@ index.tx
      <html><body><h1><: $foo :></h1></body></html>

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

      #!/usr/bin/perl
      use strict;
      use warnings;
      use utf8;
      use CGI::Tiny;
      use Mojo::Template;
      use Mojo::File 'curfile';
      use Mojo::Loader 'data_section';
    
      cgi {
        my $cgi = $_;
        my $foo = $cgi->query_param('foo');
        my $mt = Mojo::Template->new(auto_escape => 1, vars => 1);
    
        # from templates/
        my $template_path = curfile->sibling('templates', 'index.html.ep');
        $cgi->render(html => $mt->render_file($template_path, {foo => $foo}));
    
        # from __DATA__
        my $template = data_section __PACKAGE__, 'index.html.ep';
        $cgi->render(html => $mt->render($template, {foo => $foo}));
      };
    
      __DATA__
      @@ index.html.ep
      <html><body><h1><%= $foo %></h1></body></html>

 Routing

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

      #!/usr/bin/perl
      use strict;
      use warnings;
      use 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);
          $cgi->render(text => 'Not Found');
        }
      };

METHODS

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

 Setup

  set_error_handler

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

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

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

    Exceptions may occur before or after response headers have been
    rendered, so error handlers should render some response if
    "headers_rendered" is false. If no response has been rendered after the
    error handler completes, the default 500 Internal Server Error response
    will be rendered.

  set_request_body_limit

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

    Sets the limit in bytes for parsing a request body into memory. If not
    set, defaults to the value of the CGI_TINY_REQUEST_BODY_LIMIT
    environment variable or 16777216 (16 MiB). Since the request body is
    not parsed until needed, methods that parse the whole request body into
    memory like "body" will set the response status to 413 Payload Too
    Large and throw an exception if the content length is over the limit. A
    value of 0 will remove the limit (not recommended unless you have other
    safeguards on memory usage).

  set_input_handle

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

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

  set_output_handle

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

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

 Request

  auth_type

  content_length

  content_type

  gateway_interface

  path_info

  path_translated

  query_string

  remote_addr

  remote_host

  remote_ident

  remote_user

  request_method

  script_name

  server_name

  server_port

  server_protocol

  server_software

      my $type   = $cgi->content_type;   # CONTENT_TYPE
      my $method = $cgi->request_method; # REQUEST_METHOD
      my $port   = $cgi->server_port;    # SERVER_PORT

    Access to request meta-variables
    <https://tools.ietf.org/html/rfc3875#section-4.1> of the equivalent
    uppercase names. Since CGI does not distinguish between missing and
    empty values, missing values will be normalized to an empty string.

  method

  path

  query

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

    Short aliases for a few request meta-variables.

  query_pairs

      my $pairs = $cgi->query_pairs;

    Retrieve URL query string parameters as an array reference of
    two-element array references.

  query_params

      my $params = $cgi->query_params;

    Retrieve URL query string parameters as a hash reference. If a
    parameter name is passed multiple times, its value will be an array
    reference.

  query_param

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

    Retrieve value of a named URL query string parameter. If the parameter
    name is 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 as an array
    reference.

  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');

    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 $hashref = $cgi->cookies;

    Hash reference of request cookie names and values.

  cookie

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

    Retrieve the value of a request cookie by name.

  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.

  body_pairs

      my $pairs = $cgi->body_pairs;

    Retrieve x-www-form-urlencoded body parameters as an array reference of
    two-element array references.

    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 $params = $cgi->body_params;

    Retrieve x-www-form-urlencoded body parameters as a hash reference. If
    a parameter name is passed multiple times, its value will be an array
    reference.

    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_param

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

    Retrieve value of a named x-www-form-urlencoded body parameter. If the
    parameter name is passed multiple times, returns the last value. Use
    "body_param_array" to get multiple values of a parameter.

    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_param_array

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

    Retrieve values of a named x-www-form-urlencoded body parameter as an
    array reference.

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

 Response

  set_response_status

      $cgi = $cgi->set_response_status(404);

    Sets the response HTTP status code. No effect after response headers
    have been rendered. The CGI protocol assumes a status of 200 OK if no
    response status is set.

  set_response_content_type

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

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

  add_response_header

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

    Adds a 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 response cookie. 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 Encode 'encode';
      use MIME::Base64 'encode_base64';
      $cgi->add_response_cookie(foo => encode_base64(encode('UTF-8', $value), ''));
    
      use Encode 'decode';
      use MIME::Base64 'decode_base64';
      my $value = decode 'UTF-8', decode_base64 $cgi->cookie('foo');

    Structures can be encoded to JSON and base64 for transport.

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

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

    Domain

      Domain for which cookie is valid.

    Expires

      Expiration date string for cookie. "epoch_to_date" can be used to
      generate the appropriate date string format.

    HttpOnly

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

    Max-Age

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

    Path

      URL path for which cookie is valid.

    SameSite

      Strict to restrict the cookie to requests from the same site, Lax to
      allow it additionally in certain cross-site requests. This attribute
      is currently part of a draft specification so its handling may
      change, but it is supported by most browsers.

    Secure

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

  response_charset

      my $charset = $cgi->response_charset;

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

  set_response_charset

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

    Sets "response_charset".

  set_nph

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

    If set to a true value before rendering response headers, CGI::Tiny
    will act as a NPH (Non-Parsed Header)
    <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.

  headers_rendered

      my $bool = $cgi->headers_rendered;

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

  render

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

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

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

    html, xml, or text data is expected to be decoded characters, and will
    be encoded according to "response_charset". json data will be encoded
    to UTF-8.

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

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

FUNCTIONS

    The following convenience functions are provided but not exported.

 epoch_to_date

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

    Convert a Unix epoch timestamp 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';

ENVIRONMENT

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

 CGI_TINY_REQUEST_BODY_LIMIT

    Default value for "set_request_body_limit".

COMPARISON TO CGI.PM

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

      * There is no global CGI::Tiny object; the object is constructed for
      the scope of the cgi block, only reads request data from the
      environment once it is accessed, and once the block completes
      (normally or abnormally), it ensures that a valid response is
      rendered to avoid gateway errors.

      * Instead of global variables like $CGI::POST_MAX, global behavior
      settings are applied to the CGI::Tiny object inside the cgi block.

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

      * Request query and body parameter accessors in CGI::Tiny are not
      context sensitive. "query_param" and "body_param" always return a
      single value, and "query_param_array" and "body_param_array" must be
      used to retrieve multi-value parameters. CGI::Tiny also does not have
      a method-sensitive param accessor; query or body parameters must be
      accessed specifically.

      * CGI::Tiny decodes request query and body parameters from UTF-8 to
      Unicode characters by default, and "render" provides methods to
      encode response data from Unicode characters to UTF-8 or other
      charsets automatically.

      * In CGI.pm, response headers must be printed manually before any
      response data is printed to avoid malformed responses. In CGI::Tiny,
      the "render" method is used to print response data, and automatically
      prints response headers the first time it is called. redirect
      responses are also handled by "render".

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

      * Response setters are distinct methods from request accessors in
      CGI::Tiny. "content_type", "header", and "cookie" are used to access
      request data, and "set_response_content_type", "add_response_header",
      and "add_response_cookie" are used to set response headers for the
      pending response before the first call to "render".

      * CGI::Tiny does not provide any HTML templating 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.

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.

    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.

TODO

      * Uploads/multipart request

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

