NAME

NAME
Apache2::SSI - Apache2 Server Side Include Parser

SYNOPSIS
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 );

VERSION
v0.13.3

DESCRIPTION
Apache2::SSI implements Apache Server Side Include
<https://httpd.apache.org/docs/current/en/howto/ssi.html>, a.k.a. SSI.

Apache2::SSI is inspired from the original work of Apache::SSI with the
difference that Apache2::SSI works well when called from within Apache
mod_perl as well as when called outside of Apache if you want to
simulate SSI <https://httpd.apache.org/docs/current/en/howto/ssi.html>.

Under Apache mod_perl, you would implement it like this in your
"apache2.conf" or "httpd.conf"

<Files *.phtml>
SetHandler modperl
# Or if you are running mod_perl 1.0
# SetHandler perl-script
PerlHandler Apache2::SSI
</Files>

This would enable Apache2::SSI for files whose extension is ".phtml".
You can also limit this by location, such as:

<Location /some/web/path>
<Files *.html>
SetHandler modperl
PerlHandler Apache2::SSI
</Files>
</Location>

As pointed out by Ken Williams, the original author of Apache::SSI, the
benefit for using Apache2::SSI is:

1. You want to subclass Apache2::SSI and have granular control on how to
render ssi
2. You want to "parse the output of other mod_perl handlers, or send the
SSI output through another handler"
3. You want to mimick SSI without activating them or without using
Apache (such as in command line)

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

*apache_request*
This is the Apache2::RequestRec object that must be provided if
running under mod_perl.

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.

*document_root*
This is only necessary to be provided if this is not running under
Apache mod_perl. Without this value, Apache2::SSI has no way to
guess the document root and will not be able to function properly
and will return an "error".

*document_uri*
This is only necessary to be provided if this is not running under
Apache mod_perl. This must be the uri of the document being served,
such as "/my/path/index.html". So, if you are using this outside of
the rim of Apache mod_perl and your file resides, for example, at
"/home/john/www/my/path/index.html" and your document root is
"/home/john/www", then the document uri would be
"/my/path/index.html"

*errmsg*
The error message to be returned when a ssi directive fails. By
default, it is "[an error occurred while processing this directive]"

*html*
The html data to be parsed. You do not have to provide that value
now. You can provide it to "parse" as its first argument when you
call it.

*sizefmt*
The default way to format a file size. By default, this is "abbrev",
which means a human readable format such as "2.5M" for 2.5
megabytes. Other possible value is "bytes" which would have the
"fsize" ssi directive return the size in bytes.

*timefmt*
The default way to format a date time. By default, this uses the
display according to your locale, such as "ja_JP" (for Japan) or
"en_GB" for the United Kingdoms. The time zone can be specified in
the format, or it will be set to the local time zone, whatever it
is.

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.

decode_base64
Decode base64 data provided. When running under Apache mod_perl, this
uses "decode" in APR::Base64 module, otherwise it uses "decode" in
MIME::Base64

If the decoded data contain utf8 data, this will decoded the utf8 data
using "decode" in Encode

If an error occurred during decoding, it will return undef and set an
"error" object accordingly.

decode_entities
Decode html data containing entities. This uses "decode_entities" in
HTML::Entities

If an error occurred during decoding, it will return undef and set an
"error" object accordingly.

Example:

$ssi->decode_entities( 'Tous les Ãªtres humains naissent libres et Ã©gaux en dignitÃ© et en droits.' );
# Tous les êtres humains naissent libres et égaux en dignité et en droits.

decode_uri
Decode uri encoded data. This uses "uri_unescape" in URI::Escape.

Not to be confused with x-www-form-urlencoded data. For that see
"decode_url"

If an error occurred during decoding, it will return undef and set an
"error" object accordingly.

Example:

$ssi->decode_uri( 'https%3A%2F%2Fwww.example.com%2F' );
# https://www.example.com/

decode_url
Decode x-www-form-urlencoded encoded data. When using Apache mod_perl,
this uses "decode" in APR::Request, otherwise it uses "url_decode_utf8"
in URL::Encode (its XS version)

If an error occurred during decoding, it will return undef and set an
"error" object accordingly.

Example:

$ssi->decode_url( 'Tous les êtres humains naissent libres et égaux en dignité et en droits.' );
# Tous les êtres humains naissent libres et égaux en dignité et en droits.

document_directory
Returns an Apache2::SSIFile object of the current directory of the
"document_uri" provided.

document_filename
This returns the system file path to the document uri.

document_root
Sets or gets the document root.

Wen running under Apache mod_perl, this value will be available
automatically, using "document_root" in Apache2::RequestRec method.

If it runs outside of Apache, this will use the value provided upon
instantiating the object and passing the *document_root* parameter. If
this is not set, it will return the value of the environment variable
"DOCUMENT_ROOT".

document_uri
Sets or gets the document uri, which is the uri of the document being
processed.

For example:

/index.html

Under Apache, this will get the environment variable "DOCUMENT_URI" or
calls the "uri" in Apache2::RequestRec method.

Outside of Apache, this will rely on a value being provided upon
instantiating an object, or the environment variable "DOCUMENT_URI" be
present.

The value should be an absolute uri.

echomsg
The default message to be returned for the "echo" command when the
variable called is not defined.

Example:

$ssi->echomsg( '[Value Undefined]' );
## or in the document itself



would produce:

[Value Undefined]

encode_base64
Encode data provided into base64. When running under Apache mod_perl,
this uses "encode" in APR::Base64 module, otherwise it uses "encode" in
MIME::Base64

If the data have the perl internal utf8 flag on as checked with
"is_utf8" in Encode, this will encode the data into utf8 using "encode"
in Encode before encoding it into base64.

Please note that the base64 encoded resulting data is all on one line,
similar to what Apache would do. The data is NOT broken into lines of 76
characters.

If an error occurred during encoding, it will return undef and set an
"error" object accordingly.

encode_entities
Encode data into html entities. This uses "encode_entities" in
HTML::Entities

If an error occurred during encoding, it will return undef and set an
"error" object accordingly.

Example:

$ssi->encode_entities( 'Tous les êtres humains naissent libres et égaux en dignité et en droits.' );
# Tous les Ãªtres humains naissent libres et Ã©gaux en dignitÃ© et en droits.

encode_uri
Encode uri data. This uses "uri_escape_utf8" in URI::Escape.

Not to be confused with x-www-form-urlencoded data. For that see
"encode_url"

If an error occurred during encoding, it will return undef and set an
"error" object accordingly.

Example:

$ssi->encode_uri( 'https://www.example.com/' );
# https%3A%2F%2Fwww.example.com%2F

encode_url
Encode data provided into an x-www-form-urlencoded string. When using
Apache mod_perl, this uses "encode" in APR::Request, otherwise it uses
"url_encode_utf8" in URL::Encode (its XS version)

If an error occurred during decoding, it will return undef and set an
"error" object accordingly.

Example:

$ssi->encode_url( 'Tous les êtres humains naissent libres et égaux en dignité et en droits.' );
# Tous les êtres humains naissent libres et égaux en dignité et en droits.

errmsg
Sets or gets the error message to be displayed in lieu of a faulty ssi
directive. This is the same behaviour as in Apache.

error
Retrieve the error object set. This is a Module::Generic::Error object.

This module does not die nor "croak", but instead returns undef when an
error occurs and set the error object.

find_file
Provided with a file path, and this will resolve any variable used and
attempt to look it up as a file if the argument *file* is provided with
a file path as a value, or as a URI if the argument "virtual" is
provided as an argument.

It returns a Apache2::SSIFile object which is stringifyable and contain
the file path.

html
Sets or gets the html data to be processed.

lookup_file
Provided with a file path and this will look up the file.

When using Apache, this will call "lookup_file" in Apache2::SubRequest.
Outside of Apache, this will mimick Apache's lookup_file method by
searching the file relative to the directory of the current document
being served, i.e. the "document_uri".

As per Apache SSI documentation, you cannot specify a path starting with
"/" or "../"

It returns a Apache2::SSIFile object.

lookup_uri
Provided with an uri, and this will loo it up and return a
Apache2::SSIFile object.

Under Apache mod_perl, this uses "lookup_uri" in Apache2::SubRequest to
achieve that. Outside of Apache it will attempt to lookup the uri
relative to the document root if it is an absolute uri or to the current
document uri.

mod_perl
Returns true when running under mod_perl, false otherwise.

parse
Provided with html data and if none is provided will use the data
specified with the method "html", this method will parse the html and
process the ssi directives.

It returns the html string with the ssi result.

parse_config
Provided with an hash reference of parameters and this sets three of the
object parameters that can also be set during object instantiation:

*errmsg*
The value is a message that is sent back to the client if the echo
element attempts to echo an undefined variable.

This overrides any default value set for the parameter *echomsg*
upon object instantiation.

*errmsg*
This is the default error message to be used as the result for a
faulty ssi directive.

See the "errmsg" method.

*sizefmt*
This is the format to be used to format the files size. Value can be
either "bytes" or "abbrev"

See the "sizefmt" method.

*timefmt*
This is the format to be used to format the dates and times. The
value is a date formatting based on "strftime" in POSIX

See the "sizefmt" method.

parse_echo
Provided with an hash reference of parameter and this process the "echo"
ssi directive and returns its output as a string.

For example:

Query string passed: 

There are a number of standard environment variable accessible under SSI
on top of other environment variables set. See "SSI Directives"

parse_echo_date_gmt
Returns the current date with time zone set to gmt and based on the
provided format or the format available for the current locale such as
"ja_JP" or "en_GB".

parse_echo_date_local
Returns the current date with time zone set to the local time zone
whatever that may be and on the provided format or the format available
for the current locale such as "ja_JP" or "en_GB".

Example:



parse_echo_document_name
Returns the document name. Under Apache, this returns the environment
variable "DOCUMENT_NAME", if set, or the base name of the value returned
by "filename" in Apache2::RequestRec

Outside of Apache, this returns the environment variable
"DOCUMENT_NAME", if set, or the base name of the value for
"document_uri"

Example:



parse_echo_document_uri
Returns the value of "document_uri"

Example:



parse_echo_last_modified
This returns document last modified date. Under Apache, there is a
standard environment variable called "LAST_MODIFIED" (see the section on
"SSI Directives"), and if somehow absent, it will return instead the
formatted last modification datetime for the file returned with
"filename" in Apache2::RequestRec. The formatting of that date follows
whatever format provided with "timefmt" or by default the datetime
format for the current locale (e.g. "ja_JP").

Outside of Apache, the similar result is achieved by returning the value
of the environment variable "LAST_MODIFIED" if available, or the
formatted datetime of the document uri as set with "document_uri"

Example:



parse_exec
Provided with an hash reference of parameters and this process the
"exec" ssi directives.

Example:



or



parse_elif
Parse the "elif" condition.

Example:


Hi, should print

Shouldn't print

Shouldn't print


parse_else
Parse the "else" condition.

See "parse_elif" above for example.

parse_endif
Parse the "endif" condition.

See "parse_elif" above for example.

parse_flastmod
Process the ssi directive "flastmod"

Provided with an hash reference of parameters and this will return the
formatted date time of the file last modification time.

parse_fsize
Provided with an hash reference of parameters and this will return the
formatted file size.

The output is affected by the value of "sizefmt". If its value is
"bytes", it will return the raw size in bytes, and if its value is
"abbrev", it will return its value formated in kilo, mega or giga units.

Example


This file size is 

would return:

This file size is 12.7M

Or:


This file size is 

would return:

This file size is 13,316,917 bytes

The size value before formatting is a Module::Generic::Number and the
output is formatted using Number::Format by calling "format" in
Module::Generic::Number

parse_func_base64
Returns the arguments provided into a base64 string.

If the arguments are utf8 data with perl internal flag on, as checked
with "is_utf8" in Encode, this will encode the data into utf8 with
"encode" in Encode before encoding it into base64.

Example:



Payload matches

Sorry, this failed


parse_func_env
Return first match of note, reqenv, and osenv

Example:


Showing Japanese data

Defaulting to English


parse_func_escape
Escape special characters in %hex encoding.

Example:


Please go to <a href=""></a>

parse_func_http
Get HTTP request header; header names may be added to the Vary header.

Example:


You're good to go.


parse_func_ldap
Escape characters as required by LDAP distinguished name escaping
(RFC4514) and LDAP filter escaping (RFC4515).

See Apache documentation
<https://httpd.apache.org/docs/trunk/en/expr.html#page-header> for more
information

Example:


# Tous les êtres humains naissent libres \28et égaux\29 en dignité et\5c en\5c droits.\5cn

parse_func_md5
Hash the string using MD5, then encode the hash with hexadecimal
encoding.

If the arguments are utf8 data with perl internal flag on, as checked
with "is_utf8" in Encode, this will encode the data into utf8 with
"encode" in Encode before encoding it with md5.

Example:


You're good to go.


parse_func_note
Lookup request note



Showing special message


parse_func_osenv
Lookup operating system environment variable


Showing English language


parse_func_replace
replace(string, "from", "to") replaces all occurrences of "from" in the
string with "to".

Example:


This worked!

Nope, it failed.


parse_func_req
See "parse_func_http"

parse_func_reqenv
Lookup request environment variable (as a shortcut, v can also be used
to access variables).

This is only different from "parse_func_env" under Apache.

See "parse_func_env"

Example:


This worked!

Nope, it failed.


parse_func_req_novary
Same as "parse_func_req", but header names will not be added to the Vary
header.

parse_func_resp
Get HTTP response header.

Example:


This worked!

Nope, it failed.


parse_func_sha1
Hash the string using SHA1, then encode the hash with hexadecimal
encoding.

Example:


This worked!

Nope, it failed.


parse_func_tolower
Convert string to lower case.

Example:


This worked!

Nope, it failed.


parse_func_toupper
Convert string to upper case.

Example:


This worked!

Nope, it failed.


parse_func_unbase64
Decode base64 encoded string, return truncated string if 0x00 is found.

Example:


This worked!

Nope, it failed.


parse_func_unescape
Unescape %hex encoded string, leaving encoded slashes alone; return
empty string if %00 is found.

Example:


This worked!

Nope, it failed.


parse_if
Parse the "if" condition.

See "parse_elif" above for example.

parse_include
Provided with an hash reference of parameters and this process the ssi
directive "include", which is arguably the most used.

It will try to resolve the file to include by calling "find_file" with
the same arguments this is called with.

Under Apache, if the previous look up succeeded, it calls "run" in
Apache2::SubRequest

Outside of Apache, it reads the entire file, utf8 decode it and return
it.

parse_perl
Provided with an hash reference of parameters and this parse some perl
command and returns the output as a string.

Example:



or



parse_printenv
This returns a list of environment variables sorted and their values.

parse_set
Provided with an hash reference of parameters and this process the ssi
directive "set".

Possible parameters are:

*decoding*
The decoding of the variable before it is set. This can be "none",
"url", "urlencoded", "base64" or "entity"

*encoding*
This instruct to encode the variable value before display. It can
the same possible value as for decoding.

*value*
The string value for the variable to be set.

*var*
The variable name

Example:




See the Apache SSI documentation
<https://httpd.apache.org/docs/current/en/mod/mod_include.html> for more
information.

parse_ssi
Provided with the html data as a string and this will parse its embedded
ssi directives and return its output as a string.

If it fails, it sets an "error" and returns an empty string.

remote_ip
Sets or gets the remote ip address of the visitor.

Under Apache mod_perl, this will call "remote_ip" in
Apache2::Connection, and otherwise this will get the value from the
environment variable "REMOTE_ADDR"

This value can also be overriden by being provided during object
instantiation.

# Pretend the ssi directives are accessed from this ip
$ssi->remote_ip( '192.1.68.2.20' );

This is useful when one wants to check how the rendering will be when
accessed from certain ip addresses.

This is used primarily when there is an expression such as


Visitor is part of my private network


or





sizefmt
Sets or gets the formatting for file sizes. Value can be either "bytes"
or "abbrev"

timefmt
Sets or gets the formatting for date and time values. The format takes
the same values as "strftime" in POSIX

SSI Directives
config



# Thursday 24 December 2020


echo



Encoding can be either "entity", "url" or "none"

exec
# pwd is "print working directory" in shell



include
# Filesystem file path

# Relative to the document root


flastmod



fsize



printenv


set


if, elif, endif and else

I will print a lot of debugging

Debugging output will be reasonable


or with new version of Apache SSI:

No such file or directory.

Please let the admin of the <a href=""referring site</a> know about their dead link.


functions
Apache SSI supports the following functions, as of Apache version 2.4.

See Apache documentation
<https://httpd.apache.org/docs/current/en/expr.html#page-header> for
detailed description of what they do.

You can also refer to the methods "parse_func_*" documented above, which
implement those Apache functions.

*base64*
*env*
*escape*
*http*
*ldap*
*md5*
*note*
*osenv*
*replace*
*req*
*reqenv*
*basereq_novary64*
*resp*
*sha1*
*tolower*
*toupper*
*unbase64*
*unescape*

variables
On top of all environment variables available, Apache makes the
following ones also accessible:

DATE_GMT
DATE_LOCAL
DOCUMENT_ARGS
DOCUMENT_NAME
DOCUMENT_PATH_INFO
DOCUMENT_URI
LAST_MODIFIED
QUERY_STRING_UNESCAPED
USER_NAME

See Apache documentation
<https://httpd.apache.org/docs/current/en/mod/mod_include.html#page-head
er> and this page too
<https://httpd.apache.org/docs/current/en/expr.html#page-header> for
more information.

expressions
There is reasonable, but limited support for Apache expressions. For
example, the followings are supported

In the examples below, we use the variable "QUERY_STRING", but you can
use any other variable of course.

The regular expression are the ones PCRE compliant, so your perl regular
expressions should work.






# works also with eq, ne, lt, le, gt and ge


# Other operators work too, namely == != < <= > >= =~ !~



# Checks the remote ip is part of this subnet



# Checks if variable is non-empty

# Checks if variable is empty

# Checks if the visitor can access the uri /restricted/uri


For subnet checks, this uses Net::Subnet

Expressions that would not work out side of Apache:



See Apache documentation <http://httpd.apache.org/docs/2.4/en/expr.html>
for more information.

CREDITS
Credits to Ken Williams for his implementation of Apache::SSI from which
I borrowed code.

AUTHOR
Jacques Deguest <[email protected]>

CPAN ID: jdeguest

<https://git.deguest.jp/jack/Apache2-SSI>

SEE ALSO
mod_include, mod_perl(3), Apache::SSI,
<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_PerlOutpu
tFilterHandler_>

COPYRIGHT & LICENSE
Copyright (c) 2018-2019 DEGUEST Pte. Ltd.

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