Mojoli...n::CGI(3pm)

💖 Mojolicious::Plugin::CGI 💖

okay bestie, this is the manual page for Mojoli...n::CGI(3pm) — like, that's the fancy short name it goes by in your man viewer, and it lives in the User Contributed Perl Documentation. Come sit with me, we're gonna get you running CGI scripts from Mojolicious and it's gonna be ✨ adorable ✨.

---

🌸 NAME 🌸

Mojolicious::Plugin::CGI — run a CGI script from Mojolicious. that's it, that's the whole thing 🫶

---

🎀 VERSION 🎀

0.40

---

💅 DESCRIPTION 💅

so this plugin lets Mojolicious run Perl CGI scripts. how? it forks a brand new process with a modified environment, then reads the STDOUT in a non-blocking manner. no cap, that's the whole magic trick. 🪄

---

✨ SYNOPSIS ✨

🌈 Standard usage

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

literally just that and you're done. hit <http://localhost:3000/cgi-bin/script> and script.pl runs. slay. 👑

🦋 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);
  },
};

this one right here? it contains every single option you can pass to the plugin. the whole menu, bestie. 🍓

🧚 Helper

plugin "CGI";

# GET /cgi-bin/some-script.cgi/path/info?x=123
get "/cgi-bin/#script_name/*path_info" => {path_info => ''}, sub {
  my $c    = shift;
  my $name = $c->stash("script_name");
  $c->cgi->run(script => File::Spec->rel2abs("/path/to/cgi/$name"));
};

the helper can take most of the arguments that register takes, with the exception of support_semicolon_in_query_string. (that one's a whole vibe of its own, see below 👇)

it is critical that script_name and path_info is present in stash. whether the values are extracted directly from the path or set manually does not matter — we're not judging. 💁

also note that the helper is registered in all of the examples. every single one. she's everywhere.

🔥 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. and this is (pretty much) safe, even if the code block modifies global state, since it runs in a separate fork/process. iconic behaviour tbh. 😌

⭐ Support for semicolon in query string

plugin CGI => {
  support_semicolon_in_query_string => 1,
  ...
};

okay so this needs to be added before other plugins or handlers which use url in Mojo::Message::Request. what it does is inject a before_dispatch hook which saves the original QUERY_STRING, before it is split on & in Mojo::Parameters. order matters, bestie, don't play with her. 💀

---

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

this plugin will create a set of environment variables depenendent on the request passed in which is according to the CGI spec. (yes, "depenendent" — we keep the original spelling, no edits here, not on my watch 🙈)

in addition to env, these dynamic variables are set:

CONTENT_LENGTH, CONTENT_TYPE, 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"

plus all headers are exposed. examples, since the original showed them in a little box and we're doing bullet energy instead:

• Referer → HTTP_REFERER
• User-Agent → HTTP_USER_AGENT
• X-Forwarded-For → HTTP_X_FORWARDED_FOR

🌈 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. both are valid, pick your fighter. 🥊

---

👑 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

---

and that's the whole page, bestie!! 🦋 this was Mojoli...n::CGI(3pm) from the User Contributed Perl Documentation, and the version + date at the bottom of the original? perl v5.28.1 dated 2018-12-22. so old, so iconic, still serving. periodt. 💅✨