focal (3) Embperl::TipsAndTricks.3pm.gz
NAME
Embperl::TipsAndTricks - Embperl Tips and Tricks
Contents
Tips and Tricks
Alternative Way To Do Global Variables, using __PACKAGE__
Global Variables Via Namespaces
Handling Queries in DBI
Handling Exits
Handling Errors
Development and Production Websites
NAME
Embperl::TipsAndTricks - Embperl Tips and Tricks
Tips and Tricks
This document follows on from the Embperl/EmbperlObject introductory tutorial. As you can see from that,
Embperl/EmbperlObject enables extremely powerful websites to be built using a very intuitive object-
oriented structure. Now, we'll look at some additional, "unofficial" techniques which may also be useful
in certain circumstances.
This is a small collection of personal tricks which I have developed over the course of months using
EmbperlObject in my own websites. I hope they are useful, or at least spur you on to develop your own
frameworks and share these with others.
If you have any Tips & Tricks you want to share with the public please send them to richter at embperl
dot org .
Alternative Way To Do Global Variables, using __PACKAGE__
In the process of developing a large website I have found it can be a little onerous at times to use the
Request object to pass around global data. I would like to just create variables like $xxx rather than
typing $req->{xxx} all the time. It may not seem like much, but after a while your code can start looking
a lot more complex because of all the extra brackets and suchlike. As a typical lazy programmer, I looked
for a way to simplify this.
The method I am going to describe should be used with caution, because it can increase memory useage
rather dramatically if you're not careful. The way I use it, no extra memory is used, but you do need to
be aware of the issues.
Basically, you change the way you include files from /base.html, so that they are included into the same
package as /base.html:
[- Execute ({inputfile => '*', package => __PACKAGE__}) -]
You should only do this with HTML files which are included from /base.html, not with the files such as
subs.html - those files have to be in their own packages in order for Perl inheritance to work. You can't
use this technique with any files which are accessed via method calls.
So how does this make things better? Well, since all these files now share the same package, any
variables which are created in one of the files is accessible to any of the other files. This means that
if you create $xxx in /init.html, then you can access $xxx in /head.html or any other file. This
effectively gives you global variables across all the files which are included from /base.html into the
same package as /base.html.
The thing you need to be careful of here is that if one of these files is included more than once
elsewhere on the website, then it will be separately compiled for that instance - thus taking up more
memory. This is the big caveat. As a rule, if your files are all just included once by /base.html, then
you should be fine. Note that you'll also need to change any calls to parent files, for example:
/contact/init.html
[- Execute ({inputfile => '../init.html', package => __PACKAGE__}) -]
[-
# Do some setup specific to this subdirectory
-]
This is ok, since ../init.html will still be compiled into the same package as the rest of the files
included from /base.html, and so only one version of it will exist in the Embperl cache. Thus memory
usage is not increased.
I like this technique because it simplifies the look of my code, which is important for projects
containing complex algorithms. It is not the "official" way to implement globals though, and should be
used with care.
Global Variables Via Namespaces
The previous section described a way to share variables between different files which are included from
/base.html, by using the same package across all the files. However this doesn't help us much when
dealing with the method files such as subs.html, because these files have to have their own packages - so
we are back to square one.
There is another way to share variables across even different packages, and that is by using namespaces.
For variables that need to be accessible even from subs.html, you could use a namespace which is specific
to your website. For example, if your website domain is mydomain.com, then you could create variables
using the form
$mydomain::xxx = "hello";
As long as you then make sure that you only use this namespace on this website (and other websites on the
same Apache web server use their own namespaces), then you shouldn't get any conflicts. Once again, use
this with caution, since you introduce the possibility of inadvertently sharing variables between
completely different websites. For example, if you cut and paste some useful code from one website to
another, you will need to make sure you change the namespace of any globals. Otherwise, you could get
some very obscure bugs, since different requests to the various websites could conflict.
You also need to be careful about variable initialization, since these globals will now exist between
different requests. So, it's possible that if you don't re-initialize a global variable, then it may
contain some random value from a previous request. This can result in obscure bugs. Just be careful to
initialize all variables properly and you'll be fine.
Finally, note that Embperl will only clean up variables which don't have an explicit package (i.e. are in
one of the packages automatically set up by Embperl). Variables in other namespaces are not automatically
cleaned up. As a result, you need to pay closer attention to cleaning up if you use your own namespaces.
The safe way to clean up a variable is simply to 'undef' it.
Handling Queries in DBI
If you are like me, you probably use DBI extensively to enable your dynamic websites. I have found the
cleanup of queries to be onerous - e.g. calling finish() on queries. If you don't do that, then you tend
to get warnings in your error log about unfinished queries.
What I do these days is use a global hash, called e.g. %domain::query (see the previous section for using
namespaces to safely implement global variables). Then, whenever I create a query, I use this variable.
For example:
$domain::query{first_page} = $domain::dbh->prepare (qq{
SELECT *
FROM pages
WHERE page = 1
});
$domain::query{first_page}->execute();
my $first_page = $domain::query{first_page}->fetchrow_hashref();
This little pattern, I find, makes all my queries easier to read and keep track of. You give each one a
name in the %domain::query hash that makes sense. Then, at the end of each request, in the /cleanup.html
file, you can do something like this:
while (($name, $query) = each (%domain::query))
{
$query->finish();
}
$domain::dbh->disconnect();
Once again, this method is not really the "official" way of doing things in Embperl. You should use the
Request object to pass around global variables if you're not comfortable with the risks involved with
namespaces (e.g. conflicting websites on the same web server).
Handling Exits
You will often find that you want to terminate a page before the end. This doesn't necessarily indicate
an error condition; it can be just that you've done all you want to do. When you do this, it is good to
first clean up, otherwise you can get annoying warnings showing up in your error logs.
I use the following framework. /cleanup.html is Executed from /base.html, and it is the last thing that
is done. It calls the cleanup() function in the /subs.html file:
/cleanup.html
[-
$subs->cleanup ();
-]
/subs.html
[!
sub cleanup
{
while (($name, $query) = each (%domain::query))
{
$query->finish();
}
$domain::dbh->disconnect();
}
sub clean_exit
{
cleanup();
exit();
}
!]
Now, whenever I want to exit prematurely, I use a call to $subs->clean_exit() rather than just exit().
This makes sure that the queries and database connections are shut down nicely.
Handling Errors
The EMBPERL_OBJECT_FALLBACK directive in httpd.conf allows you to set a file which will be loaded in the
event that the requested file is not found. This file should be relative to the same directory as
base.html.
I have found that making a special /errors/ directory is useful, because it enables that special
subdirectory to define its own head.html file, init.html and so on. So, I then just put this in
/notfound.html:
[-
$http_headers_out{'Location'} = "/errors/";
clean_exit();
-]
See the previous section, "Handling Exits" for more on clean_exit().
Development and Production Websites
When I am developing a website, I usually use at least two machines. I have a workstation where I do
developing and testing, and a separate production server, which is accessed by the public. When I am
finished making changes to the development version of the website, I move it over to the production
server for testing there. However when I do this, I usually don't copy it immediately over the existing
production version, because there are sometimes issues with Perl modules which haven't been installed on
the server, or other issues which break the code on a different machine. So I use a separate virtual
server and subdomain (which is easy if you run your own DNS) to test the new version. For example if the
production version of the server is at www.mydomain.com, then I might do testing on the production server
under test.mydomain.com, or beta. or whatever subdomain you like. This means you have to create a new
virtual server in the httpd.conf file. You also obviously create a new directory for the test server (see
below for an example).
When you do all this, you end up with a very nice, isolated testing environment on the same server as
production. Obviously you hopefully did all your major testing on your workstation, where you can crash
the machine and it doesn't matter too much. The production server testbed is a last staging area before
production, to get rid of any lingering glitches or omissions. When you're sure it's all working
correctly you just copy the files from one directory tree (test) to another (production) on the same
machine. This test server can also be used as a beta of the new production version. Friendly users can be
given access to the new version, while the old version is still running.
One issue that comes up when you do this is that of databases. It is very likely that you will be using a
special test database rather than the live one to test your new version. It would be very unwise to use a
production database for testing. So your production database might be called "mydatabase", and the test
one called "mydatabase_test". This is fine, but it means that you have to remember to change the database
name in your code when you copy the files over to production. This is very error prone. The solution is
to set variables like the database name in httpd.conf, by setting an environment variable. You just add
it to the virtual server section.
Here is a real example of two virtual servers on the same production machine, which use two different
directories, separate log files and different databases. The website is crazyguyonabike.com, which is a
journal of a bicycle ride I did across America in 1998. I decided to expand the site to allow other
cyclists to upload their own journals, which resulted in substantial changes to the code. I wanted to
keep the original site up while testing the new version, which I put under new.crazyguyonabike.com. Here
are the relevant apache settings:
/etc/apache/httpd.conf
# The production server
<VirtualHost 10.1.1.2:80>
ServerName www.crazyguyonabike.com
SSLDisable
ServerAdmin neil@nilspace.com
DocumentRoot /www/crazyguyonabike/com/htdocs
DirectoryIndex index.html
ErrorLog /www/crazyguyonabike/com/logs/error_log
TransferLog /www/crazyguyonabike/com/logs/access_log
ErrorDocument 403 /
ErrorDocument 404 /
PerlSetEnv WEBSITE_DATABASE crazyguyonabike
PerlSetEnv WEBSITE_ROOT /www/crazyguyonabike/com/htdocs
PerlSetEnv EMBPERL_DEBUG 0
PerlSetEnv EMBPERL_ESCMODE 0
PerlSetEnv EMBPERL_OPTIONS 16
PerlSetEnv EMBPERL_MAILHOST mail.nilspace.com
PerlSetEnv EMBPERL_OBJECT_BASE base.html
PerlSetEnv EMBPERL_OBJECT_FALLBACK notfound.html
</VirtualHost>
<VirtualHost 10.1.1.2:80>
ServerName crazyguyonabike.com
Redirect / http://www.crazyguyonabike.com
</VirtualHost>
# Set EmbPerl handler for main directory
<Directory "/www/crazyguyonabike/com/htdocs/">
<FilesMatch ".*\.html$">
SetHandler perl-script
PerlHandler HTML::EmbperlObject
Options ExecCGI
</FilesMatch>
</Directory>
# The test server
<VirtualHost 10.1.1.2:80>
ServerName new.crazyguyonabike.com
SSLDisable
ServerAdmin neil@nilspace.com
DocumentRoot /www/crazyguyonabike/com/new
Alias /pics /www/crazyguyonabike/com/pics
DirectoryIndex index.html
ErrorLog /www/crazyguyonabike/com/logs/new_error_log
TransferLog /www/crazyguyonabike/com/logs/new_access_log
ErrorDocument 401 /user/register/
ErrorDocument 403 /
ErrorDocument 404 /
PerlSetEnv WEBSITE_DATABASE crazyguyonabike_new
PerlSetEnv WEBSITE_ROOT /www/crazyguyonabike/com/new
PerlSetEnv EMBPERL_DEBUG 0
PerlSetEnv EMBPERL_ESCMODE 0
PerlSetEnv EMBPERL_OPTIONS 16
PerlSetEnv EMBPERL_MAILHOST mail.nilspace.com
PerlSetEnv EMBPERL_OBJECT_BASE base.html
PerlSetEnv EMBPERL_OBJECT_FALLBACK notfound.html
</VirtualHost>
# Set EmbPerl handler for new directory
<Directory "/www/crazyguyonabike/com/new/">
<FilesMatch ".*\.html$">
SetHandler perl-script
PerlHandler HTML::EmbperlObject
Options ExecCGI
</FilesMatch>
</Directory>
# Restrict access to test server
<Directory /www/crazyguyonabike/com/new>
AuthType Basic
AuthName CrazyTest
Auth_MySQL_DB http_auth
Auth_MySQL_Encryption_Types Plaintext
require valid-user
PerlSetEnv EMBPERL_OPTIONS 16
PerlSetEnv EMBPERL_MAILHOST mail.nilspace.com
</Directory>
Note that the test and production servers each get their own databases, directories and log files.
You can also see that I restrict access to the test server (which is generally wise, unless you actually
like hackers potentially screwing with your head while testing). For basic authentication I use
mod_auth_mysql, which is available from the MySQL website. It is nice because it allows you to
authenticate based on a MySQL database.
When you use PerlSetEnv to pass in variables, you access these variables in your code as follows:
$db_name = $ENV{WEBSITE_DATABASE};
If you move those constants which differ between the test and production versions of the same code into
the httpd.conf file, then you can just copy the files over from the test directories to the production
directory without any alterations. This cuts down on editing errors and also documents specific constants
in one place.
Author
Neil Gunton neil@nilspace.com