Apache2-SSI
view release on metacpan or search on metacpan
[Apache2::RequestUtil](https://metacpan.org/pod/Apache2::RequestUtil){.perl-module}
and calling [\"request\" in
Apache2::RequestUtil](https://metacpan.org/pod/Apache2::RequestUtil#request){.perl-module}
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\"](#handler){.perl-module} method, such as:
my $r = $f->r; # $f is the Apache2::Filter object provided by Apache
apache\_response\_handler
-------------------------
This method is called from [\"handler\"](#handler){.perl-module} to
handle the Apache response when this module
[Apache2::SSI](https://metacpan.org/pod/Apache2::SSI){.perl-module} is
used as a response handler.
See also
[\"apache\_filter\_handler\"](#apache_filter_handler){.perl-module}
clone
-----
Create a clone of the object and return it.
decode\_base64
--------------
Decode base64 data provided. When running under Apache mod\_perl, this
uses [\"decode\" in
APR::Base64](https://metacpan.org/pod/APR::Base64#decode){.perl-module}
module, otherwise it uses [\"decode\" in
MIME::Base64](https://metacpan.org/pod/MIME::Base64#decode){.perl-module}
If the decoded data contain utf8 data, this will decoded the utf8 data
using [\"decode\" in
Encode](https://metacpan.org/pod/Encode#decode){.perl-module}
If an error occurred during decoding, it will return undef and set an
[\"error\"](#error){.perl-module} object accordingly.
decode\_entities
----------------
Decode html data containing entities. This uses [\"decode\_entities\" in
HTML::Entities](https://metacpan.org/pod/HTML::Entities#decode_entities){.perl-module}
If an error occurred during decoding, it will return undef and set an
[\"error\"](#error){.perl-module} 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](https://metacpan.org/pod/URI::Escape#uri_unescape){.perl-module}.
Not to be confused with x-www-form-urlencoded data. For that see
[\"decode\_url\"](#decode_url){.perl-module}
If an error occurred during decoding, it will return undef and set an
[\"error\"](#error){.perl-module} 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](https://metacpan.org/pod/APR::Request#decode){.perl-module}
and [\"decode\" in
Encode](https://metacpan.org/pod/Encode#decode){.perl-module}, otherwise
it uses [\"url\_decode\_utf8\" in
URL::Encode](https://metacpan.org/pod/URL::Encode#url_decode_utf8){.perl-module}
(its XS version) to achieve the same result.
If an error occurred during decoding, it will return undef and set an
[\"error\"](#error){.perl-module} object accordingly.
Example:
$ssi->decode_url( 'Tous+les+%C3%83%C2%AAtres+humains+naissent+libres+et+%C3%83%C2%A9gaux+en+dignit%C3%83%C2%A9+et+en+droits.' );
# Tous les êtres humains naissent libres et égaux en dignité et en droits.
document\_filename
------------------
This is an alias for [\"filename\" in
Apache2::SSI::URI](https://metacpan.org/pod/Apache2::SSI::URI#filename){.perl-module}
document\_directory
-------------------
Returns an
[Apache2::SSI::URI](https://metacpan.org/pod/Apache2::SSI::URI){.perl-module}
object of the current directory of the
[\"document\_uri\"](#document_uri){.perl-module} provided.
document\_path
--------------
Sets or gets the uri path to the document. This is the same as
[\"document\_uri\"](#document_uri){.perl-module}, except it is striped
from [\"query\_string\"](#query_string){.perl-module} and
[\"path\_info\"](#path_info){.perl-module}.
document\_root
--------------
Sets or gets the document root.
Wen running under Apache mod\_perl, this value will be available
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
<!--#config echomsg="[Value Undefined]" -->
<!--#echo var="NON_EXISTING" encoding="none" -->
would produce:
[Value Undefined]
encode\_base64
--------------
Encode data provided into base64. When running under Apache mod\_perl,
this uses [\"encode\" in
APR::Base64](https://metacpan.org/pod/APR::Base64#encode){.perl-module}
module, otherwise it uses [\"encode\" in
MIME::Base64](https://metacpan.org/pod/MIME::Base64#encode){.perl-module}
If the data have the perl internal utf8 flag on as checked with
[\"is\_utf8\" in
Encode](https://metacpan.org/pod/Encode#is_utf8){.perl-module}, this
will encode the data into utf8 using [\"encode\" in
Encode](https://metacpan.org/pod/Encode#encode){.perl-module} 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\"](#error){.perl-module} object accordingly.
encode\_entities
----------------
Encode data into html entities. This uses [\"encode\_entities\" in
HTML::Entities](https://metacpan.org/pod/HTML::Entities#encode_entities){.perl-module}
If an error occurred during encoding, it will return undef and set an
[\"error\"](#error){.perl-module} 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](https://metacpan.org/pod/URI::Escape#uri_escape_utf8){.perl-module}.
Not to be confused with x-www-form-urlencoded data. For that see
[\"encode\_url\"](#encode_url){.perl-module}
If an error occurred during encoding, it will return undef and set an
[\"error\"](#error){.perl-module} 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](https://metacpan.org/pod/APR::Request#encode){.perl-module},
otherwise it uses [\"url\_encode\_utf8\" in
URL::Encode](https://metacpan.org/pod/URL::Encode#url_encode_utf8){.perl-module}
(its XS version)
If an error occurred during decoding, it will return undef and set an
[\"error\"](#error){.perl-module} object accordingly.
Example:
$ssi->encode_url( 'Tous les êtres humains naissent libres et égaux en dignité et en droits.' );
# Tous+les+%C3%83%C2%AAtres+humains+naissent+libres+et+%C3%83%C2%A9gaux+en+dignit%C3%83%C2%A9+et+en+droits.
env
---
Sets or gets the value for an environment variable. Or, if no
environment variable name is provided, it returns the entire hash
reference. This method is intended to be used by users of this module,
not by developers wanting to inherit from it.
Note that the environment variable hash is unique for each new object,
so it works like [\"subprocess\_env\" in
Apache2::RequestRec](https://metacpan.org/pod/Apache2::RequestRec#subprocess_env){.perl-module},
meaning each process has its set of environment variable.
When a value is set for an environment variable that has an equivalent
name, it will call the method as well with the new value provided. This
is done to ensure data consistency and also additional processing if
necessary.
For example, let assume you set the environment variable `REQUEST_URI`
or `DOCUMENT_URI` like this:
$ssi->env( REQUEST_URI => '/some/path/to/file.html?q=something&l=ja_JP' );
This will, in turn, call [\"request\_uri\"](#request_uri){.perl-module},
which is an alias for
[document\_uri](https://metacpan.org/pod/document_uri){.perl-module} and
this method will get the uri, path info and query string from the value
provided and set those values accordingly, so they can be available when
parsing.
<!--#config sizefmt="abbrev" -->
This file size is <!--#fsize file="/some/filesystem/path/to/archive.tar.gz" -->
would return:
This file size is 12.7M
Or:
<!--#config sizefmt="bytes" -->
This file size is <!--#fsize virtual="/some/filesystem/path/to/archive.tar.gz" -->
would return:
This file size is 13,316,917 bytes
The size value before formatting is a
[Module::Generic::Number](https://metacpan.org/pod/Module::Generic::Number){.perl-module}
and the output is formatted using
[Number::Format](https://metacpan.org/pod/Number::Format){.perl-module}
by calling [\"format\" in
Module::Generic::Number](https://metacpan.org/pod/Module::Generic::Number#format){.perl-module}
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](https://metacpan.org/pod/Encode#is_utf8){.perl-module}, this
will encode the data into utf8 with [\"encode\" in
Encode](https://metacpan.org/pod/Encode#encode){.perl-module} before
encoding it into base64.
Example:
<!--#set var="payload" value='{"sub":"1234567890","name":"John Doe","iat":1609047546}' encoding="base64" -->
<!--#if expr="$payload == 'eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNjA5MDQ3NTQ2fQo='" -->
Payload matches
<!--#else -->
Sorry, this failed
<!--#endif -->
parse\_func\_env
----------------
Return first match of
[note](https://metacpan.org/pod/note){.perl-module},
[reqenv](https://metacpan.org/pod/reqenv){.perl-module}, and
[osenv](https://metacpan.org/pod/osenv){.perl-module}
Example:
<!--#if expr="env( $QUERY_STRING ) == /\bl=ja_JP/" -->
Showing Japanese data
<!--#else -->
Defaulting to English
<!--#endif -->
parse\_func\_escape
-------------------
Escape special characters in %hex encoding.
Example:
<!--#set var="website" value="https://www.example.com/" -->
Please go to <a href="<!--#echo var='website' encoding='escape' -->"><!--#echo var="website" --></a>
parse\_func\_http
-----------------
Get HTTP request header; header names may be added to the Vary header.
Example:
<!--#if expr="http('X-API-ID') == 1234567" -->
You're good to go.
<!--#endif -->
However, outside of an Apache environment this will return the value of
the environment variable in the following order:
X-API-ID (i.e. the name as-is)
:
HTTP\_X\_API\_ID (i.e. adding `HTTP_` and replace `-` for `_`)
:
X\_API\_ID (i.e. same as above, but without the `HTTP_` prefix)
:
If none is found, it returns an empty string.
For an equivalent function for response headers, see
[\"parse\_func\_resp\"](#parse_func_resp){.perl-module}
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){.perl-module}
for more information
Example:
<!--#set var="phrase" value="%{ldap:'Tous les êtres humains naissent libres (et égaux) en dignité et\ en\ droits.\n'}" -->
# 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](https://metacpan.org/pod/Encode#is_utf8){.perl-module}, this
will encode the data into utf8 with [\"encode\" in
Encode](https://metacpan.org/pod/Encode#encode){.perl-module} before
encoding it with md5.
If it is running as an output filter handler, then some headers, such as
`Content-Type` will not be available, unless they have been set by a
script in a previous phase. Only basic headers will be available. For
more information, check the Apache/mod\_perl2 documentation on each
phase.
parse\_func\_sha1
-----------------
Hash the string using SHA1, then encode the hash with hexadecimal
encoding.
Example:
<!--#if expr="sha1('Tous les êtres humains naissent libres et égaux en dignité et en droits.') == '8c244078c64a51e8924ecf646df968094a818d59'" -->
This worked!
<!--#else -->
Nope, it failed.
<!--#endif -->
parse\_func\_tolower
--------------------
Convert string to lower case.
Example:
<!--#if expr="tolower('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.'" -->
This worked!
<!--#else -->
Nope, it failed.
<!--#endif -->
parse\_func\_toupper
--------------------
Convert string to upper case.
Example:
<!--#if expr="toupper('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.'" -->
This worked!
<!--#else -->
Nope, it failed.
<!--#endif -->
parse\_func\_unbase64
---------------------
Decode base64 encoded string, return truncated string if 0x00 is found.
Example:
<!--#if expr="unbase64('VG91cyBsZXMgw6p0cmVzIGh1bWFpbnMgbmFpc3NlbnQgbGlicmVzIGV0IMOpZ2F1eCBlbiBkaWduaXTDqSBldCBlbiBkcm9pdHMu') == 'Tous les êtres humains naissent libres et égaux en dignité et en droits.'" -->
This worked!
<!--#else -->
Nope, it failed.
<!--#endif -->
parse\_func\_unescape
---------------------
Unescape %hex encoded string, leaving encoded slashes alone; return
empty string if %00 is found.
Example:
<!--#if expr="unescape('https%3A%2F%2Fwww.example.com%2F') == 'https://www.example.com/'" -->
This worked!
<!--#else -->
Nope, it failed.
<!--#endif -->
parse\_if
---------
Parse the `if` condition.
See [\"parse\_elif\"](#parse_elif){.perl-module} 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\"](#find_file){.perl-module} with the same arguments this
is called with.
Under Apache, if the previous look up succeeded, it calls [\"run\" in
Apache2::SubRequest](https://metacpan.org/pod/Apache2::SubRequest#run){.perl-module}
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:
<!--#perl sub="sub{ print 'Hello!' }" -->
or
<!--#perl sub="package::subroutine" -->
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`
<!--#include virtual="/footer.html" -->
flastmod
--------
<!--#flastmod file="/home/john/var/quote_of_the_day.txt" -->
<!--#flastmod virtual="/copyright.html" -->
fsize
-----
<!--#fsize file="/download/software-v1.2.tgz" -->
<!--#fsize virtual="/images/logo.jpg" -->
printenv
--------
<!--#printenv -->
set
---
<!--#set var="debug" value="2" -->
if, elif, endif and else
------------------------
<!--#if expr="$debug > 1" -->
I will print a lot of debugging
<!--#else -->
Debugging output will be reasonable
<!--#endif -->
or with new version of Apache SSI:
No such file or directory.
<!--#if expr="v('HTTP_REFERER') != ''" -->
Please let the admin of the <a href="<!--#echo encoding="url" var="HTTP_REFERER" -->"referring site</a> know about their dead link.
<!--#endif -->
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){.perl-module}
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*
:
*req\_novary*
:
*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-header){.perl-module}
and [this page
too](https://httpd.apache.org/docs/current/en/expr.html#page-header){.perl-module}
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.
( run in 0.959 second using v1.01-cache-2.11-cpan-39bf76dae61 )