NAME

       Mojolicious::Plugin::CGI - Run CGI script from Mojolicious

VERSION

       0.25

DESCRIPTION

       This plugin enable Mojolicious to run Perl CGI scripts. It does so by forking a new
       process with a modified environment and reads the STDOUT in a non-blocking manner.

SYNOPSIS

   Standard usage
         use Mojolicious::Lite;
         plugin CGI => [ "/cgi-bin/script" => "/path/to/cgi/script.pl" ];

       Using the code above is enough to run "script.pl" when accessing
       <http://localhost:3000/cgi-bin/script>.

   Complex usage
         plugin CGI => {
           # Specify the script and mount point
           script => "/path/to/cgi/script.pl",
           route  => "/some/route",

           # %ENV variables visible from inside the CGI script
           env => {}, # default is \%ENV

           # Path to where STDERR from cgi script goes
           errlog => "/path/to/file.log",

           # The "before" hook is called before script start
           # It receives a Mojolicious::Controller which can be modified
           before => sub {
             my $c = shift;
             $c->req->url->query->param(a => 123);
           },
         };

       The above contains all the options you can pass on to the plugin.

   Running code refs
         plugin CGI => {
           route => "/some/path",
           run   => sub {
             my $cgi = CGI->new;
             # ...
           }
         };

       Instead of calling a script, you can run a code block when accessing the route.  This is
       (pretty much) safe, even if the code block modifies global state, since it runs in a
       separate fork/process.

   Support for semicolon in query string
         plugin CGI => {
           support_semicolon_in_query_string => 1,
           ...
         };

       The code above need to be added before other plugins or handler which use "url" in
       Mojo::Message::Request. It will inject a "before_dispatch" hook which saves the original
       QUERY_STRING, before it is split on "&" in Mojo::Parameters.

ATTRIBUTES

   env
       Holds a hash ref containing the environment variables that should be used when starting
       the CGI script. Defaults to %ENV when this module was loaded.

   ioloop
       Holds a Mojo::IOLoop object.

METHODS

   emulate_environment
         %env = $self->emulate_environment($c);

       Returns a hash which contains the environment variables which should be used by the CGI
       script.

       In addition to "env", these dynamic variables are set:

         CONTENT_LENGTH, CONTENT_TYPE, HTTP_COOKIE, HTTP_HOST, HTTP_IF_NONE_MATCH,
         HTTP_REFERER, HTTP_USER_AGENT, HTTPS, PATH, PATH_INFO, QUERY_STRING,
         REMOTE_ADDR, REMOTE_HOST, REMOTE_PORT, REMOTE_USER, REQUEST_METHOD,
         SCRIPT_NAME, SERVER_PORT, SERVER_PROTOCOL.

       Additional static variables:

         GATEWAY_INTERFACE = "CGI/1.1"
         SERVER_ADMIN = $ENV{USER}
         SCRIPT_FILENAME = Script name given as argument to register.
         SERVER_NAME = Sys::Hostname::hostname()
         SERVER_SOFTWARE = "Mojolicious::Plugin::CGI"

   register
         $self->register($app, [ $route => $script ]);
         $self->register($app, %args);
         $self->register($app, \%args);

       "route" and path need to exist as keys in %args unless given as plain arguments.

       $route can be either a plain path or a route object.

COPYRIGHT AND LICENSE

       Copyright (C) 2014, Jan Henning Thorsen

       This program is free software, you can redistribute it and/or modify it under the terms of
       the Artistic License version 2.0.

AUTHOR

       Jan Henning Thorsen - "jhthorsen@cpan.org"