NAME

PerlHP - Turn Perl into PHP, or was it the other way around?


SYNOPSIS

 #!/usr/bin/perl
 use PerlHP;
 <html><body>
 <%
 print "<h1>HTML output</h1>";
 header("X-Header: Custom headers");
 cookie("name","value",$expires,"/path",".domain.com",$secure);
 $safe_string=escape_html($unsafe_string);
 echo "<h2>PHP-style output</h2>";
 %>
 </body></html>


DESCRIPTION

This modules implements a source filter for embedding Perl code in HTML in the style of PHP. It also turns query arguments and cookies into global variables, and handles headers and cookies.

A PerlHP page starts with a normal Perl hashbang, followed by a use PerlHP; statement.

 #!/usr/bin/perl
 use PerlHP;

On web server which support this, this can be shortened to a single hashbang. This upsets some webservers, though, so it's not encouraged.

 #!/usr/bin/perl -MPerlHP

On older Perl versions that do not support source filters (5.6.*), you can instead use this version, which is not as efficient, but which at least works:

 #!/usr/bin/perl PerlHP.pm

The PerlHP.pm module can be installed in your web server's Perl lib directory, or kept in the same directory as the script. If your Perl installation doesn't contain the current directory in its library path, you can help it find the PerlHP module as follows:

 #!/usr/bin/perl
 use lib '.';
 use PerlHP;

This is followed by HTML markup. Perl code is embedded in a <% %>, <? ?>, <%perl %> or <?perl ?> block. Any functions that outputs text to STDOUT, such as print will insert its output into the HTML code where the block is located.

 <% print "<h1>HTML output</h1>" %>

In addtion, PHP-style short tags are supported. These add an implicit print in front of their contents:

 <%= $variable %>

Query arguments and cookies are made available as global variables. If they are multi-valued, the different values will be separated by null bytes ("\0"). Arrays of the same names as the scalar variables are also created, and contain the individual values of multi-valued arguments. If use strict; is on, first declare these variables with our.

 # Print a single argument given, for instance,
 # as http://.../script.pl?argument=value
 <%
 our $argument;
 print escape_html($argument);
 %>
 
 # Print all the values of a multi-valued argument
 # separated by <br />s.
 # http://.../script.pl?list=1&list=2&list=3
 <%
 our @list;
 foreach (@list) { print escape_html($_)."<br />" }
 %>

The escape_html() function should always be applied to values received from outside the program before printing them, to guard against HTML insertion and cross-site scripting attacks. It is also strongly recommended to use use strict; to guard against potentially dangerous coding errors.


FUNCTIONS

The PerlHP module provides these functions:

cookie( $name [, $value [, $expire [, $path [, $domain [, $secure]]]]] )

Set a HTTP cookie in the browser. $name is the name of the cookie, $value is the value (which, as is not the case with the CGI.pm module, can be a Unicode string), $expire is the time in seconds when the cookie expires (passing time() plus the number of seconds until expiration is what you most likely want to do), $path is the path for which to apply the cookie (defaults to only the directory the script resides in), $domain is the sub-domain the cookie should apply to (you can not specify another domain than the one the script resides on), and $secure is a boolean flag specifiying if the cookie should apply to normal or secure (https://) connections.

Very similar to PHP's setcookie() function.

echo( $string [,$string2,...] )

Alias for print(), for those who want to look more like PHP.

escape_html( $string )

Turns several characters that have special meanings in HTML and elsewhere into HTML entities. This is useful both to properly display strings that may contain special characters, and also to protect your code against HTML insertion and cross-site scripting attacks. As a rule of thumb, this function should be applied to all values that come from outside the script, and are printed anywhere in the HTML page, either as plain text or tag attributes.

The transformations performed are:

However, numeric HTML entities are left untouched by the ampersand conversion.

header( $http_header )

Adds a custom HTTP header to the web server response. The header string should be in the usual HTTP format, and not contain any newlines or preceeding whitespace.

Unlike PHP, you can call header() anywhere in a PerlHP program.

perlhp( $code )

Parses some PerlHP code, and returns the corresponding PerlHP code. Mostly for tricky hacks, and not very useful in normal code.

readfile( $filename )

Reads the contents of the file specified by $filename, and return them as a scalar. Returns nothing on failure. Puts a shared lock on the file while reading. The name is confusingly similar to PHP's readfile() function, which doesn't quite do the same thing!


TROUBLESHOOTING, QUIRKS AND INTERNALS

Perl 5.6.*

Perl 5.6.* does not have Filter::Simple, which PerlHP prefers to use. However, there is an alternate operating mode that works on older Perls, although it is not as efficient. Change the hashbang to:

 #!/usr/bin/perl PerlHP.pm

In previous versions, you could omit the use PerlHP; line, but in the current version this is required even when using this workaround. use PerlHP; marks where the normal Perl code stops and the PerlHP code begins. You must keep the PerlHP.pm file in the same directory as your script for this to work.

This is not recommended for newer Perl versions. It is merely provided as a workaround for sites running on older Perls. Also, including external files with do or require does not work when using this (see the section about require and do for more information on this).

use strict;

Earlier versions of PerlHP did not fully support the use of use strict;. Current versions, however, do. It is recommended that you do use it for all PerlHP programs, as this is a good way to avoid some security pitfalls with the automatic globals. To properly utilize use strict;, declare all of your own variables with my, and all variables that come from external sources, such as query variables and cookie variables, with our. my will undefine the previous value of any variable, guaranteeing that they stay untouched by external sources.

Alternatively, you can use the PHP-style %_REQUEST hash to access your external variables.

Also remember that everything after use PerlHP; is PerlHP code. You either have to put the use strict; statement before this, or inside a code section later.

 #!/usr/bin/perl
 use strict;
 use PerlHP;
 #!/usr/bin/perl
 use PerlHP;
 <% use strict; %>

HTML sections

The HTML parts of the page are turned into simple print statements. This means that you can make blocks that extend between different code blocks.

 <% for(1..10) { %>
 *
 <% } %>

This is perfectly legal code, which will output ten asterisks.

require and do

Earlier versions of PerlHP did not support the use of require and do to include other PerlHP files, but this is now fully supported. You can use this to conditionally include parts of pages, or to include templated material in pages, such as side bars and footers. Remeber to put a use PerlHP; at the top of each included file, too!

 <% do "include.pl" %>

This does, however, not work in Perl 5.6.*. You can still include pages by reading the file manually, running the perlhp() function on it, and then using eval to execute the results.

 <% eval perlhp(readfile("include.pl")) %>


COPYRIGHT

No copyright is claimed on any part of this code; it is released into the Public Domain.


AUTHORS

!WAHa.06x36 <[email protected]>, Michael Mathews <[email protected]>