view release on metacpan or  search on metacpan

lib/Apache2/SSI.pm  view on Meta::CPAN

                    1;
                });
                return( ( join( '', @$output ), \%hout ) );
            }
            else
            {
                return( join( '', @$output ) );
            }
        }
        if( wantarray )
        {
            my( %hout );
            $hout{STATUS} = $subr->status;
            $hout{STATUS} = &Apache2::Const::HTTP_NOT_FOUND
                if( $hout{STATUS} == &Apache2::Const::HTTP_OK );
            $subr->headers_out->do(sub
            {
                $hout{ lc( $_[0] ) } = $_[1];
                1;
            });
            return( ( undef, \%hout ) );
        }
        else
        {
            return;
        }
        return;
    }
}

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

Apache2::SSI - Apache2 Server Side Include

=head1 SYNOPSIS

Outside of Apache:

    use Apache2::SSI;
    my $ssi = Apache2::SSI->new(
        # If running outside of Apache
        document_root => '/path/to/base/directory'
        # Default error message to display when ssi failed to parse
        # Default to [an error occurred while processing this directive]
        errmsg => '[Oops]'
    );
    my $fh = IO::File->new( "</some/file.html" ) || die( "$!\n" );
    $fh->binmode( ':utf8' );
    my $size = -s( $fh );
    my $html;
    $fh->read( $html, $size );
    $fh->close;
    if( !defined( my $result = $ssi->parse( $html ) ) )
    {
        $ssi->throw;
    };
    print( $result );

Inside Apache, in the VirtualHost configuration, for example:

    PerlModule Apache2::SSI
    PerlOptions +GlobalRequest
    PerlSetupEnv On
    <Directory "/home/joe/www">
        Options All +Includes +ExecCGI -Indexes -MultiViews
        AllowOverride All
        SetHandler modperl
        # You can choose to set this as a response handler or a output filter, whichever works.
        # PerlResponseHandler Apache2::SSI
        PerlOutputFilterHandler Apache2::SSI
        # If you do not set this to On, path info will not work, example:
        # /path/to/file.html/path/info
        # See: <https://httpd.apache.org/docs/current/en/mod/core.html#acceptpathinfo>
        AcceptPathInfo On
        # To enable no-caching (see no_cache() in Apache2::RequestUtil:
        PerlSetVar Apache2_SSI_NO_CACHE On
        # This is required for exec cgi to work:
        # <https://httpd.apache.org/docs/current/en/mod/mod_include.html#element.exec>
        <Files ~ "\.pl$">
            SetHandler perl-script
            AcceptPathInfo On
            PerlResponseHandler ModPerl::PerlRun
            # Even better for stable cgi scripts:
            # PerlResponseHandler ModPerl::Registry
            # Change this in mod_perl1 PerlSendHeader On to the following:
            # <https://perl.apache.org/docs/2.0/user/porting/compat.html#C_PerlSendHeader_>
            PerlOptions +ParseHeaders
        </Files>
        <Files ~ "\.cgi$">
            SetHandler cgi-script
            AcceptPathInfo On
        </Files>
        # To enable debugging output in the Apache error log
        # PerlSetVar Apache2_SSI_DEBUG 3
        # To set the default echo message
        # PerlSetVar Apache2_SSI_Echomsg 
        # To Set the default error message
        # PerlSetVar Apache2_SSI_Errmsg "Oops, something went wrong"
        # To Set the default size format: bytes or abbrev
        # PerlSetVar Apache2_SSI_Sizefmt "bytes"
        # To Set the default date time format
        # PerlSetVar Apache2_SSI_Timefmt ""
        # To enable legacy mode:
        # PerlSetVar Apache2_SSI_Expression "legacy"
        # To enable trunk mode:
        # PerlSetVar Apache2_SSI_Expression "trunk"
    </Directory>

=head1 VERSION

    v0.2.0

=head1 DESCRIPTION

L<Apache2::SSI> implements L<Apache Server Side Include|https://httpd.apache.org/docs/current/en/howto/ssi.html>, a.k.a. SSI, within and outside of Apache2/mod_perl2 framework.