Apache2::SSI::File - Apache2 Server Side Include File Object Class


    my $f = Apache2::SSI::File->new(
        apache_request => $r,
        base_dir => '/home/john/www',
    $f->base_dir( '/home/joe/www' );
    my $f2 = $f->clone;
    unless( $f->code == Apache2::Const::HTTP_OK )
        die( "File is not there!\n" );
    # You can also use $f->filepath which is an alias to $f->filename
    print "Actual file is here: ", $f->filename, "\n";
    my $finfo = $f->finfo;
    if( $finfo->can_exec )
        # do something
    # prints Parent is: /some/file/path
    print "Parent is: ", $f->parent, "\n";




This packages serves to resolve files whether inside Apache scope with mod_perl or outside, providing a unified api.



This instantiates an object that is used to access other key methods. It takes the following parameters:


This is the Apache2::RequestRec object that is provided if running under mod_perl.

it can be retrieved from "request" in Apache2::RequestUtil or via "r" in Apache2::Filter

You can get this Apache2::RequestRec object by requiring Apache2::RequestUtil and calling its class method "request" in Apache2::RequestUtil such as Apache2::RequestUtil-request> and assuming you have set PerlOptions +GlobalRequest in your Apache Virtual Host configuration.

Note that there is a main request object and subprocess request object, so to find out which one you are dealing with, use "is_initial_req" in Apache2::RequestUtil, such as:

    use Apache2::RequestUtil (); # extends Apache2::RequestRec objects
    my $r = $r->is_initial_req ? $r : $r->main;


Sets or gets the Apache2::RequestRec object. As explained in the "new" method, you can get this Apache object by requiring the package Apache2::RequestUtil and calling "request" in Apache2::RequestUtil such as Apache2::RequestUtil-request> assuming you have set PerlOptions +GlobalRequest in your Apache Virtual Host configuration.

When running under Apache mod_perl this is set automatically from the special "handler" method, such as:

    my $r = $f->r; # $f is the Apache2::Filter object provided by Apache


Sets or gets the base directory to be used as a reference to the files provided so they can be transformed into absolute file path.

    my $f = Apache2::SSI::File->new( './index.html',
        base_dir => '/home/joe/www',
    # This would now be /home/joe/www/index.html


Create a clone of the object and return it.


Sets or gets the http code for this file.

    $f->code( 404 );


Provided with an uri or a file path, and this will resolve the path and removing the dots, such as . and .. and return an URI object.

This is done as per the RFC 3986 section 5.2.4 algorithm

    my $file = $f->collapse_dots( '/../a/b/../c/./d.html' );
    # would become /a/c/d.html


Sets or gets the system file path to the file, as a string.

If a new file name is provided, under Apache/mod_perl2, this will perform a query with "lookup_file" in Apache2::SubRequest

Any filename provided will be resolved with its dots flattened and transformed into an absolute system file path if it is not already.


Returns a Apache2::SSI::Finfo object. This provides access to "stat" in perlfunc information as methods, taking advantage of APR::Finfo when running under Apache, and an identical interface otherwise. See Apache2::SSI::Finfo for more information.


Returns the parent of the file, or if there is no parent, it returns the current object itself.

    my $up = $f->parent;
    # would return /home/john/some/path assuming the file was /home/john/some/path/file.html


It returns the content of the "filename"

it takes an hash reference of parameters:

    my $content = $uri->slurp({ binmode => ':utf-8' });

It will return undef and sets an "error" in Module::Generic if there is no "filename" value set or if the file cannot be opened.


It returns the content of the file "filename" utf-8 decoded.

This is equivalent to:

    my $content = $uri->slurp({ binmode => ':utf8' });

:utf8 is slightly a bit more lax than :utf-8, so it you want strict utf8, you can do:

    my $content = $uri->slurp({ binmode => ':utf-8' });


Jacques Deguest <>

CPAN ID: jdeguest


Apache2::SSI::URI, Apache2::SSI::Finfo, Apache2::SSI

mod_include, mod_perl(3), APR::URI, URI,,


Copyright (c) 2020-2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.