Apache2-SSI
view release on metacpan or search on metacpan
*document\_root*
: This is only necessary to be provided if this is not running under
Apache mod\_perl. Without this value,
[Apache2::SSI](https://metacpan.org/pod/Apache2::SSI){.perl-module}
has no way to guess the document root and will not be able to
function properly and will return an
[\"error\"](#error){.perl-module}.
*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\"](#parse){.perl-module} as its
first argument when you call it.
*legacy*
: Takes a boolean value suchas `1` or `0` to indicate whether the
Apache2 expression supported accepts legacy style.
Legacy Apache expression typically allows for perl style variable
`${REQUEST_URI}` versus the modern style of `%{REQUEST_URI}` and
just an equal sign to imply a regular expression such as:
$HTTP_COOKIES = /lang\%22\%3A\%22([a-zA-Z]+\-[a-zA-Z]+)\%22\%7D;?/
Modern expression equivalent would be:
%{HTTP_COOKIES} =~ /lang\%22\%3A\%22([a-zA-Z]+\-[a-zA-Z]+)\%22\%7D;?/
See
[Regexp::Common::Apache2](https://metacpan.org/pod/Regexp::Common::Apache2){.perl-module}
for more information.
See also the property *trunk* to enable experimental expressions.
*remote\_ip*
: This is used when you want to artificially set the remote ip
address, i.e. the address of the visitor accessing the page. This is
used essentially by the SSI directive:
my $ssi = Apache2::SSI->new( remote_ip => '192.168.2.10' ) ||
die( Apache2::SSI->error );
<!--#if expr="-R '192.168.2.0/24' || -R '127.0.0.1/24'" -->
Remote ip is part of my private network
<!--#else -->
Go away!
<!--#endif -->
*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.
See [Apache2
documentation](https://httpd.apache.org/docs/current/en/howto/ssi.html){.perl-module}
for more information on this.
*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.
See [Apache2
documentation](https://httpd.apache.org/docs/current/en/howto/ssi.html){.perl-module}
for more information on this.
*trunk*
: This takes a boolean value such as `0` or `1` and when enabled this
allows the support for Apache2 experimental expressions.
See
[Regexp::Common::Apache2](https://metacpan.org/pod/Regexp::Common::Apache2){.perl-module}
for more information.
Also, see the property *legacy* to enable legacy Apache2
expressions.
handler
-------
This is a key method expected by mod\_perl. Depending on how this module
is used, it will redirect either to
[\"apache\_filter\_handler\"](#apache_filter_handler){.perl-module} or
to
[\"apache\_response\_handler\"](#apache_response_handler){.perl-module}
ap2perl\_expr
-------------
This method is used to convert Apache2 expressions into perl equivalents
to be then eval\'ed.
It takes an hash reference provided by [\"parse\" in
Apache2::Expression](https://metacpan.org/pod/Apache2::Expression#parse){.perl-module},
an array reference to store the output recursively and an optional hash
reference of parameters.
Sets or gets the path info for the current uri.
Example:
my $string = $ssi->path_info;
$ssi->path_info( '/my/path/info' );
The path info value is also set automatically when
[\"document\_uri\"](#document_uri){.perl-module} is called, such as:
$ssi->document_uri( '/some/path/to/file.html/my/path/info?q=something&l=ja_JP' );
This will also set automatically the `PATH_INFO` environment variable.
query\_string
-------------
Set or gets the query string for the current uri.
Example:
my $string = $ssi->query_string;
$ssi->query_string( 'q=something&l=ja_JP' );
or, using the [URI](https://metacpan.org/pod/URI){.perl-module} module:
$ssi->query_string( $uri->query );
The query string value is set automatically when you provide an
[document\_uri](https://metacpan.org/pod/document_uri){.perl-module}
upon instantiation or after:
$ssi->document_uri( '/some/path/to/file.html?q=something&l=ja_JP' );
This will also set automatically the `QUERY_STRING` environment
variable.
remote\_ip
----------
Sets or gets the remote ip address of the visitor.
Under Apache mod\_perl, this will call [\"remote\_ip\" in
Apache2::Connection](https://metacpan.org/pod/Apache2::Connection#remote_ip){.perl-module}
for version 2.2 or lower and will call [\"useragent\_ip\" in
Apache2::Connection](https://metacpan.org/pod/Apache2::Connection#useragent_ip){.perl-module}
for version above 2.2, 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.168.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
<!--#if expr="-R '192.168.1.0/24' -->
Visitor is part of my private network
<!--#endif -->
or
<!--#if expr="v('REMOTE_ADDR') -R '192.168.1.0/24' -->
<!--#include file="/home/john/special_hidden_login_feature.html" -->
<!--#endif -->
[Apache2::Connection](https://metacpan.org/pod/Apache2::Connection){.perl-module}
also has a [\"remote\_addr\" in
Apache2::Connection](https://metacpan.org/pod/Apache2::Connection#remote_addr){.perl-module}
method, but this returns a
[APR::SockAddr](https://metacpan.org/pod/APR::SockAddr){.perl-module}
object that is used to get the binary version of the ip. However you can
also get the string version like this:
use APR::SockAddr ();
my $ip = $r->connection->remote_addr->ip_get();
Versions above 2.2 make a distinction between ip from direct connection,
or the real ip behind a proxy, i.e. [\"useragent\_ip\" in
Apache2::Connection](https://metacpan.org/pod/Apache2::Connection#useragent_ip){.perl-module}
request\_uri
------------
This is an alias for [\"document\_uri\"](#document_uri){.perl-module}
server\_version
---------------
Returns the server version as a
[version](https://metacpan.org/pod/version){.perl-module} object can
caches that value.
Under mod\_perl2, it uses [\"get\_server\_description\" in
Apache2::ServerUtil](https://metacpan.org/pod/Apache2::ServerUtil#get_server_description){.perl-module}
and outside of mod\_perl, it tries to find `apxs` using
[File::Which](https://metacpan.org/pod/File::Which){.perl-module} and in
last resort, tries to find the `apache2` or `httpd` binary to get its
version information.
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](https://metacpan.org/pod/POSIX#strftime){.perl-module}
Encoding
========
At present time, the html data are treated as utf8 data and decoded and
encoded back as such.
If there is a need to broaden support for other charsets, let me know.
SSI Directives
==============
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.
The regular expression are the ones
[PCRE](http://www.pcre.org/){.perl-module} compliant, so your perl
regular expressions should work.
<!--#if expr="$QUERY_STRING = 'something'" -->
<!--#if expr="v('QUERY_STRING') = 'something'" -->
<!--#if expr="%{QUERY_STRING} = 'something'" -->
<!--#if expr="$QUERY_STRING = /^something/" -->
<!--#if expr="$QUERY_STRING == /^something/" -->
# works also with eq, ne, lt, le, gt and ge
<!--#if expr="9 gt 3" -->
<!--#if expr="9 -gt 3" -->
# Other operators work too, namely == != < <= > >= =~ !~
<!--#if expr="9 > 3" -->
<!--#if expr="9 !> 3" -->
<!--#if expr="9 !gt 3" -->
# Checks the remote ip is part of this subnet
<!--#if expr="-R 192.168.2.0/24" -->
<!--#if expr="192.168.2.10 -R 192.168.2.0/24" -->
<!--#if expr="192.168.2.10 -ipmatch 192.168.2.0/24" -->
# Checks if variable is non-empty
<!--#if expr="-n $some_variable" -->
# Checks if variable is empty
<!--#if expr="-z $some_variable" -->
# Checks if the visitor can access the uri /restricted/uri
<!--#if expr="-A /restricted/uri" -->
For subnet checks, this uses
[Net::Subnet](https://metacpan.org/pod/Net::Subnet){.perl-module}
Expressions that would not work outside of Apache, i.e. it will return
an empty string:
<!--#expr="%{HTTP:X-example-header} in { 'foo', 'bar', 'baz' }" -->
See [Apache
documentation](http://httpd.apache.org/docs/2.4/en/expr.html){.perl-module}
for more information.
CREDITS
=======
Credits to Ken Williams for his implementation of
[Apache::SSI](https://metacpan.org/pod/Apache::SSI){.perl-module} from
which I borrowed some code.
AUTHOR
======
Jacques Deguest \<`jack@deguest.jp`{classes="ARRAY(0x564839326528)"}\>
CPAN ID: jdeguest
<https://gitlab.com/jackdeguest/Apache2-SSI>
SEE ALSO
========
[Apache2::SSI::File](https://metacpan.org/pod/Apache2::SSI::File){.perl-module},
[Apache2::SSI::Finfo](https://metacpan.org/pod/Apache2::SSI::Finfo){.perl-module},
[Apache2::SSI::Notes](https://metacpan.org/pod/Apache2::SSI::Notes){.perl-module},
[Apache2::SSI::URI](https://metacpan.org/pod/Apache2::SSI::URI){.perl-module},
[Apache2::SSI::SharedMem](https://metacpan.org/pod/Apache2::SSI::SharedMem){.perl-module}
and
[Apache2::SSI::SemStat](https://metacpan.org/pod/Apache2::SSI::SemStat){.perl-module}
mod\_include, mod\_perl(3),
[Apache::SSI](https://metacpan.org/pod/Apache::SSI){.perl-module},
<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.
( run in 0.390 second using v1.01-cache-2.11-cpan-39bf76dae61 )