view release on metacpan or  search on metacpan

lib/HTML/MasonX/ApacheLikePlackHandler.pm  view on Meta::CPAN

to migrating from this ~1000 line class to Graham Barr entirely
different L<HTML::Mason::PlackHandler>.

This module has the following changes from
L<HTML::Mason::ApacheHandler>:

=over

=item * Changed the C<$VERSION> number to the version of this distro

=item * C<s/HTML::Mason::ApacheHandler/HTML::MasonX::ApacheLikePlackHandler/g>

=item * C<s/HTML::Mason::Request::ApacheHandler/HTML::MasonX::Request::ApacheLikePlackHandler/g>

=item * Removed code that wasn't run when APACHE2 was false.

I was already running on Apache 1 anyway, and didn't want to bother
with the Apache 1 parts of this API. So away it goes!

=item * Removed loading of mod_perl libraries

=back

But most importantly: Instead of requiring various Apache2::* modules
we require that you define
C<HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_{REQUEST,REQUEST_INSTANCE,STATUS,SERVERUTIL}_CLASS>
in C<%ENV> before requiring this module.

Those C<%ENV> entries should be the name of already loaded Perl packages
implement an API emulating the Apache2 API this package needs. The
"APACHE2_REQUEST_INSTANCE" variable is a special case though, it's the
package your request object (implementing the Apache2 API) will be
blessed into.

This makes for a rather convoluted API, but the goal was to modify the
upstream code as little as possible, both to avoid accidentally
introducing bugs, and to make it easier to incorporate future upstream
patches.

=head1 EXAMPLE

Here's an example of the source of packages you could as the
C<HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_*> variables. These are just
bare-minimal implementations of the Apache API that
L<HTML::MasonX::ApacheLikePlackHandler> expects uses.

=head2 Fake L<APR::Table> class

    # http://perl.apache.org/docs/2.0/api/APR/Table.html
    package Your::MasonCompat::APR::Like::Table;
    use strict;
    use warnings;

    sub new {
        my ($class, $table) = @_;

        # XXX: This is very naive, in reality an APR::Table maybe
        # can't be represented as a hash (multiple values for the same
        # key?). Or at least we need magic to implement a similar
        # Tie-interface.
        bless $table => $class;
    }

    sub get {
        my ($self, $key) = @_;

        die "PANIC: Someone's trying to get a key ($key) that we don't have" unless exists $self->{$key};

        if (ref $self->{$key} eq 'ARRAY') {
            # Our dumb emulation for PerlAddVar without supporting all
            # of APR::Table.
            return @{$self->{$key}};
        } else {
            return $self->{$key};
        }
    }

=head2 HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_REQUEST_CLASS

You're going to have to use L<Plack::App::FakeApache::Request>, or
pester me to generalize and open source the version I'm using. See the
L<description section|/DESCRIPTION>.

=head2 HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_REQUEST_CLASS

    package Your::ApacheLikePlackHandler::Compat::Apache2::Request;
    use strict;
    use warnings;
    use Scalar::Util qw(blessed);

    # NEEDED because of HTML::MasonX::ApacheLikePlackHandler code that
    # does $this_pkg->VERSION. We should never need to change this.
    our $VERSION = 1.2345;

    # This is only used for:
    #
    #    sub { Apache2::Request->new( $_[0] ) };
    #
    # So just return the original object. The reason for this being
    # called at all is because the mod_perl 1 API would do something
    # different
    sub new {
        my ($class, $blessed_request_object) = @_;

        die "PANIC: We should only get an already blessed object as an argument"
            unless blessed($blessed_request_object);

        return $blessed_request_object;
    }

    # We do nothing except the above in this class from
    # HTML::MasonX::ApacheLikePlackHandler as of writing this.

=head2 HTML_MASONX_APACHELIKEPLACKHANDLER_MOCK_APACHE2_SERVERUTIL_CLASS

    package Your::ApacheLikePlackHandler::Compat::Apache2::ServerUtil;
    use strict;
    use warnings;
    use Your::WebServerConfiguration qw(
        PLACK_WEBSERVER_CONFIGURATION_VARIABLES
    );