/ 
Apache2-SSI-v0.2.12
River stage zero No dependents
/ Apache2::SSI::File

NAME

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

SYNOPSIS

my $f = Apache2::SSI::File->new(
    '/some/file/path/file.html',
    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";

VERSION

v0.1.2

DESCRIPTION

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

METHODS

new

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

apache_request

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;

apache_request

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

base_dir

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
$f->filename;

base_file

Returns the base file for this file object.

clone

Create a clone of the object and return it.

code

Sets or gets the http code for this file.

$f->code( 404 );

collapse_dots

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

filename

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.

filepath

Returns the file path for this file object.

finfo

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.

parent

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

slurp

It returns the content of the "filename"

it takes an hash reference of parameters:

binmode
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.

slurp_utf8

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' });

AUTHOR

Jacques Deguest <jack@deguest.jp>

CPAN ID: jdeguest

https://gitlab.com/jackdeguest/Apache2-SSI

SEE ALSO

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

mod_include, mod_perl(3), APR::URI, URI https://httpd.apache.org/docs/current/en/mod/mod_include.html, https://httpd.apache.org/docs/current/en/howto/ssi.html, https://httpd.apache.org/docs/current/en/expr.html https://perl.apache.org/docs/2.0/user/handlers/filters.html#C_PerlOutputFilterHandler_

COPYRIGHT & LICENSE

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.