Apache2-SSI
view release on metacpan or search on metacpan
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;
*debug*
Sets the debug level. Starting from 3, this will output on the
STDERR or in Apache error log a lot of debugging output.
*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.
*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 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> 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> 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 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" or to
"apache_response_handler"
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,
an array reference to store the output recursively and an optional hash
reference of parameters.
It parse recursively the structure provided in the hash reference to
provide the perl equivalent for each Apache2 expression component.
It returns the array reference provided used as the content buffer. This
array is used by "parse_expr" and then joined using a single space to
form a string of perl expression to be eval'ed.
apache_filter
Set or get the Apache2::Filter object.
When running under Apache mod_perl this is set automatically from the
special "handler" method.
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.
path_info
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" 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 module:
$ssi->query_string( $uri->query );
The query string value is set automatically when you provide an
document_uri 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
for version 2.2 or lower and will call "useragent_ip" in
Apache2::Connection 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 also has a "remote_addr" in Apache2::Connection
method, but this returns a APR::SockAddr 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
request_uri
This is an alias for "document_uri"
server_version
Returns the server version as a version object can caches that value.
Under mod_perl2, it uses "get_server_description" in Apache2::ServerUtil
and outside of mod_perl, it tries to find "apxs" using File::Which 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
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
This is taken from Apache documentation and summarised here for
convenience and clarity to the perl community.
config
<!--#config errmsg="Error occurred" sizefmt="abbrev" timefmt="%B %Y" -->
<!--#config errmsg="Oopsie" -->
<!--#config sizefmt="bytes" -->
# Thursday 24 December 2020
<!--#config timefmt="%A $d %B %Y" -->
echo
<!--#set var="HTMl_TITLE" value="Un sujet intéressant" -->
<!--#echo var="HTMl_TITLE" encoding="entity" -->
Encoding can be either "entity", "url" or "none"
exec
# pwd is "print working directory" in shell
<!--#exec cmd="pwd" -->
*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-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 <http://www.pcre.org/>
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
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>
for more information.
CREDITS
Credits to Ken Williams for his implementation of Apache::SSI from which
I borrowed some code.
AUTHOR
Jacques Deguest <jack@deguest.jp>
CPAN ID: jdeguest
<https://gitlab.com/jackdeguest/Apache2-SSI>
SEE ALSO
Apache2::SSI::File, Apache2::SSI::Finfo, Apache2::SSI::Notes,
Apache2::SSI::URI, Apache2::SSI::SharedMem and Apache2::SSI::SemStat
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) 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 1.179 second using v1.01-cache-2.11-cpan-39bf76dae61 )