GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
CGI::Application::Plugin::Apache(3) User Contributed Perl Documentation CGI::Application::Plugin::Apache(3)

CGI::Application::Plugin::Apache - Allow CGI::Application to use Apache::* modules without interference

    use base 'CGI::Application';
    use CGI::Application::Plugin::Apache qw(:all);
    
    # then later we join our hero in a run mode...
    sub mode1 {
        my $self = shift;
        my $q = $self->query(); # $q is an Apache::Request obj not a CGI.pm obj

        # do some stuff
        
        # now we can bake a cookie using Apache::Cookie without interference  
        $cookie = Apache::Cookie->new(
                $q,
                -name       => 'foo',
                -value      => 'bar',
                -expires    => '+2h',
        );
        $cookie->bake;

        # now let's play with the content_type and other headers
        $q->content_type('text/plain');
        $q->header_out('MyHeader' => 'MyValue');

        # do other stuff
        return $content;
    }

    1;

This plugin helps to try and fix some of the annoyances of using CGI::Application in a pure mod_perl (1.0 or 2.0) environment (see INSTALLATION for specific issues regarding installation under mod_perl 2.x). CGI::Application assumes that you use CGI.pm, but I wanted to avoid it's bloat and have access to the performance of the Apache::* modules so along came this plugin. At the current moment it only does two things:
Use Apache::Request as the "$self->query" object thus avoiding the creation of the CGI.pm object.
Override the way CGI::Application creates and prints it's HTTP headers. Since it was using CGI.pm's "header()" and "redirect()" method's we needed an alternative. So now we use the "Apache->send_http_header()" method. This has a few additional benefits other than just not using CGI.pm. It means that we can use other Apache::* modules that might also create outgoing headers (e.g. Apache::Cookie) without CGI::Application clobbering them.

This module uses Exporter to provide methods to your application module. Most of the time you will never actually use these methods since they are used by CGI::Application itself, but I figured you'd like to know what's going on.

No methods are exported by default. It is up to you to pick and choose, but please choose wisely. You can import all of the methods by using:

    use CGI::Application::Plugin::Apache qw(:all);

It is recommended that you import all of them since some methods will require others. but the choice is yours. For instance, if you want to override any method then you may not want to import it from here.

This method gives your application the ability to run as a straight mod_perl handler. It simply creates an instance of you application and then runs it (using "$app->new()" and "$app->run()"). It does not pass any arguments into either method. It then returns an "Apache::Constants::OK" value. If you need anything more than this, please feel free to not import this method and write your own. You could do it like this:

    package MyApp;
    use base 'CGI::Application';
    use CGI::Application::Plugin::Apache qw(:all !handler);

    sub handler {
        # do what every you want here
    }

This overrides CGI:App's method for retrieving the query object. This is the standard way of using something other than CGI.pm so it's no surprise that we use it here. It simply creates and returns a new Apache::Request object from "Apache->request".

I didn't like the idea of exporting this private method (I'd rather think it was a 'protected' not 'private) but right now it's the only way to have any say in how the HTTP headers are created. Please see "HTTP Headers" for more details.

We encourage you to learn the mod_perl way of manipulating headers and cookies. It's really not that hard we promise. But incase you're easing your way into it, we try and provide as much backward compatibility as possible.

HTTP cookies should now be created using Apache::Cookie and it's "bake()" method not with "header_add()" or "header_props()".

You can still do the following to create a cookie

    my $cookie = CGI::Cookie->new(
        -name  => 'foo',
        -value => 'bar',
    );
    $self->header_add(-cookie => $cookie);

But now we encourage you to do the following

    my $cookie = Apache::Cookie->new(
        $self->query,
        -name  => 'foo',
        -value => 'bar',
    );
    $cookie->bake();

You can still do the following to perform an HTTP redirect

    $self->header_props( uri => $some_url);
    $self->header_type('redirect');
    return '';

But now we encourage you to do the following

    $self->query->header_out(Location => $some_url);
    $self->query->status(REDIRECT);
    return '';

But it's really up to you.

Upon using this module you completely leave behind the world of CGI.pm. Don't look back or you might turn into a pillar of salt. You will have to look at and read the docs of the Apache::* modules. But don't worry, they are really easy to use and were designed to mimic the interface of CGI.pm and family.

If you are trying to use this module but don't want to have to change your previous code that uses "header_props()" or "header_add()" then we try to help you out by being as CGI compatible as we can, but it is always better to use the mod_perl api. If you still want to use "header_props()" or "header_add()" remember that it will cause a performance hit because it will use helper routines that try and emulate CGI.pm.

If you wish to write code that performs well in both environments, you can check the $ENV{MOD_PERL} environment setting and branch accordingly. For example, to set a cookie:

  if ($ENV{MOD_PERL}) {
    require Apache::Cookie;
    $cookie = Apache::Cookie->new(
      $q,
      -name       => 'favorite',
      -value      => 'chocolate chip',
      -expires    => '+2h',
    );
    $cookie->bake;
  }
  else {
    $cookie = $self->query->cookie(
      -name    => 'favorite',
      -value   => 'chocolate chip',
      -expires => '+2h',
    );
    $webapp->header_add(-cookie => [$cookie]);
  }

If for some reason you are using this plugin in a non-mod_perl environment, it will try to do the right thing by simply doing nothing :)

Sometimes the default compatability is not enough. For instance, if you are using plugins that use the cookies or upload features of CGI.pm then you might need some extra help.

This is what CGI::Application::Plugin::Apache::Request is for. You can make this your "query" object by setting the "CAPA_CGI_Compat" var to "On" in your Apache config file:

    PerlSetVar CAPA_CGI_Compat On

Please see that module for more documentation on what it does.

This module is designed to function equally under mod_perl 1.x and mod_perl 2.x. The only real issue comes during the installation and testing phase. In order to track dependencies, etc we need to know which version you are trying to install this for. By default we assume mod_perl 1.x unless we find mod_perl 2 installed on your system.

If you want to change this, you simple pass a "MP2" option to the "Build.PL" script.

  perl ./Build.PL MP2=1

That's pretty easy, right?

Michael Peters <mpeters@plusthree.com>

Thanks to Plus Three, LP (http://www.plusthree.com) for sponsoring my work on this module

The following people have contributed to this module either through docs, code, or ideas
William McKee <william@knowmad.com>
Cees Hek <ceeshek@gmail.com>
Drew Taylor <drew@drewtaylor.com>
Ron Savage <ron@savage.net.au>

  • CGI::Application
  • Apache
  • Apache::Request / Apache2::Request
  • Apache::Cookie / Apache2::Cookie

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
2022-05-14 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.