The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-apacheSSI-0.96
River stage zero No dependents
++
/ CGI::apacheSSI

NAME

CGI::apacheSSI - Parse apache SSI directives in your CGI scripts

SYNOPSIS

The simplest use case is something like this:

   require CGI::apacheSSI;
   my $ssi = CGI::apacheSSI->new();
   $ssi->set('MY_SSI_VAR' => "this var can be accessed in /myfile.shtml");
   print $ssi->include(virtual => '/myfile.shtml');

autotie STDOUT or any other open filehandle:

   use CGI::apacheSSI (autotie => 'STDOUT');

   print $shtml; # browser sees resulting HTML

or tie it yourself to any open filehandle:

   use CGI::apacheSSI;

   open(FILE,'+>'.$html_file) or die $!;
   $ssi = tie(*FILE, 'CGI::apacheSSI', filehandle => 'FILE');
   print FILE $shtml; # HTML arrives in the file

or use the object-oriented interface:

   use CGI::apacheSSI;

   $ssi = CGI::apacheSSI->new();

   $ssi->if('"$varname" =~ /^foo/');
      $html .= $ssi->process($shtml);
   $ssi->elsif($virtual);
      $html .= $ssi->include(virtual => $filename);
   $ssi->else();
      $html .= $ssi->include(file => $filename);
   $ssi->endif();

   print $ssi->exec(cgi => $url);
   print $ssi->flastmod(file => $filename);

or roll your own favorite flavor of SSI:

   package CGI::apacheSSI::MySSI;
   use CGI::apacheSSI;
   @CGI::apacheSSI::MySSI::ISA = qw(CGI::apacheSSI);

   sub include {
      my($self,$type,$file_or_url) = @_; 
      # my idea of include goes something like this...
      return $html;
   }
   1;

or use .htaccess to include all files in a dir:

   # in .htaccess:
   Action cgi-ssi /cgi-bin/ssi/process.cgi
   <FilesMatch "\.shtml">
      SetHandler cgi-ssi
   </FilesMatch>


   # in /cgi-bin/ssi/process.cgi:
   
   #!/usr/local/bin/perl 
   use CGI::apacheSSI;
   CGI::apacheSSI->handler();

DESCRIPTION

CGI::apacheSSI is a fork of the CGI::SSI project, with the intention of making it function more like Apache's SSI parser, mod_include, and fixing a few other long standing bugs along the way. The largest changes are the complete overhaul of the parsing engine and test expression code, which is now no longer "perlish". A future feature could be added to do perlish expressions via something like a "perl_expr" directive, but since I didn't need it, I didn't implement it. The rest is basically the same, so a lot of the documentation below is taken directly from CGI::SSI.

Needless to say: "USE AT YOUR OWN RISK".

CGI::apacheSSI is meant to be an easy way to add the ability to filter and parse (even nested!) existing shtml in CGI scripts without the need to modify any of the files to be parsed.

Limitations in a CGI script's knowledge of how the server behaves make some SSI directives impossible to imitate from a CGI script, but this module is a valiant attempt at it, nonetheless. Please also note that the main target of emulation (ie, the version used to test against during development) was Apache 2.2.22, and there are differences between how it parses certain things and how Apache 2.4.x does (not to mention all the undocumented behavior). But it shouldn't be noticeable except in fringe cases (like magical flying quotes that cause parsing errors). You might never run into these differences until you have (very specific) errors in your SSI markup.

Be aware that Apache's mod_include treats single quotes ' slightly differently than double quotes " and backticks ` when you use those to wrap your expressions, and therefore so will CGI::apacheSSI.

I'm sure there are some interesting applications of this module so please do let me know if you use it for anything or if you cannibalized any of the code for a different project.

UNIMPLEMENTED FEATURES AND IMPORTANT INFO

There are many features not currently implemented, but these are some of the ones I am aware of that will definitely impede your ability to use this module as a faithful emulator of mod_include.

All server configuration directives are ignored

That means things like Options IncludesNOEXEC are not taken into consideration, and you might end up parsing pages you might not otherwise be able to.

include virtual for cgi scripts and mod_rewrite urls

The include virtual call cannot currently handle calls to cgi scripts or mod_rewrite urls. It is completely file-based, and is not currently capable of doing apache internal calls.

exec cgi is simply an alias to include virtual

In general, you are always advised to avoid the exec directive, and apache::SSI implements exec cgi as an alias for include virtual.

exec cmd needs to be explicitly enabled

Given the above, exec cmd is disabled by default, since, when enabled, it is simply a sub-call using backticks ``, leading to a big security liability. This can be set as follows:

    my $ssi = CGI::apacheSSI->new('_enable_exec_cmd' => 1);   # at instantiation time
    
    # or during usage: 
    $ssi->_enable_exec_cmd(1);    # to enable
    $ssi->_enable_exec_cmd(0);    # to disable

echo encoding

The echo command silently ignores "encoding" specifications.

USAGE

Most of the time, you'll simply want to filter shtml through STDOUT or some other open filehandle. autotie is available for STDOUT, but in general, you'll want to tie other filehandles yourself:

    $ssi = tie(*FH, 'CGI::apacheSSI', filehandle => 'FH');
    print FH $shtml;

Note that you'll need to pass the name of the filehandle to tie() as a named parameter. Other named parameters are possible, as detailed below. These parameters are the same as those passed to the new() method. However, new() will not tie a filehandle for you.

You may create and use multiple CGI::apacheSSI objects; they will not step on each others' variables.

Object-Oriented methods use the same general format so as to imitate SSI directives:

    <!--#include virtual="/foo/bar.footer" -->

would be

    $ssi->include(virtual => '/foo/bar.footer');

likewise,

    <!--#exec cgi="/cgi-bin/foo.cgi" -->

would be

    $ssi->exec(cgi => '/cgi-bin/foo.cgi');

Usually, if there's no chance for ambiguity, the first argument may be left out:

    <!--#echo var="var_name" -->

could be either

    $ssi->echo(var => 'var_name');

or

    $ssi->echo('var_name');

Likewise,

    $ssi->set(var => $varname, value => $value)

is the same as

    $ssi->set($varname => $value)
$ssi->new([%args])

Creates a new CGI::apacheSSI object. The following are valid (optional) arguments:

 DOCUMENT_URI    => $doc_uri,
 DOCUMENT_NAME   => $doc_name,
 DOCUMENT_ROOT   => $doc_root,
 errmsg          => $oops,
 sizefmt         => ('bytes' || 'abbrev'),
 timefmt         => $time_fmt,
 MAX_RECURSIONS  => $default_100, # when to stop infinite loops w/ error msg
 COOKIE_JAR      => HTTP::Cookies->new,
 _verbose_errors  => 0 || 1,
_verbose_errors

The _verbose_errors option was introduced to enable the output of more verbose errors directly to the browser (instead of the standard [an error occurred while processing this directive] message), which can be quite useful when debugging. This can be changed during script execution via $ssi->config('_verbose_errors', 1) to enable or $ssi->config('_verbose_errors', 0) to disable. Default is 0.

$ssi->config($type, $arg)

$type is either 'sizefmt', 'timefmt', 'errmsg', or '_verbose_errors'. $arg is similar to those of the SSI spec, referenced below.

$ssi->set($varname => $value)

Sets variables internal to the CGI::apacheSSI object. (Not to be confused with the normal variables your script uses!) These variables may be used in test expressions, and retreived using $ssi->echo($varname). These variables also will not be available in external, included resources.

$ssi->echo($varname)

Returns the value of the variable named $varname. Such variables may be set manually using the set() method. There are also several built-in variables:

 DOCUMENT_URI  - the URI of this document
 DOCUMENT_NAME - the name of the current document
 DATE_GMT      - the same as 'gmtime'
 DATE_LOCAL    - the same as 'localtime'
 LAST_MODIFIED - the last time this script was modified
$ssi->exec($type, $arg)

$type is either 'cmd' or 'cgi'. $arg is similar to the SSI spec (see below).

$ssi->include($type, $arg)

Similar to exec, but virtual and file are the two valid types. SSI variables will not be available outside of your CGI::apacheSSI object, regardless of whether the virtual resource is on the local system or a remote system.

$ssi->flastmod($type, $filename)

Similar to include.

$ssi->fsize($type, $filename)

Same as flastmod.

$ssi->printenv

Returns the environment similar to Apache's mod_include.

$ssi->cookie_jar([$jar])

Returns the currently-used HTTP::Cookies object. You may optionally pass in a new HTTP::Cookies object. The jar is used for web requests in exec cgi and include virtual directives.

FLOW-CONTROL METHODS

The following methods may be used to test expressions. During a block where the test $expr is false, nothing will be returned (or printed, if tied).

$ssi->if($expr)

The expr can be any Apache mod_include expression as you would use in:

 <!--#if expr="'\$varname' =~ /^foo$/" -->ok<!--#endif -->

The $varname is expanded as you would expect. (We escape it so as to use the $varname within the CGI::apacheSSI object, instead of that within our progam.) But the $/ inside the regex is also expanded. This is fixed by escaping the $:

 <!--#if expr="'\$varname' =~ /^value\$/" -->ok<!--#endif -->

NOTE: Although "if" allows multiple expr's:

 <!--#if  expr="$myexpr1" expr="$myexpr2" -->ok<!--#endif -->

only the last expression ($myexpr2) is what is used for evaluation.

$ssi->elif($expr)
$ssi->else
$ssi->endif

SEE ALSO

CGI::SSI, Apache::SSI and the SSI spec at http://www.apache.org/docs/mod/mod_include.html

AUTHOR

(c) 2000-2005 James Tolley <james@bitperfect.com>, et al., All Rights Reserved.

(c) 2013-2014 insaner <apacheSSI-PLEASE-NOSPAM@insaner.com>, (rewrite of eval engine and original fork), All Rights Reserved.

This is free software. You may copy and/or modify it under the terms of the GPL. USE AT YOUR OWN RISK. If your server explodes and invests all your money on penny stocks, don't blame me. But if this module was of any use to you and you would like to show your gratitude with a financial contribution, that would be most graciously received.

CREDITS

Many Thanks to all contributors to CGI::SSI, Apache::SSI and HTML::SimpleParse.

And now that you have read all the documentation, go out there and find (and fix) all those bugs!