NAME

NAME

Catalyst::Controller::WrapCGI - Run CGIs in Catalyst

SYNOPSIS

package MyApp::Controller::Foo;

use parent qw/Catalyst::Controller::WrapCGI/;
use CGI ();

sub hello : Path('cgi-bin/hello.cgi') {
my ($self, $c) = @_;

$self->cgi_to_response($c, sub {
my $q = CGI->new;
print $q->header, $q->start_html('Hello'),
$q->h1('Catalyst Rocks!'),
$q->end_html;
});
}

In your .conf, configure which environment variables to pass:

<Controller::Foo>
<CGI>
username_field username # used for REMOTE_USER env var
pass_env PERL5LIB
pass_env PATH
pass_env /^MYAPP_/
kill_env MYAPP_BAD
</CGI>
</Controller::Foo>

DESCRIPTION

Allows you to run Perl code in a CGI environment derived from your
Catalyst context.

*WARNING*: do not export CGI functions into a Controller, it will break
with Catalyst 5.8 onward.

If you just want to run CGIs from files, see
Catalyst::Controller::CGIBin.

REMOTE_USER will be set to $c->user->obj->$username_field if available,
or to $c->req->remote_user otherwise.

CONFIGURATION

pass_env

$your_controller->{CGI}{pass_env} should be an array of environment
variables or regular expressions to pass through to your CGIs. Entries
surrounded by / characters are considered regular expressions.

kill_env

$your_controller->{CGI}{kill_env} should be an array of environment
variables or regular expressions to remove from the environment before
passing it to your CGIs. Entries surrounded by / characters are
considered regular expressions.

Default is to pass the whole of %ENV, except for entries listed in
"FILTERED ENVIRONMENT" below.

username_field

$your_controller->{CGI}{username_field} should be the field for your
user's name, which will be read from $c->user->obj. Defaults to
'username'.

See "SYNOPSIS" for an example.

METHODS

cgi_to_response

$self->cgi_to_response($c, $coderef)

Does the magic of running $coderef in a CGI environment, and populating
the appropriate parts of your Catalyst context with the results.

Calls "wrap_cgi".

wrap_cgi

$self->wrap_cgi($c, $coderef)

Runs $coderef in a CGI environment using HTTP::Request::AsCGI, returns
an HTTP::Response.

The CGI environment is set up based on $c.

The environment variables to pass on are taken from the configuration
for your Controller, see "SYNOPSIS" for an example. If you don't supply
a list of environment variables to pass, the whole of %ENV is used
(with exceptions listed in "FILTERED ENVIRONMENT".

Used by "cgi_to_response", which is probably what you want to use as
well.

FILTERED ENVIRONMENT

If you don't use the "pass_env" option to restrict which environment
variables are passed in, the default is to pass the whole of %ENV
except the variables listed below.

MOD_PERL
SERVER_SOFTWARE
SERVER_NAME
GATEWAY_INTERFACE
SERVER_PROTOCOL
SERVER_PORT
REQUEST_METHOD
PATH_INFO
PATH_TRANSLATED
SCRIPT_NAME
QUERY_STRING
REMOTE_HOST
REMOTE_ADDR
AUTH_TYPE
REMOTE_USER
REMOTE_IDENT
CONTENT_TYPE
CONTENT_LENGTH
HTTP_ACCEPT
HTTP_USER_AGENT

%ENV can be further trimmed using "kill_env".

DIRECT SOCKET/NPH SCRIPTS

This currently won't work:

#!/usr/bin/perl

use CGI ':standard';

$| = 1;

print header;

for (0..1000) {
print $_, br, "\n";
sleep 1;
}

because the coderef is executed synchronously with STDOUT pointing to a
temp file.

ACKNOWLEDGEMENTS

Original development sponsored by http://www.altinity.com/

SEE ALSO

Catalyst::Controller::CGIBin, CatalystX::GlobalContext,
Catalyst::Controller, CGI, Catalyst

BUGS

Please report any bugs or feature requests to
bug-catalyst-controller-wrapcgi at rt.cpan.org, or through the web
interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Controller-WrapCGI.
I will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.

AUTHOR

Matt S. Trout <mst at shadowcat.co.uk>

CONTRIBUTORS

Caelum: Rafael Kitover <[email protected]>

confound: Hans Dieter Pearcey <[email protected]>

rbuels: Robert Buels <[email protected]>

Some code stolen from Tatsuhiko Miyagawa's CGI::Compile.

COPYRIGHT & LICENSE

Copyright (c) 2008-2015 "AUTHOR" in Catalyst::Controller::WrapCGI and
"CONTRIBUTORS" in Catalyst::Controller::WrapCGI.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.