Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

CGI::Apache2::Wrapper - CGI.pm-compatible methods via mod_perl

SYNOPSIS

  sub handler {
    my $r = shift;
    my $cgi = CGI::Apache2::Wrapper->new($r);
    my $foo = $cgi->param("foo");
    my $header = {'Content-Type' => 'text/plain; charset=utf-8',
		  'X-err_header_out' => 'err_headers_out',
		 };
    $cgi->header($header);
    $r->print("You passed in $foo\n");
    return Apache2::Const::OK;
  }

DESCRIPTION

Certain modules, such as CGI::Ajax and JavaScript::Autocomplete::Backend, require a minimal CGI.pm-compatible module to provide certain methods, such as param() to fetch parameters. The standard module to do this is of course CGI.pm; however, especially in a mod_perl environment, there may be concerns with the resultant memory footprint. This module provides various CGI.pm-compatible methods via mod_perl2 and librapreq2, and as such, it may be a viable alternative in a mod_perl scenario.

Note that this module is not a drop-in replacement for CGI.pm, as only a select few methods that naturally arise in mod_perl2 and libapreq2 are provided. As well as providing CGI.pm-compatible methods to other modules, one of the main intents here is to assist development of porting CGI applications over to mod_perl2 and libapreq2 and/or for use in writing applications that are to be used in either a cgi or mod_perl environment. However, for applications that are intended only for mod_perl, it is recommended that the native interface to mod_perl2 and libapreq2 ultimately be used, as this module will add some overhead.

Methods

Methods are called via the object created as

my $cgi = CGI::Apache2::Wrapper->new($r);

The Apache2::RequestRec object $r must be passed in as an argument.

Methods available can be grouped according to what mod_perl2/libapreq2 modules provide them:

Apache2::RequestRec

$cgi->header($header);

In a mod_perl environment, this sets the headers, whereas in a CGI environment, this returns a string containing the headers to be printed out. If no argument is given to header(), only the Content-Type is set, which by default is text/html. If a hash reference $header is passed to header, such as
```
  my $header = {'Content-Type' => 'text/plain; charset=utf-8',
	        'X-err_header_out' => 'err_headers_out',
	       };
```
these will be used as the headers.
$qs = $cgi->query_string();

This retrieves the unprocessed query string.
$sp = $cgi->server_protocol();

This returns the protocol of the client, such as HTTP/1.0 or HTTP/1.1.
$rm = $cgi->request_method();

This returns the method used to form the request, such as POST, GET or HEAD.
$ct = $cgi->content_type();

This returns the HTTP response Content-type header value.
$pi = $cgi->path_info();

Returns additional path information from the URL. For example, for a handler specified through a <Location /some/location > directive, fetching /some/location/additional/stuff will result in path_info() returning /additional/stuff.
$cgi->redirect($url);

This redirects the client to the specified URL. For a ModPerl::Registry script, $cgi-status(Apache2::Const::REDIRECT);> should also be called.
$cgi->status(Apache2::Const::REDIRECT);

This can be used to set the status field, typically in the context of a redirect for a ModPerl::Registry script. Handlers should never manipulate the status field directly.

Apache2::RequestUtil

$ru = $cgi->remote_user();

This returns the authorization name used for user verification.
$un = $cgi->user_name();

Attempts to return the remote user's name.
$sn = $cgi->server_name();

This returns the name of the server, which is usually the machine's host name.
$sp = $cgi->server_port();

This returns the port that the server is listening on.

Apache2::Access

$at = $cgi->auth_type();

This returns the authorization/verification method in use, if any.
$ri = $cgi->remote_ident();

This returns the identity of the remote user if the host is running identd.

Apache2::Connection

$ra = $cgi->remote_addr();

This returns the remote IP address.
$rh = $cgi->remote_host();

This returns either the remote host name or the IP address, if the former is unavailable.

Apache2::Request

$value = $cgi->param("foo");

This fetches the value of the named parameter. If no argument is given to param(), a list of all parameter names is returned.

Apache2::URI

my $url = $cgi->url(%opts);

This returns the url in a variety of formats compatible with CGI. For example, suppose that the handler is in a location
```
<Location /TestCGI>
   SetHandler modperl
   PerlResponseHandler My::Handler
</Location>
```
on port 8529 and the request http://localhost:8529/TestCGI/extra/path/info?opening=hello is made. The following options for %opts are recognized:
- no options
  
  Called without any arguments, this returns the full form of the URL, including host name and port number: http://localhost:8529/TestCGI
- -absolute => 1
  
  This produces an absolute url: /TestCGI
- -relative => 1
  
  This produces an relative url: TestCGI
- -full => 1
  
  This produces a full url: http://localhost:8529/TestCGI
- -path => 1 (or -path_info => 1)
  
  This appends the additional path information to the url: http://localhost:8529/TestCGI/extra/path/info
- -query => 1 (or -query_string => 1)
  
  This appends the query string to the url: http://localhost:8529/TestCGI?opening=hello;closing=goodbye
- -base => 1
  
  This generates just the protocol and net location: http://localhost:8529
Specifying the options -path => 1 and -query => 1 will lead to the complete url: http://localhost:8529/TestCGI/extra/path/info?opening=hello;closing=goodbye.
my $url = $cgi->self_url;

This generates the complete url, and is a shortcut for my $url = $cgi->url(-query => 1, -path => 1);. Using the example described in the url options, this would lead to http://localhost:8529/TestCGI/extra/path/info?opening=hello;closing=goodbye.

A new cookie can be created as

my $c = $cgi->cookie(-name    =>  'foo',
                     -value   =>  'bar',
                     -expires =>  '+3M',
                     -domain  =>  '.capricorn.com',
                     -path    =>  '/cgi-bin/database',
                     -secure  =>  1
                    );

which is an object of the CGI::Apache2::Wrapper::Cookie class. The arguments accepted are

-name

This is the name of the cookie (required)
-value

This is the value associated with the cookie (required)
-expires

This accepts any of the relative or absolute date formats recognized by CGI.pm, for example "+3M" for three months in the future. See CGI.pm for details.
-domain

This points to a domain name or to a fully qualified host name. If not specified, the cookie will be returned only to the Web server that created it.
-path

This points to a partial URL on the current server. The cookie will be returned to all URLs beginning with the specified path. If not specified, it defaults to '/', which returns the cookie to all pages at your site.
-secure

If set to a true value, this instructs the browser to return the cookie only when a cryptographic protocol is in use.

A value of an existing cookie can be retrieved by calling cookie without the value parameter:

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

A list of all cookie names can be obtained by calling cookie without any arguments:

my @names = $cgi->cookie();

See also CGI::Apache2::Wrapper::Cookie for a CGI::Cookie-compatible interface to cookies.

Apache2::Upload

Uploads can be handled with the upload method:

my $fh = $cgi->upload('filename');

which returns a file handle that can be used to access the uploaded file. If there are multiple upload fields, calling upload in a list context:

my @fhs = $cgi->upload('filename');

will return an array of filehandles. There are two helper methods available for uploads:

my $tmpfile = $cgi->tmpFileName($fh);

This returns the name of the temporary file associated with the $fh fielhandle returned from upload.
my $info = $cgi->uploadInfo($fh);

This returns a hash reference containing some information about the uploaded file associated with the $fh filehandle returned from upload. The keys of this hash typically include:
- Content-Type
  
  The content type, such as text/plain, associated with this upload.
- Content-Disposition
  
  This typically is a string such as form-data; name="HTTPUPLOAD"; filename="data.txt".
- size
  
  This is the size of the uploaded file.
- name
  
  This is the name of the HTML form element which generated the upload.
- filename
  
  The (client-side) filename as submitted in the HTML form. Note that some agents will submit the file's full pathname, while others may submit just the basename.
- type
  
  This is the MIME type of the upload.

Helpers

my $r = $cgi->r;

This returns the Apache2::RequestRec object $r passed into the new() method.
my $req = $cgi->req;

This returns the Apache2::Request object $req, which provides the param() method to fetch form parameters.

SUPPORT

You can find documentation for this module with the perldoc command:

perldoc CGI::Apache2::Wrapper

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/CGI-Apache2-Wrapper
CPAN::Forum: Discussion forum

http:///www.cpanforum.com/dist/CGI-Apache2-Wrapper
CPAN Ratings

http://cpanratings.perl.org/d/CGI-Apache2-Wrapper
RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Apache2-Wrapper
Search CPAN

http://search.cpan.org/dist/CGI-Apache2-Wrapper
UWinnipeg CPAN Search

http://cpan.uwinnipeg.ca/dist/CGI-Apache2-Wrapper

ENVIRONMENT VARIABLES

If the USE_CGI_PM environment variable is set, the new method will return a CGI.pm object.

BUGS

Although the methods provided here have a natural correspondence with the associated methods of CGI.pm, there may be subtle differences present.

Please report any bugs and feature requests to the author or through CPAN's request tracker at http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Apache2-Wrapper.

COPYRIGHT

To install CGI::Apache2::Wrapper, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CGI::Apache2::Wrapper

CPAN shell

perl -MCPAN -e shell
install CGI::Apache2::Wrapper

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)