NAME

       Plack::Handler::Apache2 - Apache 2.0 mod_perl handler to run PSGI application

SYNOPSIS

         # in your httpd.conf
         <Location />
         SetHandler perl-script
         PerlResponseHandler Plack::Handler::Apache2
         PerlSetVar psgi_app /path/to/app.psgi
         </Location>

         # Optionally preload your apps in startup
         PerlPostConfigRequire /etc/httpd/startup.pl

       See "STARTUP FILE" for more details on writing a "startup.pl".

DESCRIPTION

       This is a mod_perl handler module to run any PSGI application with mod_perl on Apache 2.x.

       If you want to run PSGI applications behind Apache instead of using mod_perl, see Plack::Handler::FCGI to
       run with FastCGI, or use standalone HTTP servers such as Starman or Starlet proxied with mod_proxy.

CREATING CUSTOM HANDLER

       If you want to create a custom handler that loads or creates PSGI applications using other means than
       loading from ".psgi" files, you can create your own handler class and use "call_app" class method to run
       your application.

         package My::ModPerl::Handler;
         use Plack::Handler::Apache2;

         sub get_app {
           # magic!
         }

         sub handler {
           my $r = shift;
           my $app = get_app();
           Plack::Handler::Apache2->call_app($r, $app);
         }

STARTUP FILE

       Here is an example "startup.pl" to preload PSGI applications:

           #!/usr/bin/env perl

           use strict;
           use warnings;
           use Apache2::ServerUtil ();

           BEGIN {
               return unless Apache2::ServerUtil::restart_count() > 1;

               require lib;
               lib->import('/path/to/my/perl/libs');

               require Plack::Handler::Apache2;

               my @psgis = ('/path/to/app1.psgi', '/path/to/app2.psgi');
               foreach my $psgi (@psgis) {
                   Plack::Handler::Apache2->preload($psgi);
               }
           }

           1; # file must return true!

       See <http://perl.apache.org/docs/2.0/user/handlers/server.html#Startup_File> for general information on
       the "startup.pl" file for preloading perl modules and your apps.

       Some things to keep in mind when writing this file:

       •   multiple init phases

           You  have to check that "restart_count" in Apache2::ServerUtil is "> 1", otherwise your app will load
           twice       and        the        env        vars        you        set        with        PerlSetEnv
           <http://perl.apache.org/docs/2.0/user/config/config.html#C_PerlSetEnv_>  will  not  be available when
           your app is loading the first time.

           Use the example above as a template.

       •   @INC

           The "startup.pl" file is a good place to add entries to your @INC.  Use lib to add entries, they  can
           be  in  your  app  or ".psgi" as well, but if your modules are in a local::lib or some such, you will
           need to add the path for anything to load.

           Alternately, if you follow the example above, you can use:

               PerlSetEnv PERL5LIB /some/path

           or

               PerlSwitches -I/some/path

           in your "httpd.conf", which will also work.

       •   loading errors

           Any exceptions thrown in your "startup.pl" will stop Apache from starting at all.

           You probably don't want a stray syntax error  to  bring  your  whole  server  down  in  a  shared  or
           development  environment, in which case it's a good idea to wrap the "preload" call in an eval, using
           something like this:

               require Plack::Handler::Apache2;

               my @psgis = ('/path/to/app1.psgi', '/path/to/app2.psgi');

               foreach my $psgi (@psgis) {
                   eval {
                       Plack::Handler::Apache2->preload($psgi); 1;
                   } or do {
                       my $error = $@ || 'Unknown Error';
                       # STDERR goes to the error_log
                       print STDERR "Failed to load psgi '$psgi': $error\n";
                   };
               }

       •   dynamically loaded modules

           Some modules load their dependencies at runtime via e.g. Class::Load.  These  modules  will  not  get
           preloaded into your parent process by just including the app/module you are using.

           As  an  optimization,  you  can dump %INC from a request to see if you are using any such modules and
           preload them in your "startup.pl".

           Another method is dumping the difference between the %INC on process start and process exit. You  can
           use something like this to accomplish this:

               my $start_inc = { %INC };

               END {
                   my @m;
                   foreach my $m (keys %INC) {
                       push @m, $m unless exists $start_inc->{$m};
                   }

                   if (@m) {
                       # STDERR goes to the error_log
                       print STDERR "The following modules need to be preloaded:\n";
                       print STDERR "$_\n" for @m;
                   }
               }

AUTHOR

       Tatsuhiko Miyagawa

CONTRIBUTORS

       Paul Driver

       Ævar Arnfjörð Bjarmason

       Rafael Kitover

SEE ALSO

       Plack

perl v5.38.2                                       2024-01-20                       Plack::Handler::Apache2(3pm)