Provided by: libembperl-perl_2.5.0-11build1_amd64 bug

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