/ 
Embperl-3.0.0
River stage one • 3 direct dependents • 3 total dependents
/ Embperl::TipsAndTricks

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 / https://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