Apache-ASP
view release on metacpan or search on metacpan
$rv;
}
*Config = *config;
sub config {
my($self, $key, $value, $default) = @_;
my $dir_config = $self->{dir_config};
if(defined $value) {
$dir_config->set($key, $value);
} elsif(defined $key) {
my $rv = $dir_config->get($key);
if(defined($rv)) {
if(lc($rv) eq 'off') {
$rv = 0; # Off always becomes 0
}
} else {
# use default value if none is returned
if(defined($default)) {
$rv = $default;
}
}
$rv;
} else {
$dir_config;
}
}
1;
__END__
=pod
=encoding ISO8859-1
=head1 NAME
Apache::ASP - Active Server Pages for Apache with mod_perl
=head1 SYNOPSIS
SetHandler perl-script
PerlModule Apache::ASP
PerlHandler Apache::ASP
PerlSetVar Global /tmp/asp
=head1 DESCRIPTION
Apache::ASP provides an Active Server Pages port to the
Apache Web Server with Perl scripting only, and enables developing
of dynamic web applications
with session management and embedded Perl code. There are also
many powerful extensions, including XML taglibs, XSLT rendering,
and new events not originally part of the ASP API!
=begin html
<table class="noescape" border="0"><tr><td>
<b>Apache::ASP's features include:</b>
<font face=verdana,helvetica,arial size=-1>
<ul>
<li> Scripting SYNTAX is Natural and Powerful
<li> Rich OBJECTS Developer API
<li> Web Application EVENTS Model
<li> Modular SSI Decomposition, Code Sharing
<li> User SESSIONS, CIFS & NFS Cluster Ready
<li> XML/XSLT Rendering & Custom Tag Technology
<li> CGI Compatibility
<li> PERLSCRIPT Compatibility
<li> Great Open Source SUPPORT
</ul>
</font>
</table>
=end html
This module works under the Apache Web Server
with the mod_perl module enabled. See http://www.apache.org and
http://perl.apache.org for further information.
This is a portable solution, similar to ActiveState's PerlScript
for NT/IIS ASP. Work has been done and will continue to make ports
to and from this implementation as smooth as possible.
For Apache::ASP downloading and installation, please read
the INSTALL section. For installation troubleshooting
check the FAQ and the SUPPORT sections.
For database access, ActiveX, scripting languages, and other
miscellaneous issues please read the FAQ section.
=head1 WEBSITE
The Apache::ASP web site is at http://www.apache-asp.org/
which you can also find in the ./site directory of
the source distribution.
=head1 INSTALL
The installation process for Apache::ASP is geared towards those
with experience with Perl, Apache, and unix systems. For those
without this experience, please understand that the learning curve
can be significant. But what you have at the end will be a web site
running on superior open source software.
If installing onto a Windows operating system, please see the section
titled Win32 Install.
=head2 Need Help
Often, installing the mod_perl part of the Apache server
can be the hardest part. If this is the case for you,
check out the FAQ and SUPPORT sections for further help,
as well as the "Modern Linux Distributions" notes in this section.
Please also see the mod_perl site at http://perl.apache.org/
which one ought to give a good read before undertaking
a mod_perl project.
=head2 Download and CPAN Install
You may download the latest Apache::ASP from your nearest CPAN,
and also:
http://search.cpan.org/dist/Apache-ASP/
http://cpan.org/modules/by-module/Apache/
As a Perl developer, you should make yourself familiar with
the CPAN.pm module, and how it may be used to install
Apache::ASP, and other related modules. The easiest way
to install Apache::ASP for the first time from Perl is to
fire up the CPAN shell like:
This config does not work when Debug 2 is set, as it is a setting for
use in production only, where Debug 2 is for development use.
PerlSetVar MailAlertTo youremail@yourdomain.com
=item MailAlertPeriod
Default 20 minutes, this config specifies the time in minutes over
which there may be only one alert email generated by MailAlertTo.
The purpose of MailAlertTo is to give the admin a heads up that there
is an error at the www server. MailErrorsTo is for to aid in speedy
debugging of the incident.
PerlSetVar MailAlertPeriod 20
=head2 File Uploads
=item FileUploadMax
default 0, if set will limit file uploads to this
size in bytes. This is currently implemented by
setting $CGI::POST_MAX before handling the file
upload. Prior to this, a developer would have to
hardcode a value for $CGI::POST_MAX to get this
to work.
PerlSetVar 100000
=item FileUploadTemp
default 0, if set will leave a temp file on disk during the request,
which may be helpful for processing by other programs, but is also
a security risk in that other users on the operating system could
potentially read this file while the script is running.
The path to the temp file will be available at
$Request->{FileUpload}{$form_field}{TempFile}.
The regular use of file uploads remains the same
with the <$filehandle> to the upload at
$Request->{Form}{$form_field}. Please see the CGI section
for more information on file uploads, and the $Request
section in OBJECTS.
PerlSetVar FileUploadTemp 0
=head1 SYNTAX
=head2 General
ASP embedding syntax allows one to embed code in html in 2 simple ways.
The first is the <% xxx %> tag in which xxx is any valid perl code.
The second is <%= xxx %> where xxx is some scalar value that will
be inserted into the html directly. An easy print.
A simple asp page would look like:
<!-- sample here -->
<html>
<body>
For loop incrementing font size: <p>
<% for(1..5) { %>
<!-- iterated html text -->
<font size="<%=$_%>" > Size = <%=$_%> </font> <br>
<% } %>
</body>
</html>
<!-- end sample here -->
Notice that your perl code blocks can span any html. The for loop
above iterates over the html without any special syntax.
=head2 XMLSubs
XMLSubs allows a developer to define custom handlers for
HTML & XML tags, which can extend the natural syntax
of the ASP environment. Configured like:
PerlSetVar XMLSubsMatch site:\w+
A simple tag like:
<site:header title="Page Title" />
can be constructed that could translate into:
sub site::header {
my $args = shift;
print "<html><head><title>$args->{title}</title></head>\n";
print "<body bgcolor=white>\n";
}
Better yet, one can use this functionality to trap
and post process embedded HTML & XML like:
<site:page title="Page Title">
... some HTML here ...
</site:page>
and then:
sub site::page {
my($args, $html) = @_;
&site::header($args);
$main::Response->Write($html);
$main::Response->Write("</body></html>");
}
Though this could be used to fully render XML
documents, it was not built for this purpose, but
to add powerful tag extensions to HTML development
environments. For full XML rendering, you ought
to try an XSLT approach, also supported by Apache::ASP.
=head2 Editors
As Apache::ASP supports a mixing of perl and HTML,
any editor which supports development of one or the
other would work well. The following editors are
known to work well for developing Apache::ASP web sites:
* Emacs, in perl or HTML modes. For a mmm-mode config
that mixes HTML & perl modes in a single buffer, check
out the editors/mmm-asp-perl.el file in distribution.
mod_perl "Eagle" Book
http://www.modperl.com
mod_perl Developer's Cookbook
http://www.modperlcookbook.org
Programming the Perl DBI
http://www.oreilly.com/catalog/perldbi/
=head2 Reference Cards
Apache & mod_perl Reference Cards
http://www.refcards.com/
=head2 Web Sites
mod_perl Apache web module
http://perl.apache.org
mod_perl 1.x Guide
http://perl.apache.org/guide/
Perl Programming Language
http://www.perl.com
Apache Web Server
http://www.apache.org
=head1 TODO
There is no specific time frame in which these things will be
implemented. Please let me know if any of these is of particular
interest to you, and I will give it higher priority.
=head2 WILL BE DONE
+ Database storage of $Session & $Application, so web clusters
may scale better than the current NFS/CIFS StateDir implementation
allows, maybe via Apache::Session.
=head1 CHANGES
Apache::ASP has been in development since 1998, and
was production ready since its .02 release. Releases
are always used in a production setting before being
made publically available.
In July 2000, the version numbers of releases went
from .19 to 1.9 which is more relevant to software development
outside the perl community. Where a .10 perl module usually
means first production ready release, this would be the
equivalent of a 1.0 release for other kinds of software.
+ = improvement - = bug fix (d) = documentations
=item $VERSION = 2.63; $DATE="03/14/2018"
+ Added section ``raw'' to MailErrors.inc to debug POSTs without
form fields
- MailErrorsHTML now uses monospaced fonts for errors. Easier on
the eyes and more informative
=item $VERSION = 2.62; $DATE="08/16/2011"
- Fixed 'application/x-www-form-urlencoded' for AJAX POSTs post
Firefox 3.x
+ First sourceforge.net hosted version
+ Incremented version number to actually match SVN branch tag
=item $VERSION = 2.61; $DATE="05/24/2008"
- updated for more recent mod_perl 2 environment to trigger correct loading of modules
+ loads modules in a backwards compatible way for older versions of mod_perl 1.99_07 to 1.99_09
+ license changes from GPL to Perl Artistic License
=item $VERSION = 2.59; $DATE="05/23/2005"
+ added "use bytes" to Response object to calculate Content-Length
correctly for UTF8 data, which should require therefore at least
perl version 5.6 installed
+ updated to work with latest mod_perl 2.0 module naming convention,
thanks to Randy Kobes for patch
+ examples now exclude usage of Apache::Filter & Apache::SSI under mod_perl 2.0
=item $VERSION = 2.57; $DATE="01/29/2004"
- $Server->Transfer will update $0 correctly
- return 0 for mod_perl handler to work with latest mod_perl 2 release
when we were returning 200 ( HTTP_OK ) before
- fixed bug in $Server->URL when called like $Server->URL($url)
without parameters. Its not clear which perl versions this bug
affected.
=item $VERSION = 2.55; $DATE="08/09/2003"
- Bug fixes for running on standalone CGI mode on Win32 submitted
by Francesco Pasqualini
+ Added Apache::ASP::Request::BINMODE for binmode() being
called on STDIN after STDIN is tied to $Request object
+ New RequestBinaryRead configuration created, may be turned off
to prevent $Request object from reading POST data
++ mod_perl 2 optmizations, there was a large code impact on this,
as much code was restructured to reduce the differences between
mod_perl 1 and mod_perl 2, most importantly, Apache::compat is
no longer used
+ preloaded CGI for file uploads in the mod_perl environment
- When XSLT config is set, $Response->Redirect() should work now
scalar ref for arguments of data to parse for greater
integration ability with other applications.
+PodComments optimization, small speed increase at
compilation time.
+String optimization on internal rendering that avoids
unnecessary copying of static html, by using refs. Should
make a small difference on sites with large amounts of
static html.
+CompressGzip setting which, when Compress::Zlib is installed,
will compress text/html automatically going out to the web
browser if the client supports gzip encoding.
++Script_OnFlush event handler, and auxiliary work optimizing
asp events in general. $Response->{BinaryRef} created which
is a reference to outgoing output, which can be used
to modify the data at runtime before it goes out to the client.
+Some code optimizations that boost speed from 22 to 24
hits per second when using Sessions without $Application,
on a simple hello world benchmark on a WinNT PII300.
++Better SessionManagement, more aware of server farms that
don't have reliable NFS locking. The key here is to have only
one process on one server in charge of session garbage collection
at any one time, and try to create this situation with a snazzy
CleanupMaster routine. This is done by having a process register
itself in the internal database with a server key created at
apache start time. If this key gets stale, another process can
become the master, and this period will not exceed the period
SessionTimeout / StateManager.
** Work on session manager sponsored by LRN, http://www.lrn.com. **
** This work was used to deploy a server farm in production with **
** NFS mounted StateDir. Thanks to Craig Samuel for his belief in **
** open source. :) **
Future work for server farm capabilities might include breaking
up the internal database into one of 256 internal databases
hashed by the first 2 chars of the session id. Also on the plate
is Apache::Session like abilities with locking and/or data storage
occuring in a SQL database. The first dbs to be done will include
MySQL & Oracle.
+Better session security which will create a new session id for an
incoming session id that does not match one already seen. This will
help for those with Search engines that have bookmarked
pages with the session ids in the query strings. This breaks away
from standard ASP session id implementation which will automatically
use the session id presented by the browser, now a new session id will
be returned if the presented one is invalid or expired.
-$Application->GetSession will only return a session if
one already existed. It would create one before by default.
+Script_OnFlush global.asa event handler, and $Response->{BinaryRef}
member which is a scalar reference to the content about to be flushed.
See ./site/eg/global.asa for example usage, used in this case to
insert font tags on the fly into the output.
+Highlighting and linking of line error when Debug is set to 2 or -2.
--removed fork() call from flock() backup routine? How did
that get in there? Oh right, testing on Win32. :(
Very painful lesson this one, sorry to whom it may concern.
+$Application->SessionCount support turned off by default
must enable with SessionCount config option. This feature
puts an unnecessary load on busy sites, so not default
behavior now.
++XMLSubsMatch setting that allows the developer to
create custom tags XML style that execute perl subroutines.
See ./site/eg/xml_subs.asp
+MailFrom config option that defaults the From: field for
mails sent via the Mail* configs and $Server->Mail()
+$Server->Mail(\%mail, %smtp_args) API extension
+MailErrorsTo & MailAlertTo now can take comma
separated email addresses for multiple recipients.
-tracking of subroutines defined in scripts and includes so
StatINC won't undefine them when reloading the GlobalPackage,
and so an warning will be logged when another script redefines
the same subroutine name, which has been the bane of at least
a few developers.
-Loader() will now recompile dynamic includes that
have changed, even if main including script has not.
This is useful if you are using Loader() in a
PerlRestartHandler, for reloading scripts when
gracefully restarting apache.
-Apache::ASP used to always set the status to 200 by
default explicitly with $r->status(). This would be
a problem if a script was being used to as a 404
ErrorDocument, because it would always return a 200 error
code, which is just wrong. $Response->{Status} is now
undefined by default and will only be used if set by
the developer.
Note that by default a script will still return a 200 status,
but $Response->{Status} may be used to override this behavior.
+$Server->Config($setting) API extension that allows developer
to access config settings like Global, StateDir, etc., and is a
wrapper around Apache->dir_config($setting)
+Loader() will log the number of scripts
recompiled and the number of scripts checked, instead
of just the number of scripts recompiled, which is
misleading as it reports 0 for child httpds after
a parent fork that used Loader() upon startup.
-Apache::ASP->Loader() would have a bad error if it didn't load
any scripts when given a directory, prints "loaded 0 scripts" now
documentation, and added error_document.htm example.
=OrderCollections setting was added, but then REMOVED
because it was not going to be used. It bound
$Request->* collections/hashes to Tie::IxHash, so that data
in those collections would be read in the order the
browser sent it, when eaching through or with keys.
-global.asa will be reloaded when changed. This broke
when I optimized the modification times with (stat($file))[9]
rather than "use File::stat; stat($file)->mtime"
-Make Apache::ASP->Loader() PerlRestartHandler safe,
had some unstrict code that was doing the wrong thing.
-IncludesDir config now works with DynamicIncludes.
+DebugBufferLength feature added, giving control to
how much buffered output gets shown when debugging errors.
++Tuning of $Response->Write(), which processes all
static html internally, to be almost 50% faster for
its typical use, when BufferingOn is enabled, and
CgiHeaders are disabled, both being defaults.
This can show significant speed improvements for tight
loops that render ASP output.
+Auto linking of ./site/eg/ text to example scripts
at web site.
+$Application->GetSession($session_id) API extension, useful
for managing active user sessions when storing session ids
in $Application. Documented.
-disable use of flock() on Win95/98 where it is unimplemented
-@array context of $Request->Form('name') returns
undef when value for 'name' is undefined. Put extra
logic in there to make sure this happens.
=item $VERSION = 0.16; $DATE="09/22/99";
-$Response->{Buffer} and PerlSetVar BufferingOn
configs now work when set to 0, to unbuffer output,
and send it out to the web client as the script generates it.
Buffering is enabled by default, as it is faster, and
allows a script to error cleanly in the middle of execution.
+more bullet proof loading of Apache::Symbol, changed the
way Apache::ASP loads modules in general. It used to
check for the module to load every time, if it hadn't loaded
successfully before, but now it just tries once per httpd,
so the web server will have to be restarted to see new installed
modules. This is just for modules that Apache::ASP relies on.
Old modules that are changed or updated with an installation
are still reloaded with the StatINC settings if so configured.
+ASP web site wraps <font face="courier new"> around <pre>
tags now to override the other font used for the text
areas. The spacing was all weird in Netscape before
for <pre> sections.
-Fixed Content-Length calculation when using the Clean
option, so that the length is calculated after the HTML
is clean, not before. This would cause a browser to
hang sometimes.
+Added IncludesDir config option that if set will also be
used to check for includes, so that includes may easily be
shared between applications. By default only Global and
the directory the script is in are checked for includes.
Also added IncludesDir as a possible configuration option
for Apache::ASP->Loader()
-Re-enabled the Application_OnStart & OnEnd events, after
breaking them when implementing the AllowApplicationState
config setting.
+Better pre-fork caching ... StatINC & StatINCMatch are now
args for Apache::ASP->Loader(), so StatINC symbols loading
may be done pre-fork and shared between httpds. This lowers
the child httpd init cost of StatINC. Documented.
+Made Apache::ASP Basic Authorization friendly so authentication
can be handled by ASP scripts. If AuthName and AuthType Apache
config directives are set, and a $Response->{Status} is set to
401, a user will be prompted for username/password authentication
and the entered data will show up in ServerVariables as:
$env = $Request->ServerVariables
$env->{REMOTE_USER} = $env->{AUTH_USER} = username
$env->{AUTH_PASSWD} = password
$env->{AUTH_NAME} = your realm
$env->{AUTH_TYPE} = 'Basic'
This is the same place to find auth data as if Apache had some
authentication handler deal with the auth phase separately.
-MailErrorsTo should report the right file now that generates
the error.
=item $VERSION = 0.15; $DATE="08/24/1999";
--State databases like $Session, $Application are
now tied/untied to every lock/unlock triggered by read/write
access. This was necessary for correctness issues, so that
database file handles are flushed appropriately between writes
in a highly concurrent multi-process environment.
This problem raised its ugly head because under high volume,
a DB_File can become corrupt if not flushed correctly.
Unfortunately, there is no way to flush SDBM_Files & DB_Files
consistently other than to tie/untie the databases every access.
DB_File may be used optionally for StateDB, but the default is
to use SDBM_File which is much faster, but limited to 1024 byte
key/value pairs.
For SDBM_Files before, if there were too many concurrent
( run in 0.575 second using v1.01-cache-2.11-cpan-ceb78f64989 )