v3.23 release

vim: reset style at plp block start

PLPperlblock should not be made 'transparent', because this incorrectly
preserves the current HTML highlight for default Perl code.  Mixing Perl and
HTML styling can lead to very strange and unwanted effects, like partially
marking the following code as a comment:

<!-- <: print not_a_comment(); :> -->

capture actual test warnings

Compare expected `use warnings` output to warnings produced by similar code
instead of hardcoding text.  It doesn't really matter what is said, as long
it's the same using plp.

Fixes (so far and afaik) a slight change introduced by Perl v5.11.0 in
"Useless use of a constant in void context" (adding details about which
constant).

fix tiny typo in PLP::HowTo title

EscapeHTML function

Another function to encode html/xml, this time (imho) the "right" way by
only quoting reserved characters.  The provided Entity() function would
often be unusable because of its overcomplete whitespace formatting.
This is a feature which I (have to) set up manually in many cases, which
seems very unfriendly for a module optimised for outputting HTML.

According to personal preferences, it only substitutes a minimal set of
entities:
- &amp; and &lt; (both required to prevent html interpretation)
- &gt; (for xml or otherwise to ease document parsing)
- &quot; (to make it usable in attribute values).

Single quotes (&#39; or &apos;) are left unquoted, assuming attributes are
always in double quotes (no reason to do otherwise).
Unlike Entity, it only handles a single argument, to allow for possible
options in the future (hopefully supporting a custom range of unsafe chars).
It also dies on failure (like trying to change read-only input), because
that is a user mistake which should not go unnoticed.

The name was devised to be more consistent with other environments (also
anticipating new URI encoding and decoding):

* php                   htmlspecialchars  html_entity_decode urlrawencode       urldecode
* javascript                                                 encodeURIComponent decodeURIComponent
* ruby CGI              escapeHTML        unescapeHTML       escape             unescape
- CGI::Simple::Util     escapeHTML        unescapeHTML       escape             unescape
- CGI::Util             (simple_escape)                      escape             unescape
- HTML::Mason::Escapes  basic_html_escape                    url_escape
- HTML::Tiny            entity_encode                        url_encode         url_decode
* URI::Escape                                                uri_escape_utf8    uri_unescape
* XML::Quote            xml_quote         xml_dequote
- PLP (legacy)          Entity                               EncodeURI          DecodeURI
- PLP (redesign)        EscapeHTML        UnescapeHTML       EscapeURI          UnescapeURI

HTML:
- Escape etc used nearly everywhere (so the obvious choice).
- Decode is only used by php, but uglily and inconsistently.
- Quote seems most appropriate linguistically, but only used in one minority
  module.

URIs:
- Encode etc common in php and javascript.
- Escape etc used by ruby and several perl modules (including URI::Escape),
  and is still familiar to javascript users
- URI used in all significant environemnts; URL only in minor modules.

fix header output triggered by say() in perl 5.10.1+

Since the latest Perl release, calling sendheaders() from within a say()
would (correctly) retain a custom output seperator, resulting in http
headers being sent incorrectly.

Easily fixed by resetting normal printing behaviour.

resolve test directory

File::Spec->tmpdir may return a symlink as well, so
c41c902ca6fd9f8e352267be64d (test in directories provided by Test::Spec)
still didn't fix darwin (in all cases).

The darwin I tested on gave a tmpdir like:
/var/folders/OJ/OJjGh2I+HBOinZB8Re8QVU+++TI/-Tmp-
but cpantesters machines are still using a symlinked /tmp.

Use Cwd to find the real path name, hopefully fixing all remaining cases.

exclude PLP::Script from META.yml provides

Saying we've got PLP::Script might have been useful to users looking
for it, but it seems to provide more disadvantages, confusing at least
search.cpan.org (thinks PLP is pod now).

compact output in warnings test

warn pre-start() errors

Early warnings (cgi 403/404) should warn instead of print to STDERR.
This allows them to be handled by $SIG{__WARN__} (usually not set, but
used in tests).

test in directories provided by Test::Spec

On darwin machines /tmp seems to be symlinked to /private/tmp, resulting
in different file names reported by <()> (uses rel2abs with dirname of
parent file) and Include() (uses rel2abs in cwd, so symlinks are
resolved).  Similarly, on windows the latter adds a drive name (C:\tmp).

F::S->tmpdir should provide a preresolved directory, so results are the
same.

fix perl 5.6 syntax error in t/50-cgi.t

> Bareword "STDOUT" not allowed while "strict subs" in use.

test 403 and 404 responses

do not require server signature on page error

In rare cases, SERVER_SIGNATURE may not be set.  This isn't a problem,
but we need to check for definedness to prevent warnings.

fix missinginclude tests

Try to open the missing file in the same way PLP::source() will,
to obtain the same warning message.

For example MSWin32-x86-multi-thread said:
Can't open "C:\Perl\cpan\build\PLP-3.22-ZfVju5\missinginclude" (No such file or directory)
while several CPANTS linuxes were localized:
Can't open "/tmp/missinginclude" (Datei oder Verzeichnis nicht gefunden)

v3.22 release

declare provides in META.yml

List provided modules (recommended by Kwalitee metayml_has_provides).
Module::Build would find the same data, but telling it to leave other
fields alone currently takes more effort than simply updating it
manually.  Maybe later.

require Test::YAML::Meta 0.10 for correct testing

Versions upto the current 0.09 do not parse repository resource url
correctly (Unknown protocol used in URL (git://)).  This will most
likely be fixed in the next version.

Addendum: confirmed by BARBIE 2008-06-02 10:34:18 GMT:
> Added 'git' as a valid url protocol in:
> Test-YAML-Meta-0.10

rewrite documentation of mod_perl as the only persistent backend

Update docs to reflect the multiple persistent backends (mod_perl was
mentioned specifically where FastCGI now qualifies as well).

expect unordered headers in tests

Headers are stored as hash, which will be printed in semi-random order.
Sort all lines in output upto the first empty line, in order to compare
reliably.

fix delete %header

Header value wasn't deleted case-insensitively.  Because the alias was
still removed correctly, it usually worked, but as of recently producing
warnings in sendheaders().

Also, delete returned the original key (not documented anywhere).
Change this to always return the deleted value, matching the behaviour
of normal hashes and user expectation.

50-cgi.t: test PLP::Backend::CGI parse output of most plp features

fix Exporter inclusion

Revert recent change of including only import() from Exporter instead of
basing on it, as the latter fails on older Perls (smoke on versions
5.8.2 and below).  Broke PLP::Functions in these versions at
d9f3acb221a71e094318c7b5d3809aa81dbb5bb3 (use warnings in all modules).

v3.21 release

treat custom exit() as private for now

Do not require documentation coverage of PLP::Functions::exit,
it's supposed to be a transparant replacement of CORE::exit.

I'll probably move it outside of this module later (no side-effects
to make it usable without PLP), but that's a seperate fix.

order v3.21 Changes by significance

disable warnings within PLP::Script

d9f3acb221a71e094318c7b5d3809aa81dbb5bb3 (use warnings in all modules)
would not only enable warnings in plp modules, but also users' code
evalled within.  Obviously not a nice thing to do.

retain undef in encoding functions

Entity(), DecodeURI(), and EncodeURI() should return undef for any
undefined input.  Only string behaviour was specified, so users relying
on this did so at their own risk (and they can always disable warnings
like the careless bitches they are :P).

Not too coincidently also silences warnings in PLP::Functions itself.

undefined warnings while reading unknown headers

Return undef for unaliased headers right away, instead of trying to find
$header{+undef}.  Result is the same (the '' header never exists at this
point), but without the warning.

fix undefined warning in apache cgi path

PATH_INFO was intentionally declared undef in PLP::Backend::CGI, but
would be concatenated later (in Apache mode at least), giving warnings
since d9f3acb221a71e094318c7b5d3809aa81db (use warnings in all modules).

only test PLP::Functions in t/10-functions.t

Functions could be used seperately from the rest of PLP, so do not
require everything.  This test is covered by t/50-cgi.t now.

fix PLP::everything() wrapper

CGI initiator everything() was moved in 96959bff080392067524996e6edbf954
(move backend interface modules into PLP::Backend:: namespace)
and made a method, but backwards compatibility wrapper doesn't call it
as such.  This breaks old plp.cgi scripts, completely negating the
purpose of this feature.

order tests

Prefix filenames so they sort in order of significance.

add charset to default content-type header if STDOUT is in UTF-8

If output has utf8 layer enabled, it makes only sense to mark it as such
to clients.  Only available with PerlIO (as of Perl 5.8 afaict), but not
fatal (assume non-utf8) if it doesn't work.

Charset is only added at first read or change of the content-type value,
so it's not hardcoded to site defaults.  Requires an extra object
variable unfortunately, but the only way to make it useful (no page
runtime accomodation wouldn't give much advantage).

undefined warnings during Fields parsing

Accessing undefined values pollutes error logs since
d9f3acb221a71e094318c7b5d3809aa81dbb5bb3 (use warnings in all modules).

test pod coverage as far as applicable

output multiline %headers as multiple headers of the same name

Allowing repeated HTTP headers (RFC2616 §4.2) even though this didn't
add much value afterall (one may also use commas).  It does prevent
(accidentally) malformed header values though, as most servers don't
seem to handle continuation lines.

add version numbers to versionless modules

use warnings in all modules

improve plpinfo page

Fix version display in Perl >= 5.10: $^V no longer consists out of
single characters for each level.  Use the recommended practise of
formatting with sprintf (see perlvar) which seems to work in at least
5.6.1 (ie good enough).

Add 'Perl API' version analogous to 'PHP API' in phpinfo().
Some fallbacks if variables are empty or undefined.

fix META.yml syntax

Bah, used lists where simple maps were expected (though this syntax is
used with optional_features and another project of mine, so slightly
excusable except for missing tests).

Also, Test::YAML::Meta wants keys of optional_features to conform to
/^[a-z_-]+$/.  This isn't mentioned anywhere in the specifications, but
a passing test is more useful than a minor stylistic detail.

Finally, while 'repository' apparantly still isn't an official resources
key, it _is_ mentioned as such (lowercased) in the specs.  In fact
everyone seems to use it like that, so I guess being technically
incorrect will be supported better.

add a few todo entries

v3.20 release

improve lighttpd configuration samples

Use the merge (+=) syntax so the user doesn't have to integrate any
existing options, and can simply add the snippet as is (even as a
seperate include, especially easy in a Debian setup).

Extend backend configuration examples with options for a directory index
of index.plp, and (static) source rejection.

keep SCRIPT_* environment variables in CGI

These are now identical to their PLP_* counterparts, and should be used
instead for familiarity (why rename for no apparant reason; SCRIPT_* now
contain their expected values so no reason to suggest otherwise).
Apache already has both.

license file from COPYING renamed LICENSE

While COPYING seems to be most frequently used overall, LICENSE is used
more in perl modules and recommended by Kwalitee guidelines.  Fine with
me either way, so use the name that breaks the least.

do not import parent module in PLP::Backend::FastCGI

FastCGI initialized normal CGI as well, providing unneeded CGI support.
Apparantly it's not in the way, but wrong nonetheless (and quite
confusing to be able to use the fastcgi module with cgi).

suppress warning in PLP::Backend::CGI

Add parentheses to my $scalar argument to read() to verify it's really
only a single variable.  Works the same, but fixes a warning if run -w.

restructure file locations

Use root directories lib/ (pm and pod) and bin/ (executable scripts).
This is the common layout of modern modules, and in fact ever more
expected (by Module::Build for example).

custom META.yml

Automatically generated module information cannot ascertain certain
information, so I'd rather provide all YAML myself.

Compared to ExtUtils::MakeMaker 6.42 output, this adds resources,
recommends, and optional_features.

seperate/rewritten README file

Plain text README should be a minimal introductionary basics: intro
(first paragraph of pod description), installation, help, copyright.
Leave the pod (and only that) to be the full manual.  All users should
be able to run perldoc, without being held off by some wannabe text
conversion.

set $PLP::interface to executing backend

Useful to know how we're running, as code may want to target specific
backends.  Currently undocumented so that behaviour can be changed
easily if need be.

change to MIT license

Add a proper license instead of the just saying 'public domain'
(arguably unfulfilling, see http://www.linuxjournal.com/article/6225).
The MIT or X11 license is similar in intent to the perceived PD,
and should provide all if not more rights to users.
It's essentially the same as the 2-clause BSD and ISC licenses.

With consent of the original copyright holder Juerd Waalboer:
> BTW, mocht je een echte licentie willen gebruiken, dan stel ik MIT
> voor als je je daar zelf in kunt vinden

test for pod correctness

If Test::Pod is present, check the pod of files in our manifest.

expand backend documentation

Add descriptions for PLP::Backend::FastCGI and ::Apache explaining
their configuration and advantages, and recommend/reorder backends
accordingly.

Document a major bug in mod_perl2, and discourage its use for now.
Not investigated, but easily reproducable with:

<:
use Cwd qw(cwd);
say cwd, '<br>';
sleep 10;  # now request a plp from a different directory
say cwd, '<br>';

handle fastcgi signals

http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S7
> A Web server can request that a FastCGI application exit by sending it
> SIGTERM. If the application ignores SIGTERM the Web server can resort
> to SIGKILL.

So stop accepting new requests after receiving a TERM signal.  Allow the
current page to finish, we should assume it won't be long (long-running
scripts usually require customized destructors anyway, so don't account
for those).  This is quite important to prevent interrupted output.

According to http://www.fastcgi.com/docs/faq.html#Signals Apache
mod_fastcgi will send a SIGUSR1 in addition to the TERM.  Seems safe to
ignore these.

If a client aborts a connection, we'll get a SIGPIPE.  Because the page
may still have crucial actions to perform, we should ignore and finish
the code.  Pages can easily handle PIPEs themselves if wanted.

The LastCall method is used, even though FCGI 0.67 warns:
> Note that this method is still experimental and everything about it,
> including its name, is subject to change.

As it's stable since september 2001, I guess it'll be fine for now.

fix default text for pod links to other modules

Do not provide an explicit link presentation for stand-alone module
references (no context, so let the renderer do what it thinks best).
In a running text we want the opposite though: make sure modules names
aren't 'linkified' when they shouldn't (e.g. "use the XML::Quote
manpage" when we mean just the module).

short TODO with planned features

Note some of the things planned for near-future releases.

move backend interface modules into PLP::Backend:: namespace

Keep our namespace a bit organized.

fix exit constants usage in apache2

Apache2::Const requires HTTP_* constants to be compiled before they can be
accessed. This caused at least a warning message at the end of each page,
usually:

Use of inherited AUTOLOAD for non-method Apache2::Const::OK() is deprecated

update plp.cgi

Update plp.cgi intro comments to reflect new interfaces status.
To make it more usable out of the box, executable flag is set (so it can be
run directly) and uses interpreter from environment (/usr/bin/env should be
supported better than /usr/bin/perl).

move detailed setup documentation to interface modules

Only keep basic instructions for Lighttpd+mod_fastcgi and
Apache+mod_perl in PLP's main synopsis. Other configurations is given in
the pods of interface modules. These are linked at PLP#DESCRIPTION,
which now also contains an overview of supported servers.

Mod_perl configuration variables have also been moved into PLP::Apache.
In all, makes the main documentation much cleaner (uncluttered with
interface-specific details).

add license to Makefile definitions

As recommended by Kwalitee indicator metayml_has_license.
Currently we specify public domain even though it's not listed in
Module::Build::Api and arguably not a valid license at all. Maybe change
our license later, or classify as 'unrestricted'.

git exclude of compile-time files

Ignore everything generated by/for make.

handle request automatically on PLP::CGI import

As it's not used for much else, PLP::CGI can simply start running on
import. So like PLP::FastCGI, the executable only needs to C<use PLP::CGI>
(and C<require> for advanced usage).

No backwards compatibility issues, as the last release didn't have this
modularized (PLP wrapper works the same as before).

fix setting PLPcache from apache configuration

Apache has been split from PLP package, so need to specify variable
explicitly.

make mod_perl request object a global in PLP::Apache only

No reason to always create $PLP::r, as it's only used with Apache.

eg/plpinfo.plp demo/status page

Demo page reporting about the current status of Perl and PLP. Useful as
test page (see if correct versions are loaded as they should, and what
variables are set), or at least as a somewhat larger example of a plp
page.

Modelled closely after PHP's phpinfo() output (even color scheme is the
same, albeit html is much cleaner) to keep it as familiar as possible to
php switcheroos.

FastCGI interface (PLP::CGI extension using FCGI)

Do not exit from PLP::CGI, allowing it to be used consecutively.

Coincidentally, PLP::FastCGI does just that: extending the PLP::CGI
interface to handle FCGI requests. Its import() runs a PLP dispatcher,
so a FastCGI executable (example plp.fcgi is provided) only has to
C<use PLP::FastCGI>. If a server supports run arguments, a wrapper
script isn't even needed this way: just do /usr/bin/perl -MPLP::FastCGI.

PATH_TRANSLATED is explicitly removed from environment so file names are
gotten from SCRIPT_*, which mostly already point to the requested script
(at least much more correctly than can be determined from PATH_*).

This seems to work correctly on at least:
- Apache 1.3.34, 2.2.4, 2.2.8 with mod_fastcgi and mod_fcgid
- Lighttpd 1.4.7 and 1.4.18 with mod_fastcgi

Caching can be controlled by setting an environment variable PLP_CACHE
(unlike with mod_perl, no other means of configuration are provided).
If not specified, PLPcache will be turned on.

fcgi script

generalize reading post input

Input retrieval differs per server interface, so set $PLP::read to a
function providing a read of specified number of bytes. This differs
from $PLP::print as it's not just a name, because it won't be evalled
but called directly.

404 handling for pre-parsed CGI handling

When using SCRIPT_FILENAME provided by server, still make sure the file
exists. Lighttpd can provide non-existant files when setting check-local
is turned off.

PATH_TRANSLATED handling (i.e. Apache) is unaffected: always does 404
checking when walking the path.

clean up CGI environment parsing

When parsing PATH_TRANSLATED, put results in SCRIPT_* variables. Create
additional PLP_* vars only later. This makes both cases result in the
same intermediate state, and therefor easier to follow.

Lighttpd CGI support

In case no PATH_TRANSLATED environment var is present, assume request is
already parsed and SCRIPT_* pointing to target script (not plp handler).
This supports at least Lighttpd CGI requests.  Functionality unchanged
for Apache1/2 CGI.

use recommended apache2 constants

According to mod_perl documentation (porting/compat):

REDIRECT and similar constants have been deprecated in Apache for
years, in favor of the HTTP_* names (they no longer exist Apache
2.0). mod_perl 2.0 API performs the following aliasing behind the
scenes

make PLP::Apache mod_perl 2.0 compatible

move plp server handlers to respective modules

Keep compatibility wrappers for handler() and everything().

test-suite directory

Anticipating more tests.

Also clarifies (limited) testing scope by filename.

seperate modules for backend-specific code

Split out initialization and other specifics for CGI and mod_perl (Apache).

remove disabled Cwd include

documentation fixes

Typo, small mistake in example, unmarked code.

fix html of default error message

Remove unclosed and useless tag; consistent tag capitalization.

reindent remaining 4-space+tab@8 code

Use only tabs for indenting, spaces for alignment.

tiny speedup decoding + in DecodeURI()

v3.19 release

minor code cleanups and clarifications

common argument handling in functions

Slightly cleaner and faster, and accepts read-only values in all functions.

change code indenting to tabs

remove undocumented function HiddenFields()

add tests for all quoting functions

update text dump of documentation

README regenerated from PLP.pm pod.

makefile cleanup

Also drops perl <5.5 support, since PLP requires 5.6 anyway.

module Cwd not used in PLP; don't use

document caveats for quoting functions; fix documentation indenting/wrapping.

fix header sending for tied printing

Headers were not sent on initial printf or print with empty first argument.

plp.tieprint.patch by Shiar 2002-08-21 18:54:45

new maintainer: shiar

v3.18 release

extend howto

Explain basic http authentication. Mention SQLite.

cleanup (minor things like punctuation, use spaces for docu indenting)

optional end tag for plp code

fix header key conversion to match documentation

Really convert Content_Type to content-type.