NAME
mod_perl 1.x versus mod_perl 2.x compatibility issues
Description
FIXME: DESCRIPTION
Code Porting from 1.x to 2.x
mod_perl 2.x is trying hard to be back compatible with mod_perl 1.x. However some things (mostly APIs) have been changed. In order to gain a complete compatibilty with 1.x while running under 2.x, you should load the compatibility module as early as possible:
use Apache::compat;at the server startup. And unless there are forgotten things or bugs, your code should work without any changes under 2.x series.
However, unless you want to keep the 1.x compatibility, you should try to remove the compatibility layer and adjust your code to work under 2.x without it. You want to do it mainly for the performance improvement.
This document explains what APIs have changed and what new APIs should be used instead.
Configuration Directives
To migrate the configuration files to the 2.x syntax, you may need to do certain adjustments if you use any of the configuration directives listed in the following sections.
Remember that if you use any of the new directives you configuration won't work anymore with mod_perl 1.x.
PerlHandler
Replaced with PerlResponseHandler.
PerlSendHeader
Replaced with PerlOptions +/-ParseHeaders directive.
PerlSendHeader On => Options +ParseHeaders
PerlSendHeader Off => Options -ParseHeadersPerlSetupEnv
Replaced with PerlOptions +/-SetupEnv directive.
PerlSendHeader On => Options +SetupEnv
PerlSendHeader Off => Options -SetupEnvPerlTaintCheck
Now can be turned on with:
PerlSwitches -TThe default is Off. You cannot turn it Off once it's turned On.
PerlWarn
Now can be turned on with:
PerlSwitches -wApache API
To continue using Apache API from 1.x, load the compatibility module as early as possible:
use Apache::compat;at the server startup.
Apache::gensym
Since Perl 5.6.1 filehandlers are autovivified and there is no need for Apache::gensym() function, since now it can be done with:
open my $fh, "foo" or die $!;The C function modperl_perl_gensym() is available for XS/C extension writers, though.
Apache::File
Apache::Util
A few Apache::Util functions have changed their interface.
Apache::Util::size_string
Apache::Util::size_string has been replaced with APR::String::format_size, which returns formatted strings of only 4 characters long. See the APR::String manpage for more information.
Miscellaneous
Method Handlers
In mod_perl 1.x the method handlers could be specified by using the ($$) prototype:
package Bird;
@ISA = qw(Eagle);
sub handler ($$) {
my($class, $r) = @_;
...;
}Starting from Perl version 5.6 the subroutine attributes are used in place of subroutine prototypes:
package Bird;
@ISA = qw(Eagle);
sub handler : method {
my($class, $r) = @_;
...;
}see the attributes manpage for additional information on subroutine attributes.
mod_perl 2.0 doesn't support the ($$) prototypes, mainly because several callbacks in 2.0 have more arguments than $r, so the ($$) prototype doesn't make sense anymore. Therefore if you want your code to work with both mod_perl generations, you should use the subroutine attributes.
Apache::Registry and Apache::PerlRun and Other mod_cgi Emulators
Apache::Registry and Apache::PerlRun now live in the ModPerl:: namespace to avoid collisions with the versions from 1.x.
To run the 1.x Apache::Registry you have to load Apache::compat:
file:startup.pl:
----------------
use Apache::compat ();
use lib ...; #or something to find 1.xx Apache::Registrythen in httpd.conf:
Alias /perl /path/to/perl/scripts
<Location /perl>
Options +ExecCGI
SetHandler modperl
PerlResponseHandler Apache::Registry
</Location>Notice that Apache::compat has to be loaded before CGI.pm if the latter module is used.
META: complete
Apache::StatINC
Apache::StatINC has been replaced by Apache::Reload.
Maintainers
Maintainer is the person(s) you should contact with updates, corrections and patches.
Stas Bekman <stas (at) stason.org>
Authors
Stas Bekman <stas (at) stason.org>
Only the major authors are listed above. For contributors see the Changes file.