php|architect (December 2003)

DECEMBER 2003 The Nukes and Beyond ANNIVERSERY From yesterday's Nukes to the future of Xaraya with veteran CMS develo...

225 downloads 950 Views 4MB Size Report

This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Report copyright / DMCA form

DOWNLOAD PDF

DECEMBER 2003

The Nukes and Beyond

ANNIVERSERY

From yesterday's Nukes to the future of Xaraya with veteran CMS developer John Cox

EDITION

The Magazine For PHP Professionals

JFFNMS

Inside the 'Just For Fun Network Management System'

Improving Web Application Management The Software Sleuth

The inside scoop from creator Marco Pratesi

Tracking defects through a system logging framework

www.phparch.com

Mailing List Management with PHPMailer Creator Brent Matzelle on handling mail within PHP

Get Ready For php | Cruise Plus:

See inside for details

March 1st - March 5th 2004

Tips & Tricks, Book Reviews, Product Reviews and much

This copy is registered to: Richard Freem [email protected]

1

The PHP Layers Menu Project Revealed

YEAR

Gentoo's new approach for web administrators

In partnership with Zend Technologies

Zend Studio 3.0 is the official PHP IDE of php|cruise

We’ve got you covered, from port to sockets.

php | Cruise

Port Canaveral • Coco Cay • Nassau

March 1st - March 5th 2004 ENJOY LEARNING PHP IN A FUN AND EXCITING ENVIRONMENT—AND SAVE A BUNDLE! Features

Visit us at www.phparch.com/cruise for more details. Andrei Zmievski - Andrei's Regex Clinic, James Cox - XML for the Masses, Wez Furlong - Extending PHP, Stuart Herbert - Safe and Advanced Error Handling in PHP5, Peter James - mod_rewrite: From Zero to Hero, George Schlossnagle Profiling PHP, Ilia Alshanetsky - Programming Web Services, John Coggeshall Mastering PDFLib, Jason Sweat - Data Caching Techniques Plus: Stream socket programming, debugging techniques, writing high-performance code, data mining, PHP 101, safe and advanced error handling in PHP5, programming smarty, and much, much more!

php | Cruise

Conference Pass

$ 899.99**

Hotel

Included

Meals

Totals:

Traditional PHP Conference* $ 1,150.00

($ 400.00)

Included***

$ 899.99

($ 200.00)

$1,750.00

You Save $ 850 * Based on average of two major PHP conferences ** Based on interior stateroom, double occupancy *** Alcohol and carbonated beverages not included

TABLE OF CONTENTS

php|architect Departments

5

Features

9 Editorial

Toward the Improvement of Web Application Management by Stuart Herbert

I N D E X

6

15

What’s New!

Inside the 'Just For Fun Network Management System' by Javier Szyszlican

45

Product Review

28

DBDesigner4 by Eddie Peloke

Beyond the Nukes: John Cox on PHP-based CMS, and Xaraya by John Cox

61

Tips & Tricks By John W. Holmes

34 The PHP Layers Menu Project Revealed

65

by Marco Pratesi

Book Reviews by Peter MacIntyre

69

50 Customized Mailing List Management with PHPMailer

exit(0);

by Brent R. Matzelle

Frequently Annoying Questions By Marco Tabini

56 The Software Sleuth Tracking application defects through a system logging framework by Graeme Foster

December 2003

●

PHP Architect

●

www.phparch.com

3

! W E N

Existing subscribers can upgrade to the Print edition and save! Login to your account for more details.

php|architect

Visit: http://www.phparch.com/print for more information or to subscribe online.

The Magazine For PHP Professionals

php|architect Subscription Dept. P.O. Box 54526 1771 Avenue Road Toronto, ON M5M 4N5 Canada Name: ____________________________________________

Your charge will appear under the name "Marco Tabini & Associates, Inc." Please allow up to 4 to 6 weeks for your subscription to be established and your first issue to be mailed to you. *US Pricing is approximate and for illustration purposes only.

Choose a Subscription type:

Address: _________________________________________

Canada/USA

$ 97.99 CAD

($69.99 US*)

City: _____________________________________________

International Surface

$111.99 CAD

($79.99 US*)

International Air

$125.99 CAD

($89.99 US*)

Combo edition

$ 14.00 CAD

($10.00 US)

State/Province: ____________________________________ ZIP/Postal Code: ___________________________________

(print + PDF edition)

Country: ___________________________________________ Payment type: VISA Mastercard

American Express

Credit Card Number:________________________________ Expiration Date: _____________________________________ E-mail address: ______________________________________ Phone Number: ____________________________________

Signature:

Date:

*By signing this order form, you agree that we will charge your account in Canadian dollars for the “CAD” amounts indicated above. Because of fluctuations in the exchange rates, the actual amount charged in your currency on your credit card statement may vary slightly. **Offer available only in conjunction with the purchase of a print subscription.

To subscribe via snail mail - please detach/copy this form, fill it out and mail to the address above or fax to +1-416-630-5057

EDITORIAL

E D I T O R I A L

R A N T S

I

n the grand scheme of things, one year is not a really long time. We all got a little older, some dear ones passed away and many more were born. Global warming got a little worse (or so, at least, meteorologists seem to agree from time to time) and El Niño was supplanted by La Niña. Much to the general joy of his parents (and of diaper companies worldwide), my son Daniel arrived. In the lifetime of a new magazine, however, a year is a long time. As Arbi and I were recently celebrating the start of our collaboration on what has become php|a (which started quite a long time before the first issue was even announced), the temptation of falling for that very human of games, Do You Remember, was very strong. To be certain, there is a lot to remember. Publishing the first twelve issues of php|a has been an incredible ride—I am still short of breath from it! I won’t dwell too much on it—I like to look at the future rather than at the past, and this month’s exit(0) column, which you’ll find in its usual slot on page 66, already contains all the reminiscing that I want to do for one issue. Let me concentrate, instead, on this month’s content. First of all, a big thank you goes to Brian K. Jones, our Editor-At-Large, who, for this special issue, has put together an impressive collage of articles from some of the best authors out there. The contents of the magazine you’re holding in your hands (or reading on your screen) have been in the works for a long time—almost six months— and I hope you’ll agree with us that it was worth the wait. Stuart Herbert’s Toward the Improvement of Web Application Management has to be my favourite article from this month’s issue. It deals with a problem I’ve been struggling with myself very recently when a client asked me to write an installation management system for one of their applications. Due to a number of reasons, including the fact that the application runs on a slightly obsolete environment, I had to come up with a completely customized solution that took quite a bit of development time to build. As PHP evolves into a more complex and complete language and its potential begins transcending web applications into new areas (such as client-side GUI software), the development community will feel the need for an installation management technology more and more. Being able to install a PHP application at the click of a mouse,

December 2003

●

PHP Architect

●

www.phparch.com

php|architect Volume II - Issue 12 December, 2003

Publisher Marco Tabini Editor-at-Large Brian K. Jones [email protected] Editorial Team Arbi Arzoumani Peter MacIntyre Brian Jones Eddie Peloke Graphics & Layout Arbi Arzoumani Managing Editor Emanuela Corso Director of Marketing J. Scott Johnson [email protected] Account Executive Shelley Johnston [email protected] Authors John Cox, Graeme Foster, Stuart Herbert, Brent Matzelle, Marco Pratesi, Javier Szyszlican php|architect (ISSN 1705-1142) is published twelve times a year by Marco Tabini & Associates, Inc., P.O. Box 54526, 1771 Avenue Road, Toronto, ON M5M 4N5, Canada. Although all possible care has been placed in assuring the accuracy of the contents of this magazine, including all associated source code, listings and figures, the publisher assumes no responsibilities with regards of use of the information contained herein or in all associated material.

Contact Information: General mailbox: [email protected] Editorial: [email protected] Subscriptions: [email protected] Sales & advertising: [email protected] Technical support: [email protected] Copyright © 2002-2003 Marco Tabini & Associates, Inc. — All Rights Reserved

EDITORIAL without having to worry about manually configuring Apache, the web application or PHP itself, could be a major advantage of PHP over many other platforms. The problem, of course, is how does one write a common software deployment tool when a PHP application can be installed on so many different platforms, each with its own individual quirks and configuration parameters? If you think that this is a moot point, because most people only use variants of Unix for their production systems, think again. There has been a recent push to make PHP more stable and usable under Windows, with Zend, in particular, forging ahead with a new FastCGI component and a Windows edition of their Performance Suite. Once someone can find an answer to this question, deploying PHP applications in complex environments will be a breeze. Until then, we’ll have to rely on our manual skills, and hope that the term “human error” won’t apply to us.

php|a

N E W

S T U F F

What’s New! Zend Studio 3.0.1. Zend.com announces the release of Zend Studio 3.0.1. What’s New? According to Zend.com changes in ZDE 3.0.1 include: General • Stopping a Search operation could take a very long time • Presence of very large content on the clipboard could result in degraded performance • Renaming a directory could sometimes result in an internal error • Refresh problem in ‘Project Inspector’ Appearance • Under certain situations, the ZDE could launch with all of the toolbar icons disabled. • Shortcut keys were not always visible under Windows. • Docking and undocking Profiler windows didn’t restore the same location and size. • Focus was sometimes lost during Alt-Tab under Windows. • Improved default keymaps under OS X • Room for the line number in the status bar was sometimes too small under Linux. December 2003

●

PHP Architect

●

www.phparch.com

There are many other changes in areas such as the debugger, profiler, and editor. Get all the information from Zend.com.

NuSphere Technology Platform 3.1 The NuSphere Technology Platform is an integrated distribution of the most popular open source components made for those who are just beginning to develop sites and applications. It contains the most recent versions Apache, mod_ssl, mod_perl, Perl, phpmyadmin, phppgadmin, and of course PHP. This release includes Apache 1.3.29, mod_ssl 2.8.16, mod_perl 1.29, Perl 5.8.0, phpmyadmin 2.5.4, phppgadmin 3.1, and PHP 4.3.4. Visit Nusphere.com for more information.

Tidy 1.0 Coggeshall.org announces: ”I officially released Tidy 1.0 today for PHP 4.3.x and PHP 5. This release fixes a num-

6

NEW STUFF ber of PHP5-related bugs dealing with node traversals, and is even rumored to work on Windows. Tidy is a binding for the Tidy HTML clean and repair utility which allows you to not only clean and otherwise manipluate HTML documents, but also traverse the document tree using the Zend Engine 2 OO semantics. Any and all users of tidy are encouraged to upgrade their modules to 1.0 which can be found here in the PECL repository. Feedback and comments of course are always welcome.” You can get more information or download from Coggeshall.org.

Smarty 2.6.0 Smarty is a template engine for PHP. Many other template engines for PHP provide basic variable substitution and dynamic block functionality. Smarty takes a step further to be a “smart” template engine, adding features such as configuration files, template functions, and variable modifiers, and making all of this functionality as easy as possible to use for both programmers and template designers. Smarty also converts the templates into PHP scripts, eliminating the need to parse the templates on every invocation. This makes Smarty extremely scalable and manageable for large application needs. “This release incorporates numerous enhancements, refinements, bug-fixes, speed-ups and architectural changes that will benefit developers and designers. Compatibility with supported functionality of previous releases has been a specific focus allowing most existing installations to upgrade with minimal—if any—changes required. The 2.6.0 release also marks a maturation of the Smarty codebase, source code and documentation. With improved error handling, enhanced diagnostic capabilities, better multi-platform support and numerous bug-fixes, many testers have noted that 2.6.0 is more stable and easier to debug than previous versions. Some adopters are already using pre-release versions of 2.6.0 on production sites.” For more information visit: Smarty.php.net.

Savant Template System 1.1 PHPSavant announces the release of version 1.1. What is it? PHPSavant.com describes it as: “a powerful but lightweight PEAR-compliant template system for PHP. It is non-compiling, and uses PHP itself as its template language so you don’t need to learn a new markup system. It has an object-oriented system of template plugins and output filters, so it sports almost all of the power of Smarty

December 2003

●

PHP Architect

●

www.phparch.com

with almost none of the overhead.” According to PHPSavant.com, Savant does four things: • Assigns variables, references, and objects for parsing through to a PHP-based template script via the methods assign(), assignRef(), and assignObject() • Parses then displays or returns the template script output via the display() and fetch() methods • Provides an object-oriented system of plugins that add “convenience functions” for your display logic using plugin() and splugin() methods • Provides an object-oriented system of output filters to automatically process the parsed output of the template script via the setFilter() and mapFilter() functions. Get more information from PHPSavant.com

phpPgAdmin 3.2.1 PhpPgAdmin is a fully functional PHP-based administration package for PostgreSQL. It has all the basic functionality you need to completely administer a PostgreSQL server and/or database, including the ability to administer views, sequences, stored procedures, and triggers. Features include the ability to create and drop databases; create, copy, drop, and alter tables/views/sequences/functions/triggers; edit and add fields (to the extent Postgres allows); execute any SQL-statement, even batch-queries; manage keys on fields; create and read dumps of database and tables; and administer one single database, multiple servers, and Postgres users/groups. This version fixes a trailing newline problem in the Chinese Sim translation, and adds French and Russian translations. For more information visit: http://phppgadmin.sourceforge.net

Zend is Turning Four! Zend is happy to announce that the company has been around for almost four years! They're celebrating by offering a "free" gift for anyone that wants one. December is Zend's 4th birthday and we are grateful for so many things including the active PHP community and your involvement in it. To say thanks, we have designed the Zend Collector's Edition Winter Scarf and we are giving it away for FREE. All we ask is that you chip in for the shipping and handling charges...

7

NEW STUFF ADOdb 4.02 Released with PHP5 Support ADOdb 4.02 now auto-detects PHP5. If PHP5 is detected then the following features will be enabled: • Support for PHP5 iterator overloading • Support for PHP5 exceptions PHP is a wonderful language for building dynamic web pages. Unfortunately, PHP’s database access functions are not standardized. Every database extension uses a different and incompatible API. This creates a need for a database class library to hide the differences between the different databases so we can easily switch databases. Unique Features of ADOdb include: • Easy for Windows programmers to understand. Makes porting ASP code to PHP easy because many of the conventions are similar to Microsoft’s ADO. • We provide support code to handle inserts and updates which can be adapted to multiple databases quickly. Methods are provided for date handling, string concatenation and string quoting characters for differing databases. • A metatype system is built in so that we can figure out that types such as CHAR, TEXT and STRING are equivalent in different databases. • Easy to port because all the database dependent code are stored in stub functions. You do not need to port the core logic of the classes. • SQL to dropdown (<SELECT>) support included • PHP4 Session support. For more information go to: http://php.weblogs.com/2003/11/05#a3100

PHPMyFAQ 1.3.9 PhpMyFAQ is a multilingual, completely database-driven FAQ system. It also offers a content management system, flexible multi-user support, a news system, user tracking, language modules, templates, extensive XML support, PDF support, a backup system, and an easy to use installation script. PhpMyFAQ 1.3.9 is released with major feature enhancements. “This release contains improvements in highlighting searched words, an updated English language file, BBCode support for the news, better category browsing, graphical analysis of votings, and date information which is ISO 8601 compliant. Other additions include a Russian lanDecember 2003

●

PHP Architect

●

www.phparch.com

guage file, an enhanced BB-Code Editor, fixes for some multibyte issues, and improvements to the display of images in PDF export. This version fixes a lot of minor bugs, and should work on a server running PHP 5.0.0b2. “ For more information visit: http://www.phpmyfaq.de/

PhpDig Announces PhpDig 1.6.5 PhpDig is a PHP search engine that uses a MySQL database backend. It features indexing of both static and dynamic pages, spidering of almost all links in HTML content, in hrefs, areamaps, and frames, and full text indexing. The search results appearance is skin-able, using a very simple templates system. It can index PDF and Office files using external tools. PhpDig version 1.6.5 has been released as a minor release. This version now adds escapes to the path and file if necessary, fixes the highlight when the keyword is followed by period, relaxes the regex to allow for more characters, changes the maximum number of results per site to allow all results in limit to searches, enables the search depth of level zero for the index, and adds an option to bypass the renice command. For more information go to: http://www.phpdig.net/

Errata

php|a

To phpEd or not to phpEd It's not every day that one gets to make the same mistake twice in two different occasions – and after having been notified of it. But, we outdid ourselves when we used the wrong logo to identify NuSphere's phpEd IDE twice, once in a news item and then again in last month's review of the product. Instead of using the right NuSphere logo, we ended up using the logo for the open-source phpEdit product. Much to the chagrin of everbody involved, making the same mistake twice is, as they say, pretty bad. Our apologies go out both to NuSphere, who has been most cooperative with us, and to the developers of phpEdit, who have been very understanding and informed us immediately (twice) of the error.

8

Toward the Improvement of Web Application Management

F E A T U R E

by Stuart Herbert Generally speaking, web server and site administrators who manage applications and virtual hosts for many users have a lot of overhead in terms of manual administrative tasks. While it would seem that some of this work is unavoidable, the Gentoo Linux project is aiming to simplify and consolidate some of this work, making easy things brainless, and harder things less taxing. The road to administrator freedom in this area is somewhat arduous, but a clear methodology, described herein, can be a very good start. Introduction It’s been a few months since my last article for php|architect. In that time, a surprising amount has changed. The missus and I both have new jobs, we’re getting a new car next week, and we’re finally able to put behind us the four years of litigation from the car accident I had in ‘99 (in case you’re wondering, we won). Although all of us writing in this first anniversary issue of php|architect have strong opinions about PHP and the community that has grown up around this wonderful little language, I think it’s important to start this article by reminding our readers – especially those that contribute to some of the PHP mailing lists - that there really are more important things in life. One of the other things that has changed is that I’m now one of the developers for the Gentoo Linux project. Gentoo Linux is a community-based Linux distribution – which basically means that all the work is done by volunteers working in their free time. Many of the volunteers are like me – they got involved because they use Gentoo themselves, and they want to improve how it works. And right now, I’m involved in improving how applications written in PHP – what I call web-based applications – are installed. A quick search through Freshmeat will turn up a huge variety of projects that use the PHP language. There are a gazillion and one content management systems, with new ones appearing every day. There are numerous database management tools, providing essential functionality for the PHP developer. Blogs and calendar December 2003

●

PHP Architect

●

www.phparch.com

tools also feature highly. But there’s only one project providing a packaged installer for PHP applications. My point is this: there are a lot of people using PHP to create dynamic Web applications. But how many of these projects ship with your favorite distribution? How many of these projects can be installed quickly and effortlessly under the web server of your choice? The answers are predictable. In the battle for the desktop, distributions have largely ignored the needs of website administrators. Apart from the usual suspects, distributions by and large just don’t include a rich variety of the PHP applications that are out there. Because Apache is such a high quality – and free – web server, no thought has been given to what happens when you don’t or can’t use Apache. And that is before I mention anything about virtual hosting. During the summer, the Gentoo Linux project decided it was time to tackle this problem once and for all. A spec was thrashed out on the gentoo-developers mailing list, and approved by the distribution leaders as GLEP #11. As 2003 draws to a close, a small team of us volunteers are busy turning that idea into reality. Over the last year, subscribers to php|architect will

REQUIREMENTS PHP: 4.3+ OS: N/A Applications: N/A Code: N/A Code Directory: N/A

9

FEATURE


have read a lot about PHP itself – about how to write better PHP code, or how to use PHP to do new things. Well, there’s more to using PHP than writing PHP script files. As it turns out, there’s a lot more. The Problems Of Installing A PHP Application I can picture the puzzled faces out there already. What’s so difficult about installing a web-based application written in PHP? Make a new directory inside the website, dump the contents of the tarball, and stick in the username and password for the database server. What more does anyone need to do? When we first started discussing this on the Gentoo mailing lists, I know that many of the people involved in the discussion were surprised at just how much there is to take into account. To my mind, we probably spent more time making sure we all understood the problems fully than we did on solving those problems. The central problem that has been cropping up time and time again on Gentoo is quite a straight-forward one. Just where should we install web-based applications to? One of the really great features of Gentoo is that you can install any supported application – webbased or otherwise – with just a single command – emerge. Several attempts had been made to autodetect the document root of the website, but none of them coped well with all the possible configurations that a user could legitimately setup. From this starting point sprang quite a few more problems to consider. Gentoo’s webserver of choice is Apache, and with good reason. It does most jobs well, we can distribute it on CDs, there’s a ton of third-party modules to extend its capabilities, and above all it works. We run Apache under its own user for security reasons, and therefore all of our install scripts for web-based applications simply installed the files to be owned by the Apache user and group. But we do support more than just the one webserver (heck, you can even use the NCSA webserver if you want), and crucially at the heart of Gentoo’s philosophy is this statement: “The most fundamental issue is designing a technology that allows us and others to do what they want to do, without restriction.” Running chown apache:apache on every file just isn’t the way to deal with this. It is quite unusual for Gentoo users to want to use a different webserver, but it’s not unusual for our users to want to host more than one website on their servers. Sometimes, these servers are serving up websites that are owned and managed by more than one user. Each of these users may want to use the same forum software, for example – but might want to run different December 2003

●

PHP Architect

●

www.phparch.com

versions for whatever reason. And certainly the server administrators do not want to have to upgrade every installed copy of the forum software in one go. Realistically, we needed to be able to have an arbitrary number of applications installed on one machine at any one time; and an arbitrary number of versions of the same application too. We also agreed that we needed to be able to do this without making life more complicated for Gentoo users who only host the one website on their servers. Whatever we came up with had to fit into the Gentoo way of doing things. Portage (see the “What Is Portage?” sidebar below) – the Gentoo package installer – had to play its part. Installation, upgrades, and removals had to be automated; at least as automated as they were before we began. So, just to recap, we needed a solution for the following problems: • How do we work out which document root directory to install the web-based application into? • How do we decide which user and group should own the files on disk? • How can we support servers that need to What Is Portage?

Portage is Gentoo Linux’s installation system. Think of it as a huge library of installation scripts for your favourite applications; a library that sits on your computer, and is kept up to date over the Internet from our rsync mirrors. No more searching the Net, trying to find a compatible package for that application that you just have to have on your machine. If there’s a Gentoo install script for it, it’ll be in Portage. Just like Debian’s apt-get system, Portage automatically handles downloading and installing all of the dependencies – all from one command. However, unlike Debian, packages on Gentoo are normally compiled from source code. It’s true that this can take a bit of time for larger packages such as Gnome, KDE and OpenOffice, but once you’re used to it, it feels no less natural than installing precompiled binaries. For more information about Gentoo’s Portage system, take a look at the excellent documentation on http://www.gentoo.org/.

10

FEATURE


run multiple copies of the same application? • How do we support installing applications under any of the web servers supported by Gentoo Linux? • How can we deliver all of this through Gentoo’s Portage installation system? The New Home For Web Server Document Roots Faced with our list of problems, do we solve them in some sensible order? Of course not. The first thing we did was to solve a different problem – to put some foundations in place to build our solution on. We realized that Gentoo Linux didn’t have a recommendation for where to put websites on a server. Sure, by default Apache was set to look in /home/httpd/htdocs, but that was a solution for hosting just the one website at best. What we wanted was a default scheme that could support one, two, ten, a hundred different websites – all in the same, standardized way. In Figure 1, you’ll find a screenshot of the new directory layout that the Gentoo Linux project is adopting. In keeping with the latest beta of the FHS – the accepted standard layout of Linux filesystems – we’re placing all websites under the new /srv/www directory. In the default situation – where a server only has the one website on it – this website will be stored in /srv/www/localhost/. Later, when you want to add more websites, you can just create them alongside, as shown in Figure 1. For example, all the files for the host

www.gnqs.org are stored in /srv/www/www.gnqs.org/.

Don’t have a domain name? Accessing a virtual host through an IP address? Not a problem. Just put the files into /srv/www/, such as /srv/www/127.0.0.1/. And you can use symlinks to provide aliases for websites that can be accessed through multiple domain names and/or IP addresses. Underneath each host’s directory (e.g. /srv/www/localhost/), we still have the standard four directories that Apache users will expect to see. • cgi-bin – for your cgi-bin programs • errors – for storing local customized pages for HTTP 404 et al errors • icons – for the icons that appear when you browse a directory that has no index.html file • htdocs – the document root directory for the website This scheme finally standardizes the way that websites will be installed on Gentoo Linux machines, and has to be a great step forward. But how does it help us determine where to install web-based applications? For servers that are hosting only the one website, we can install the web-based application under /srv/www/localhost/. Of course, this won’t be hardcoded into our installer, so users who really want to put this somewhere else will be able to change a config file in /etc to suit their tastes. That’s the easy part of the problem. Real problems come with volume – and with scale.

Figure 1: /srv/www - The new home for website document root directories

December 2003

●

PHP Architect

●

www.phparch.com

11

FEATURE


Or, in terms of website hosting, they come with virtual hosting – and with lots of users managing their own websites on the same box. In that sort of environment, people are going to want to install a variety of web-based applications all over the place. I don’t believe that there is a good default location. The users are just going to have to tell us where to install the web-based application to. Without the constraint of trying to find a good default location to install web-based applications into, we were free to come up with a more creative solution to handling application installations. We decided to split the job into two parts. Installing Applications: The Webapp Image Each web-based application is first installed into /usr/share/webapps/-; and each version of each application gets its own directory. You can see an example of what this looks like in Figure 2. I’m calling the contents of these directories the webapp image. At the moment, the webapp image is normally made up of two directories and three files: The image-htdocs directory holds a copy of all of the files that need to be installed under the webserver’s document root. These are the PHP scripts, HTML files, image files, and so on. The files inside image-htdocs can be inside directories if required. Sometimes, web-based applications need to install files outside of the webserver’s document root directory. FUDforums comes to mind as a good example, if you’ve ever used that. The image-hostroot directory is

the place to put these files; they will be copied into /srv/www// later in the process. Again, directories as well as files can be placed inside the image-hostroot directory. We’re using the config-files plain text file to store a list of all of the web-based application’s configuration files. These files must be writeable by the user who owns the website; they need to be unique to each installed instance of the web-based application; and they need to be protected during application upgrades. All files listed in the config-files file are relative to the image-htdocs directory; I’m sure we’ll soon need to expand this to support files in the image-hostroot directory too. After a lot of discussion, we decided that most of the installed files should be owned by root, rather than the webserver’s user or the user who owns the website. I’m not sure how that’s going to work out in practice – it’s not something I’ve seen done a lot myself. Some webbased applications write to their own files – and directories – and these need to be owned by the user that the web server runs as. We’re using the server-owned-files plain-text file to maintain a list of these files and directories. One file that we’re not yet creating – but will at some point – will be called run-by-cgi-bin. It’ll contain a list of the scripts that need to be executed by a script engine, such as PHP/CGI, in case we need to add a #!/usr/bin/php-cgi to the top of these files. I’m sure that the details will change as we roll this out and produce install scripts for the many and varied web-based applications out there, but the idea’s going to remain largely intact. The webapp image is an inter-

Figure 2: An example install image under /usr/share/webapps.

December 2003

●

PHP Architect

●

www.phparch.com

12

FEATURE


mediate install. It’s a master copy of an application; a suitable format to allow our users to install as many local copies of the application as they need. Creating A Local Instance An application installed as a webapp image cannot be executed as-is. A local instance of the application needs to be installed under a document root directory. I guess if I was to think of it like PHP objects, I’d say that our webapp image is a class, and each local instance is an object instantiated from the class; or rather from the webapp image. To perform this second stage of the install process, we’ve designed (and are currently implementing) a tool which we’re calling webapp-config. Regular Gentoo users will know that we have a growing collection of -config tools for managing applications once they have been installed through Portage. webapp-config’s job is to create, upgrade, or remove a local instance of a web-based application. For the moment, to try and ensure as much compatibility as possible with as many web servers as possible, I’m using a simple approach to creating the local instance. Basically, all of the directories under the image-hostroot and image-htdocs directories will be created where the user specifies, and all of the files that don’t need to be unique will just be symlink’ed in. Any files listed in config-files and server-owned-files will be copied in for now, and the necessary permissions set. One of my favorite features about Portage is that it protects your configuration files when you upgrade any installed application, and invites you to merge the old and new files by comparing a diff between the two. Our webapp-config tool is going to have to do the same for the config files in each local instance of a webbased application. The job of removing a local instance at the moment (he says, having not written the code yet) looks very easy. It should be a total no-brainer for webapp-config to just delete all of the files and directories that were installed under the local instance. Building On The Foundations: Where We Are Today As I’m writing this article, we’re making good progress on delivering everything I’ve described so far. Thanks to the excellent work of Troy Dack, we’ve documented the solution as Gentoo GLEP #11, which has been approved by the Gentoo Linux project leaders. We’ve made the changes necessary to the default Apache config file that we install, which are now out in the wild. I’m currently implementing the webapp-config tool, and all being well a beta version will have been released by the time you read this. Robin Johnson – the lead PHP maintainer for Gentoo Linux – is working on a vhost-config tool, to help administrators manage December 2003

●

PHP Architect

●

www.phparch.com

their virtual hosts. Once we have a working beta of the webapp-config tool out in the wild, we then have the long and somewhat laborious job of converting all of our existing installation scripts for web-based applications to support our new approach. We also have a steadily growing backlog of new submissions – new installation scripts – which will also need converting. In all honesty, it’ll probably take us a few months to get everything working smoothly; and then we’ll be able to look at a problem that so far we’ve deliberately avoided facing in our first cut of the webapp-config tool. Problems Left To Solve Many web-based applications require a database of some description, normally stored inside the excellent MySQL database server. These applications normally ship a database schema, which can be run through phpMyAdmin or the mysql command-line tool. In the past, administrators have been required to perform this step by hand; and, for the moment, they’re going to have to continue to do so. In the back of my mind, I’ve a vague idea about forcing a standard naming scheme for the databases that web-based applications require, so that we can automate creating and updating databases. Hopefully, we’ll be able to develop that idea for Gentoo, and be able to give our users a truly one-command install solution for web-based applications. Because, if we can get to that stage, an exciting possibility opens up.

Taking It To The Next Level At the moment, on most servers shared by multiple users with their own websites, only the system administrator can install, upgrade, or remove web-based applications. Why? Because many of the more useful applications either need to have their files owned by the user that the web server runs as, or needs to have directories that the web server can write to. This can generate a lot of work for these administrators – a lot of work that it would be great if we could reduce. The system administrator should be able to make a pool of “approved” applications available, and then the users should be able to perform their own installs, upgrades and removals. Although I haven’t worked out the details, it should be possible to put together a simple PHP-based website that will allow users to do just that. By making it a website, we can run the webapp-config installer as the same user that the webserver runs as – making it easy to sort out the right permissions on files. Heck – we should be able to throw in an online config editor tool, providing an easy-to-use interface that also automatically versions the config files in case users need to undo their changes.

13

FEATURE


My ideal is that it should be as easy for anyone – and I do mean anyone – to install a web-based application as it is to, install say, OpenOffice. What we’re doing for the Gentoo Linux project should go a long way towards that goal. Sharing The Benefits I say that we’re doing this for Gentoo Linux, but the truth is that there’s no reason at all why other Linux distributions couldn’t share the benefits. The only part of this scheme that is Gentoo-specific is our Portage code that creates the master copy of the web-based application in /usr/share/webapps. What Portage does for us, rpm does for RedHat/Fedora and Mandrake, and apt-get does for Debian. I can’t think of a single reason why an RPM package – or a Debian package – couldn’t install the required files into /usr/share/webapps. We have a social contract on the Gentoo Linux project, and it guarantees that others can share our work. The webapp-config tool is licensed under the GNU General Public License. Other Linux distributions are free to incorporate it into their own releases. And, because the GPL requires them to make their improvements available too, we will also benefit if our approach

is adopted more widely. But perhaps what I like most is that it’s not just webbased applications written in PHP that will be easier to install on Gentoo Linux. The application could be written in Perl, Python, Ruby, Java, C, or any other language that will run under a web server; our solution can support them all. And that can’t be a bad thing at all.

About the Author

?>

Stuart Herbert has designed and implemented solutions for major companies such as Eurostar, Vodafone, and Hewlett-Packard, and has been the lead maintainer of the Generic NQS project since 1994. A former Systems Manager with Orange UK, Stuart now works for Box UK, developers of the Amaxus XML Content Management System. You can reach Stuart via [email protected].

Click HERE To Discuss This Article http://forums.phparch.com/110

FavorHosting.com offers reliable and cost effective web hosting... SETUP FEES WAIVED AND FIRST 30 DAYS FREE! So if you're worried about an unreliable hosting provider who won't be around in another month, or available to answer your PHP specific support questions. Contact us and we'll switch your information and servers to one of our reliable hosting facilities and you'll enjoy no installation fees plus your first month of service is free!* - Strong support team - Focused on developer needs - Full Managed Backup Services Included Our support team consists of knowledgable and experienced professionals who understand the requirements of installing and supporting PHP based applications. Please visit http://www.favorhosting.com/phpa/ call 1-866-4FAVOR1 now for information.

December 2003

●

PHP Architect

●

www.phparch.com

14


F E A T U R E

by Javier Szyszlican

I

am the creator and main developer of JFFNMS, an Open Source Network Management/Monitoring System written in PHP and licensed under the GNU GPL. This article will describe what JFFNMS is, how I got inspired to create a Network Management System (NMS), the challenges I faced in doing it, what it can do now, and what we have planned for the future. In addition, I’ve included some neat hacks toward the end that even advanced users of JFFNMS might not have stumbled across. I hope you will find it interesting. What is JFFNMS? JFFNMS stands for “Just For Fun Network Management System”. The name comes from the Linus Torvalds Autobiography (“Just For Fun”), and from the reason I took on the project - I did it Just For Fun. This program can be used to monitor any device on a network. You don’t need to have a big network to use a NMS, because it’s always useful to be notified when something strange happens. It should be noted that when I say “monitor”, I’m referring to the act of trying to connect to a port, and retrieving the current utilization of an ethernet card, the CPU load, or status of a process on that host. Anything can be monitored (polled) if a plugin is written for that purpose. It works on any operating system where PHP is installed, including any Unix, GNU/Linux, and Windows 2000/XP. Most users are installing it on GNU/Linux, though there are some installations on Windows, generally when the user doesn’t have another choice. JFFNMS can use either MySQL or PostgreSQL for its

December 2003

●

PHP Architect

●

www.phparch.com

backend data storage, so if you have either of these, you’re ready to go! If you don’t, they’re both free downloads, so you won’t have to buy one. Most of the parts that make up JFFNMS are modular. The ones that are not are being modified to be modular (like the authentication and profile system). This will make it easier to troubleshoot, and hopefully easier for other developers to extend or integrate the system (or any of its modular parts). The JFFNMS site is located at www.jffnms.org. From there you can access the “jffnms-users” mailing list, the Downloads section (Stable and Development versions are available), a list of some of the features, and a forum. Most of these services are provided thanks to Sourceforge.net. Screenshots! For the restless or impatient, I’ve taken the liberty of providing a few screenshots right in the beginning to provide a glimpse of what JFFNMS looks like, and a small sampling of the information it provides: Figure 1 is an example of one of the JFFNMS main views. You can see the hosts, represented by the boxes in

REQUIREMENTS PHP: 4.x OS: Any Applications: N/A Code: http://code.phparch.com/18/1 Code Directory: jffnms

15

FEATURE


the upper panel. The boxes can turn red or some other color if any of its internal interfaces (TCP ports, proceses, network cards, etc) has a problem. The box also displays the hostname, zone, a total of the interface alarms, and the IP address. This is the default view. A text view (no HTML) also exists, as shown in Figure 6. In the bottom pane you can see a list of the latest events on the network. The event viewer allows filtering and exporting to CSV (Comma Separated Values). Figure 2 lets you see what’s inside of (in this case) a Linux host. Each box in the leftmost column represents an interface – either a TCP port, a physical interface, a storage or memory device, a CPU or an application. At the bottom you will see the events which are specific for that host, like an SLA telling you that the ‘Real Memory’ usage is more than 80% of its full capacity. Figure 3 shows the setup screen. You will only need to access it when you are doing the first install or want to change system-wide options. Most values will be autoconfigured and will alert you to any problems in the configuration. Figure 8 shows some GNU/Linux interface graphs. Memory usage, load average and TCP connection status graphs are shown here. The graphs include a legend

explaining and showing the absolute values. To select an interface just use the “Interface Selector” under the “Performance” menu. Goals JFFNMS aims to be a complete NMS for ISPs and private networks, providing all of the tools and information any NOC employee or network manager will need to gather and respond to data about their network. Easy to use menus and screens show your network at a glance. There’s a complete view of everything that is going on; users logging in and out of routers and issuing commands, interfaces (representing applications, TCP ports, customer links, etc.) going up or down, and threshold alerts to warn you about future problems. Even your customers can use JFFNMS to see their traffic usage reports. It can also serve a sort of network accountant, who can see any changes to the network, which are stored for easy discovery of configuration problems. Inspiration I started working at my current job as a Network Operation Center (NOC) Operator in the Buenos Aires

Figure 1

December 2003

●

PHP Architect

●

www.phparch.com

16

FEATURE


Internation Teleport (TIBA) in Argentina in September 2001. One of my first duties was to install HP OpenView (HP’s large, expensive, commercial NMS) on a Sun/Solaris computer to replace their current monitoring systems. They were using IPSwitch’s What’s Up Gold, MRTG and a custom syslog reciever. All of these tools had to be configured separately - meaning, of course, that there was no centralized administration or configuration tool. Another shortcoming was the complexity involved in the integration and addition of new features like TACACS+ authentication, syslog integration, ping from the router to the customer, alerts, etc. When I started installing HP OpenView I didn’t like how it was organized, and the configuration involved in order to take advantage of its features (like alerts and adding new OIDs to poll) was very complex. The only good parts were its network discovery (the best one I have found), and syslog reciever features. Then I tried looking for another NMS and found OpenNMS, but it was way too slow and I couldn’t find a way to make it work the way we wanted. That together with my incipient urge to do it myself took away any motivation to try too hard to get what I wanted from

the tool. The only other PHP/SNMP application available at the time was CACTI, an RRDTool front-end, with minimal SNMP interface discovery features. It’s really more like MRTG ported to PHP with a nice configuration interface and an RRDTool backend. We wanted a more full-fledged NMS, integrating syslog message parsing and analysis, TACACS+ accounting and authentication, SNMP polling, and discovery of what services and resources a host (Server/Router) had to offer. In addition, we really needed automatic SLA verification based on the gathered data, interface grouping, and graphics aggregation (shown in Figure 7), etc. So, I told myself “you can do it better”, and started this journey using the UNIX mindset of having small, simple tools doing their respective jobs. I started out using msyslog for receiving syslog messages and storing them in a MySQL database, and tac_plus_v9, doing TACACS+ authentication and accounting using the same database for its storage. The main application at the time featured two event lists; one showing syslog messages and the other showing TACACS+ accounting. The event processing was done when the screen was reloaded. It was a client-side script with no backend code. Work continued.

Figure 2

December 2003

●

PHP Architect

●

www.phparch.com

17

FEATURE


I started JFFNMS in January of 2002, and the first public release, version 0.5 was released in February (this release is still available on SourceForge if you want to see how we have progressed). At that time we had most of the features described earlier along with SNMP interface discovery, TFTP host configuration download, and a few other features. Unfortunately, everything at that time was hard-coded and non-modular. Challenges As the releases went by (there have been 24 public releases so far, the most recent being 0.7.3), one of the most difficult tasks was coaxing JFFNMS to run flawlessly on various PHP versions (and configurations), operating systems (and their respective versions) and with various related utilities (RRDTool, UCD/NET-SNMP, etc) - all using the same codebase. Getting this to happen in a way that doesn’t cause users to become suicidal necessitates the creation of a release script. Whenever you’re working with a multi-platform target release, one big challenge is getting your release script right. A release script is a makefile or simple shell script which handles the project release procedure (which files will go into the tarball or zip file) and helps

the project manager in automating tasks (database cleanup, and dumping, converting). The one I coded for JFFNMS handles the creation of the code patches (doing a diff from the earlier version) for upgrades. It also dumps the earlier version’s database schema and data and compares them to the current ones, resulting in the required SQL queries to do a database data upgrade. This provides a great benefit to the users, since they don’t need to dump their old database and then do text merges and import again. Just execute these files and the database will be upgraded doing normal SQL commands (for MySQL and PostgreSQL). This script also helps me not to forget anything when doing a release version, and allows us to create nightly development versions without having to do it manually. Nonetheless, getting this script to run flawlessly given all of the variables in the equation is a non-trivial task, to say the least. Crossplatform Support Some issues arise when you try to support Unix and Windows hosts within the same codebase. • Path Handling: you have to be aware of file-

Figure 3

December 2003

●

PHP Architect

●

www.phparch.com

18

FEATURE


naming restrictions. • Forking: Using a combination of ‘popen ( )’ and ‘start.exe’ we can launch another process in parallel (this is used for polling and autodiscovery) • Scheduled Tasks: On Unix you will normally use cron to do this job and launch your proceses in the background, on Windows we ended up using the ‘Scheduled Tasks’ Service because no GPL or free program exists to do this job. The major drawback of using this service is that programs have to be wrapped in .BAT files to allow output redirection (to NULL), and even with that you cannot hide the program command line windows from appearing in your taskbar unless you run them as another user. Interface Tracking This is really an SNMP issue, but no other open source NMS addressed it. All interfaces defined with the IF-MIB are indexed

with a number, the ifIndex. This number identifies the interface according to the host until the next reload. So when the router or server is restarted, some ifIndexes could change (mostly virtual interfaces like tunnels, loopbacks, frame relay, ATM, multilink, etc). JFFNMS keeps track of these changes using either the interface IP address or the interface name (or alias). So when something changes, a poller/backend duo handles it and updates the database. Net-SNMP Issues The current PHP-SNMP extension has a problem with the translation of Human readable OID’s (ie. Interfaces.ifTable.ifIndex) to the numeric form used inside the SNMP packets. Our solution was to modify all of the code to use the numeric from directly, this way the requests are faster because the libraries don’t have to lookup the names using the MIBs, and you don’t need to have the MIBs loaded at all. A drawback here is that if something changes in the base numbering of a MIB we will have to change the code. But if anything changes the vendor will likely not only change the base numbering, they will also have made some changes to the format and inner workings

Figure 4

December 2003

●

PHP Architect

●

www.phparch.com

19

FEATURE


of the MIB, and we will have to do some changes regardless. Design Fundamentals: GUI/API Separation JFFNMS has 2 very distingished parts: the GUI (in the htdocs/ folder) containing the user interface, and the Engine (in the engine/ folder) which contains the API and all of the backend daemons and modules. Both parts share common libraries (in the lib/ folder), but this will be separted in the future. The GUI only communicates with the Engine through an object (PHP Class). It doesn’t call database functions or other filesystems directly. This means that most functions used to get the data for the GUI are in the API. This together with a SOAP/WDDX RPC (called Satellite) allows the recreation of the GUI in another language, possibly even running on another computer. It doesn’t have to be a complete GUI, mind you. You can use this “interface” (RPC) to integrate JFFNMS into your current systems. For example, if you integrate JFFNMS into your CRM, the HelpDesk staff can be sure of the customer’s link states when he/she calls.

Modular Approach The Engine code consists of 4 main systems: • Poller: Runs the Modular Polling System every 5 minutes. The polling system generates a “poller plan”, using information like the interface type and the poller group (an ordered list of poller and backend combinations). This plan tells the application what to poll and where to store the poll results for a host’s interfaces. It executes one instance (fork) of itself for each host (when called without parameters), which allows a parallel poll of all hosts, speeding up the polling process. • Autodiscovery: Runs the discovery scripts against the hosts every half hour. Like the poller, this system runs itself against each host in parallel. It executes each discovery script (one for each interface type) against the host IP for each SNMP community on that host. The results are then compared with the stored interface data. Based on the

Figure 5

December 2003

●

PHP Architect

●

www.phparch.com

20

FEATURE


host’s autodiscovery policy it can automatically add, modify or delete an interface to match the discovered data. • RRDAnalyzer: Verifies SLA conformance every 30 minutes. Uses the RRDTool ‘fetch’ function to get all polled data for each interface from the last 30 minutes (this is generally about 6 or 7 measurements).It calculates the average of each measurement and uses those values to replace the placeholders in the SLA expresions. Then, using a simple RPN (Reverse Polish Notation, think HP Calculators) engine, it analyzes the expresions to determine if they are true or not. If the SLA returns true, an event is generated to alert the users of a possible problem (ie. interface error rate is higher than 10%, or memory utilization is above 80%). • TFTP Configuration: This process downloads the router configuration file (only Cisco’s for now) every day via TFTP and then stores it in the database. JFFNMS allows you

to view the differences between one day’s configuration and another, using GNU/diff. This is useful for analyzing the changes to the router configuration. • Consolidate: Parses all the raw data items (syslog, tacacs, snmp traps) into events (host bound messages with fixed fields) based on the type of events, and the configured parsers. Then the events are processed to check if an alarm should be generated. It also handles most of the triggers since it creates most of the events and alarms. Each system has its own plugins and modules, which are declared and interconnected using the database tables and configured via the GUI administration screens. So really, the database is the “glue” between all of the small modules, their configuration and the relation with their parents. These systems are called from the operating system task scheduler (cron in GNU/Linux) like a shell script (using the command line PHP parser), this allows the systems to run in the background without user

Listing 1 1

December 2003

●

PHP Architect

●

www.phparch.com

21

FEATURE


intervention. Listing 1 shows the TCP Port Discovery Plugin for the Autodiscovery System. This disocovery script uses NMAP (Network Mapper from www.nmap.org) to do a port scan of a host and discover which TCP ports are open. Then it returns a list of interfaces detailing each TCP port in a format the autodiscovery engine understands. RRDTool usage We use RRDTool to store the data we gather from the hosts. It stores numbers in a time-series round robin database (RRD, which means the file will not be bigger than when it’s created) and allows graphing (Figure 7) and fetching of the stored data. When I started writing the RRDTool backend for JFFNMS, a PHP extension existed to bind the RRDTool libraries to PHP functions, later it became unmaintained, and caused errors when trying to compile it against a new PHP version. Also, a Windows DLL didn’t exist, and most users were having problems compiling their own PHP. The solution I took was to create a wrapper for the RRDTool extension functions that, if the extension was not pressent,

would call the RRDTool binary and return its output. This way we could use RRDTool in any operating system without the need for an RRDTool extension - but if the extension was present it can use that. If the RRDTool extension starts being maintained again and/or distributed with PHP, JFFNMS can take advantage of the performance gains the extension approach provides (you don’t have to call the shell and waste CPU/OS context-swiches). PHP Usage: JFFNMS is currently using the following PHP extensions and libraries: • SNMP: Most of our pollers and discovery scripts use it to gather data from the SNMP agent on the remote host. • PCRE: Used by the Syslog message analyzer to match a message against a list of known patterns. Other tools use it as a ‘search and replace’ tool. • Sockets: Used to test the state of a TCP port and gather the first line of text it sends. This happens inside the TCP port poller.

Figure 6

December 2003

●

PHP Architect

●

www.phparch.com

22

FEATURE


• GD: Used in the GUI for map and performance graph generation. • WDDX: Our RPC system can send its information in this format. Useful when interoperating with PERL. • PEAR::SOAP: Our RPC system can use this extension to communicate with other Satellites. • MySQL and PgSQL: Of course, for backend database comunication, all SQL queries are written for MySQL, and our Database abstraction framework handles the translation to PgSQL. Also, we plan to use: • SHMop: in the daemonized poller, this extension will be used for communication between the poller child processes. • PCNTL: Will handle the forking in the daemonized poller. Future We have a lot of features waiting in our “TODO” file.

Some very specific and some very broad and useful. You are welcome to help us achieve our remaining goals and features. The upcoming releases will focus on: • GUI redesign: I plan to use templates to draw most of the GUI (currently this is done with PHP functions returning HTML tags), and PHP code to fill the dynamic parts only. This way it will be easier for a designer to change the look and feel of JFFNMS without having to deal with the GUI code. • Daemonized Poller: One of out most active contributors (Anders Karlsson) is working in a poller that will have N number of children and distribute the polling work among them. The current poller spawns a number of instanses of itself equal to the number of hosts to poll, causing it to become a resource hog when you have a lot of hosts. The child processes are being created using the ‘pcntl’ extension, and comunication is via SHM (Shared Memory) with the ‘shmop’ functions.

Figure 7

December 2003

●

PHP Architect

●

www.phparch.com

23

FEATURE


• Host Autodiscovery: The ability to do a network wide scan (probably using NMAP), remove duplicates, and add the resulting hosts to the system to permit invidual interface discovery on them. This feature will allow faster JFFNMS configuration in big networks. Currently each host has to be added manually. • Modular RRD Analyzer: The current analyzer only executes the SLA verification. We will try to separate the RRDTool data fetching from the SLA analysis so that we can have more modules working with the data. This will allow for example a Top Ten list of interfaces having the most traffic, obtaining the bandwidth the interface consumed in a month, calculation of the 95th percentile, etc. • SNMP Version 2 and 3 Support: This is a complex one, because this should be an option in the PHP-SNMP extension. Currently, this is a hard-coded constant. In a

common production network scenario you generally have devices supporting only SNMPv1 or SNMPv2 and you need to communicate with both within the same script. One solution might be to create a wrapper for the SNMP functions allowing the call of the command line utilities and processing their output. Tips & Tricks For those users who have already ‘been there, done that’, I thought I’d include a few useful tricks that might uncover some functionality in JFFNMS you didn’t know about. If you’re just starting out with JFFNMS, keep these handy, and consider yourself one step ahead in your implementation. • Customer Login: When you create a new customer you can assign a username and password to it. Then, when you add a new interface you can bind it to the customer by selecting it in the specified field. Using the provided username and password, your customer will be able to login to JFFNMS and

Figure 8

December 2003

●

PHP Architect

●

www.phparch.com

24

FEATURE


see only the graphs for his interfaces. He will be seeing a limited JFFNMS view. This could be a value added service for your end users. • Limits: Suppose that you have a NOC employee that is only responsible for a couple of links, routers or services. Maybe you also have a big customer to keep happy. you want him to be able to look at all of the JFFNMS features (Events, Graphs, Reports, etc) but only for selected interfaces. You can accomplish this by creating a new a new map and adding any interfaces you want to it. Don’t forget the Map ID (its the first field)! Then go to the User Profile and add the “Map” Profile Option, put the Map ID as the value. When the user logs in, he will be limited only to the selected interfaces. • Active TCP Connections: If you use JFFNMS to monitor TCP ports you normally don’t install an SNMP daemon in the monitored server. But if you install it, the TCP port interface type includes a poller which checks the host TCP connections table via SNMP (like if you do a netstat -na on the server) and counts how many established connections this port has. This is useful when you want to know how many active connections per port you have on your server. For example, how many established connections is your database or web server currently handling? Also if you want to know the number of inbound, outbound and established connections on a per host basis, for the complete host, you can use the “TCP Connection Status” graph when you select the host CPU Interface in the “Performance” menu. • Graphical Performance Maps: You can create a map of interfaces and then modify the positions of every interface for that map (this is shown in Figure 4). To edit the “links” between the interfaces select the “Edit” graph button and double-click one interface and then the other. You can also see the default graph associated to the interfaces directly in the interface status view (check out Figure 5). Select “Interfaces & Events” or “Maps”, then change the View Type (under Options) to “Performance”.

Glossary MRTG: Multi Router Traffic Grapher (http://www.mrtg.org), the pionner of SNMP data graphing. Writeen by Tobias Oeticker. RRDTool: Round Robin Database Tool (http://www.rrdtool.org) created by the author of MRTG to separate data storage from presentation. RPC: Remote Procedure Call. A system used to call a function from a remote computer and get a response. SLA: Service Level Agreement, a series of parameters used to identify if the current level of service complies with a standard or a signed customer contract. TACACS+: Terminal Access Controller Access Control System (RFC 1492), is used as an authentication framework from devices (Routers or Servers) to check login information against a central server. Syslog: RFC 3164, a service to send logs from one device to another on a UDP port. SNMP: Simple Network Management Protocol (RFC 1157), an SNMP client comunicates with an SNMP agent by querying the remote agent for values stored by the agent. The available values are generally viewable by doing a ‘walk’ on the device or reading the different MIBs the device uses. There are standard MIB’s (information trees) defined, but most vendors implement their own inside the enterprises tree. SOAP: Simple Object Access Protocol, allows RPC calls from one program to another using an XMLover-HTTP approach. WDDX: is an XML-based data enconding/encapsulation technology useful for exchanging complex data structures between different programming languages, like PHP and PERL. TFTP: Trivial File Transfer Protocol, a simple FTPover-UDP implementation with no user authentication.

Support I do most of the support on the “jffnms-users” mailing list, and some users and contributors help with specific topics like Debian or Windows installations. December 2003

●

PHP Architect

●

www.phparch.com

25

FEATURE


Also, when some company needs specialized support or installation help, they come back to me, and let me access their servers and routers to help their staff get 100% utilization of the JFFNMS features. Other services available are the customization of some parts of the code, and the coding of new features or plugins for a specific purpose. It’s always better for the users to go directly to the programmer who wrote the code, because he knows exactly were to look and how things work. Contributions: We are always open to suggestions and contributions. You don’t have to be the best coder in the world, you only need innovative ideas and a need for a solution. Some people are better coders and can contribute with a patch, adding a needed feature or fixing a bug. Others have more vision or ideas and can help us choose the best path. Another important point is that we need people with writing skills to help Craig Small and myself with the documentation. I think this is the most needed contribution right now. It will be nice when we finally have a simple User’s Guide on how to accomplish normal administrative tasks in JFFNMS.

December 2003

●

PHP Architect

●

www.phparch.com

I’ve even received some Gifts from the Amazon Wishlist, which is linked from the JFFNMS site (Thanks to Brian, Daryl & Chris). If you don’t feel you can contribute in any other way, but want to show your appreciation, feel free to check out the wishlist! Thanks: I would like to use this opportunity to thank all of the JFFNMS users and contributors for their support; my employer for allowing me to create this software; Tobias Oeticker for RRDTool; the PHP Developers for this great programming language; and Brian Jones for inviting me to write my very first big article.

About the Author

?>

Javier Szyszlican is NOC Techinician and Developer at TIBA (http://www.tiba.com). He lives in Buenos Aires, Argentina with his girlfriend Analia and their 2 cats, Olivia and Calista. If you want to reach him, send an email to [email protected].


26

Can’t stop thinking about PHP? Write for us! Visit us at http://www.phparch.com/writeforus.php

Beyond the Nukes: John Cox on PHP-based CMS, and Xaraya

F E A T U R E

by John Cox There is a lot of hype surrounding PHP-based content management solutions. However, most developers who have deployed one know that what lies under the covers can be somewhat distressing. In this article, John Cox explains some of the shortfalls of the current collection of available PHP-based CMSes, even going so far as to (gasp!) take responsibility for some of them! Also included is a description of his new project, 'Xaraya', which aims to right some of these wrongs and be 'a better mousetrap'. Introduction It has been a while since I began doing web development. I started about seven years ago to build a website to keep the family informed about my first daughter’s birth. From there I began to look at the web as a hobby, and then a passion. Initially I was drawn to design, as it seemed to be a very good outlet for my creativity, but I later fell in love with programming. Some prefer to do fix cars, some prefer to paint, I enjoy programming. I enjoy building a better mousetrap. My quest to build a better mousetrap (by way of website) has been a journey into content management. I have seen the good, the bad, and the downright ugly. Content management is an art form in the right hands, but it can be a nightmare to execute properly. Building a content management system is more than putting together code snippets to generate a site. In its simplest form, it’s a matter of designing an infrastructure that interconnects systems together to provide a cohesive, easy-to-use system not only for end users, but for administrators as well. What novice PHP developers do to learn PHP consists largely of downloading and hacking existing scripts. Popular CMS packages are one of the primary targets for people learning PHP as these systems tend to illustrate many concepts in one package. I learned PHP after PERL hacking by downloading PHP-Nuke. Unfortunately, I have been trying to rid myself of bad habits ever since. At the time, PHP-Nuke held no infrastructure to speak of and was a misery of security holes and bad assumptions. In some respects, I would imagine that it still is, as I know several XSS have not been December 2003

●

PHP Architect

●

www.phparch.com

shorn up. It should be noted, though, that PHP-Nuke was itself a way for its creator to learn PHP. I was able to sense (due to my prior experience coding in PERL) that PHP-Nuke was not designed well. This was one of the primary reasons that PostNuke started. We (Sean Finkle, Greg Allan, Harry Zink and myself) wanted to design a system that had the community elements of PHP-Nuke but had a more logical design for reusing components. PostNuke was a great start for accomplishing those ideals, but eventually tradeoffs between backward compatibility and the rewards of a completely rewritten system came into play. Partially as a result of these tradeoffs, PostNuke suffers from some of the same problems as PHP-Nuke. There is an apparent lack of willingness to depart from the current ‘kitchen sink’ mentality, so you wind up throwing mish mash together, and if it sticks, it sticks. Before I, and the majority of the PostNuke development team broke from PostNuke and began Xaraya, we had a foundation set to break these paradigms. With Xaraya, we have come full circle with a completely rewritten system, with the core architecture designed to foster the system’s growth.

REQUIREMENTS PHP: 4.3+ OS: N/A Extensions: N/A Code: http://code.phparch.com/18/2 Code Directory: nukes

28

FEATURE


Breaking the paradigms of the Nukes There are a few reasons that the Nukes are so popular. First and foremost there is a very low cost of entry. I don’t mean cost in the sense of dollars, but rather the time investment to learn and extend the system. I had little to no PHP knowledge when I started playing with PHP-Nuke, and yet within a day I was able to understand how to make a theme. I could, without much work at all, make my website look close to how I wanted with the editing of just a few files. This low cost of entry is, in my opinion, the strength of the Nukes. A marginal developer (a category in which I place myself, by the way) can look like a genius by understanding the rules of modification. Does this mean the developer is a genius? No. But all newbie coders like to feel like one, so they submit their hacked code, which gets downloaded and used, people praise the hacked code (possibly not knowing any better themselves) which makes the ‘developer’ feel like a genius, and the cycle continues. This is not a bad thing in and of itself. Systems should be easy to understand and work with. However, when you are adding crap to crap, you just end up with a larger pile. How many hacked up scrolling news blocks (rendered useless on the next upgrade) do you need? Unfortunately, a system built without the forethought of design coupled with a low cost of entry fosters this kind of ‘block mill’ behavior. Another paradigm that needs to be broken is that of data and code redundancy. It is very easy to add a new module in the Nuke systems that just renders content a different way. Reviews, FAQs, News, Journals, Blogs you name it and there is a module for it. Each of these modules has a separate data storage table, and each more than likely has a separate system for commenting on the content, rating the content, or whatever else we can imagine to the content. I seem to remember the Downloads and Links systems were identical in design – only the function names were different, and each had at least six tables for storage! What’s the sense in that? All you’re doing is creating more overhead to store the same type of data, and cutting and pasting functions, unnecessarily creating more code. This is an example of poor design. I am responsible for that on the PostNuke side, so before I get flooded with email calling me every name in the book, let me say that I hold myself responsible for the PostNuke design. Of course the current code base of PostNuke is nearly a year and half old, and it is still pretty popular, so I’m relieved to see that the world is not ending over it. Finally, the control over the output is deplorable with the Nuke systems. Yes, there is CSS over a good portion of the scripts, but that only goes so far. When was the last time you visited a web portal made by a Nuke system and didn’t recognize it off the bat? It is not because of decisions surrounding templating, not templating, or the templating system that is used. It is December 2003

●

PHP Architect

●

www.phparch.com

because of the inflexible design constraints that are built into the systems. A lack of control over the output means a lack of control over your website and your code. It does you no good, and as a developer, it does me no good as I might have to answer to the web gods one day. I was once told by a manager at work that the executives of my company stay up at night thinking about ways to fix the company and stay ahead of the competition. I stay awake at night thinking about these problems with content management and how we are going to change the way people think about both content management, and PHP as the platform to build systems on. It doesn’t take too many bad eggs to shy major corporations away from PHP as a development platform. We as a community lose innovation when companies and individuals move from one language to another. Innovation is what makes the web go ‘round, and it is also why PHP developers, whether hobbyist or professional, are drawn to the language. Xaraya: changing the way we think about content management I have spent a great deal of time pointing out the problems with Nuke systems. I would also say that these are universal problems in one way or another. Drupal has its problems as good a system as it is; Geeklog isn’t perfect as evidenced by the entries in Bug Traq; Typo3 is a very good system but it tackles problems in a very different fashion than some are looking for; and ezPublish has a very high cost of entry. Let me start by saying Xaraya ain’t nirvana either. It is an immature product with a smaller user base than other content management systems. Xaraya has great potential though. Looking back at the cost of entry of the Nuke systems and the problems that plague those communities, Xaraya has a comparably low cost of entry, which could make it vulnerable to the same issues as the Nukes. However, unlike the other systems, it takes work to write bad code for Xaraya. You can compare an example by looking at Listing 1 (PostNuke) and Listing 2 (Xaraya) on the next page. To be fair, I chose an example of code that has not been converted to the PostNuke API. I did this because it is a fair example of code that will run in both Nuke systems. This code would not run on Xaraya at all. These two functions both “DELETE” something out of the system. They are both deleting Ephemeris, but now let’s take a deeper look. In the first example we have absolutely no separation between design, content, presentation, and logic. It is all there. We are echoing statements, we are not returning, and to top it all off, we’re doing SQL statements right in there as well. No separation of logic at all. With the Xaraya model, we are separating these various responsibilities of the system. With the Xaraya API we are doing a lot in terms of functionality without many lines of code. We are also

29

FEATURE


reusing as much as we possibly can by leaning on other modules’ APIs and hooks (more on those later) throughout the system. In the code sample we are evaluating whether or not you have the correct privilege set, then we are looking for the confirmation variable to be set. If it has not been set, then we are returning an array to the template system. If it has been set, then we are looking to make sure that an auth variable is there for preventing XSS attacks, and then sending the appropriate string to be deleted by the module’s API function. The workflow within Xaraya is really quite simple. Something happens, whether someone clicks on something to go somewhere, or a module calls a function from somewhere else. This causes the logic to direct the traffic. Something is probably going to happen at the presentation layer, so the backend logic will look to send an array to the template system. Another event might cause something to be processed in the API (whether it’s a query, expression, etc.). In some cases, both presentation and processing is done, as in the code sample. Listing 1: PostNuke 1

December 2003

●

PHP Architect

●

www.phparch.com

It is a natural way to think about the problem at hand. It is also a natural way to think about just about anything. It is a work flow. Something happens and that something causes a decision point. That decision point does something. You see a car you like. You decide to either: • look at the car and not buy it • you look at the car and you start trying to find financing It is the natural order, and Xaraya just illustrates it. It allows you to develop quickly and efficiently without trying to learn a whole new development paradigm. As mentioned before, another weakness of the Nuke systems is the lack of cooperation among subsystems. You could well have separate modules that basically do the exact same thing, but call it something different. I mentioned the Web Links and Downloads which are just a cut and paste of one another. In Xaraya, we tackle this differently. For content, we have the articles module which has been written by Michel Dalle. From the sound of the name you would think that it just handles news or articles. Instead it handles content at a generic level. Instead of having separate content modules performing essentially the same actions on essentially the same Listing 2: Xaraya 1

30

FEATURE


type of data as in the Nuke systems, the articles module in Xaraya would more than likely be able to handle these things by itself. The underlying system allows you to define publication types. These publication types, in conjunction with the template system, allow you to create new publications by merely defining the input. To go a step further, we have built into the system what is called “Dynamic Data”. What Dynamic Data allows you to do is extend the functionality of Xaraya to determine the input to the system as well. Need a PayPal button to appear in a shopping cart that is controlled as a publication type? That can easily be done via Dynamic Data. You can do e-commerce, groupware, web links, downloads, news, documents, you name it - all within the articles module. What’s more, you can export your publication types to XML and distribute them to other Xaraya installations. The cost of entry goes down even further with Xaraya, because to create new content types you merely need to have an imagination and a rudimentary knowledge of XHTML. This way, the cooperative aspect is covered. We are not creating new dependencies throughout the system, whereby a new content module you create would also need its very own ‘Comments’ module, its own database structure, etc. Instead you can rely on code and structure already provided by the underlying system. Building on these ideas, Xaraya does not have “Monster” modules as the other systems do. We instead try to develop small reusable items to speed development. For instance, we have a categories module developed originally by Jim McDonald and later by Flavio Botelho which allows categories to be used across your entire website. Instead of constantly reinventing code, we “hook” into the categories. Likewise we have a comments module, written by Carl Corliss, which allows comments to be attached to any content module. It speeds development for you, and it allows us to concentrate on the core. In some respects, what we have built is more of a generic application framework than a content management system as there is no steadfast rule that you have to run “news” on your website. I have mentioned hooks throughout. Let me spend a few minutes to explain what hooks mean to Xaraya. Hooks are simply the calling of other modules to do your dirty work. Hooks come in many different shapes and varieties, but they all fall into three categories:

change that match to our predetermined rule. It could be anything from autolinking specific words, to changing content, to ASCII art. • API Hooks do something when they are told. It could be as simple as sending a mail out when something is added to the system. It could be a cron event. It is a matter of processing on a certain condition. It doesn’t know why, it just does what it’s told. • GUI hooks are the third general type of hook. These hooks display something when told. They don’t really know where they are displaying, just that they are doing something. An example would be the comments system. It could be attached to an article, or a user. It doesn’t know, and it doesn’t care. It just attaches itself to an ID, and then spits out the result in the user interface. The cost of entry keeps going down. I am somewhat lazy in my development. If I can create something and continue to reuse it without having to cut and paste, and without having to constantly reinvent a storage schema for it, I am going to take that route. I believe that most developers feel the same way, but don’t have the necessary tools to allow this to work for them. Xaraya provides those tools. Another achievement and advantage over the Nuke systems is the templating system that we use. We use a home grown XSLT-based templating system which lowers the barriers to learning. We are all familiar with HTML or XHTML, and with the BlockLayout system of Xaraya, there is a certain home grown familiarity. We decided to go with the BlockLayout system over Smarty (which caused a great deal of outrage in my PostNuke days) because of the proliferation of XML on the web. XSLT gives us a chance to do more with the templates before processing with the natural XML characteristics than Smarty ever would. Regardless of the template system and how it works, let’s focus in on the true power behind Xaraya’s presentation layer. Everything can be overridden from what we call themes. Themes have their ideas back from the Nukes, but they are completely different in their execution. You can override any module output, any block output, any output whatsoever, on a theme by theme basis. It allows a designer to do what they do best, with the tools that they are comfortable with. {if condition=”foo eq bar”} I believe is Smarty syntax which for a designer looks foreign, but for Xaraya it is <xar:if condition=”foo eq bar”> which probably makes more

“It isn’t the presentation layer that makes an application, but rather the full package”

• Transform hooks take content that is ready to be displayed on the website and compare it against rules. Regular expressions are the norm for the transform hooks. We search the data looking for a specific match and then December 2003

●

PHP Architect

●

www.phparch.com

31

FEATURE


sense from a designer’s point of view. If I am comfortable with HTML tags, then I just have a few more to learn in order to unleash Xaraya. What’s more, I can override anything, anywhere. Whether it is in a module output, or the entire template on a page by page basis, it doesn’t matter. I have the control back that I had when designing static pages. The ability to have dynamic pages with the same abilities that I had as a designer with static pages is nirvana. It isn’t the presentation layer that makes an application, but rather the full package. Xaraya is breaking the preconceived notions of what content management should be. It isn’t there to give you the latest news in a scrollable block. It is there to handle the interaction between your content and the consumer. That is what it is about, and those are the ideas that we are pushing. We need to step back just a bit now that we have brought some issues and differences to light to explain exactly what I wanted when I set out on this quest to build a better mouse trap. I wanted a core that would do very little in the way of presenting content, but rather gave users the tools to allow that to happen well. Interaction between applications is what people are looking for when they begin to deploy a CMS. Folks generally look to content management because they integrate tools into one package, and allow for the extension of those tools. That is what Xaraya does, and it does so pretty well if I do say so myself. The core of Xaraya consists of: • An administration system which allows whoever has the proper privilege to edit, add, delete or moderate content. • A user system that allows you to handle (or not handle) registration and authentication of users. • A privilege system which allows you to block content or open content to certain roles within the system. • The dynamic data system which allows you to extend the functionality of any module based on your wants and needs. • Modules and themes system which provides an API for creating and interacting with extensions throughout the system. The API itself is documented in an example module as well as through inline comments with the phpdoc system. • An interface to the server for managing sessions and server variables to ensure that Xaraya runs well on different platforms. • An interface to database systems. We are using ADODB for our abstraction. If I have learned anything in my quest, it is that even with an abstraction system it’s often difficult to make all databases play nicely. • A logging and exception system to aid in December 2003

●

PHP Architect

●

www.phparch.com

debugging. • A variable system to allow easy setting and retrieval of variables based on instances. • An XML- or PHP-based string translation system which allows Xaraya to be translated into not only different languages, but different dialects. We could easily have separate US and UK translations, since my friends across the pond seem to think that I talk funny and slaughter their language. • An XML parsing system to allow modules and the core to parse XML in a single routine. • The BlockLayout Template system which controls the output of Xaraya. These are the basic core building blocks in Xaraya. This gives developers the tools to write applications without having to write the basics over and over again. The system is what I envisioned nearly three years ago when I first started playing with PHP-Nuke. Still a work in process Xaraya has flaws. They are not design flaws though. We are still in the Beta cycle and as such we are uncovering uses for Xaraya that we had not ever thought of. Like any good Beta cycle, we are getting feedback, but to be fair and in the interest of full disclosure, let me bring those flaws to light. With all of the interaction between the modules, we have run into performance and memory issues. We have been able to cut the memory usage in half since the first Beta, but we still have some room for improvement. Going forward, the performance can and will be improved. We will release a full cache mechanism before the launch of 1.0.0. This cache mechanism should be smart enough to predict and cache in order to serve static documents to any anonymous user. This means that we will be cutting the final problem of content management, the processing, out of the picture for 90% of the users that visit a website built with Xaraya. Not only do you have the luxuries of a dynamic site, with the design possibilities of a static site, but it will serve up like a static site as well! Another problem that we face is consistency of the user interface. With as many developers as we have working on Xaraya, one of the problems that any development community faces is consistency. In the code base it is not so much a problem as long as we each can read one another’s code, and we follow the PEAR standards, but the user interface is something that is tangible. It is something that any one person can look at and see inconsistency. Our goal is to compete on the level of best in class. That doesn’t mean best in class with other GPL projects, but best in class period. There is no reason to do something if you cannot do it right, and the user interface is one place that needs improvement.

32

FEATURE


That said, we have a staff of designers building a design guide. The problem will more than likely be the implementation, because the code base grows on a daily basis. As a member of the project management committee, to be honest I don’t much care about the how’s but rather the what’s. Our goal is XHTML 1.0 Strict compliance, along with the ability to run modern CSS layouts out of the box. Currently, that is possible, but there is still some fine tuning that must happen. Furthermore, we need to have a clean design out of the box, as some will judge more on the appearance than what is under the hood. It is a common problem that I am sure we share with many PHP (and even non-PHP) projects. Conclusion I have spent a great deal of time building a better mouse trap. That said, the Xaraya team deserves the credit for what we have built. Greg Allan who tragically passed away towards the end of my time at PostNuke also deserves much of the praise, as we continued on in respect to his memory and his vision. Greg was a friend and a mentor to us all, and he is greatly missed. I only hope that we have made him proud with what we have accomplished.

If anything I hope that I might have clarified some of the issues surrounding content management with this article. We can’t stop people from building applications without much thought, but we should all look at our applications and think about the designs a bit. I had to swallow some pride and look at what I had developed when I lead PostNuke before I realized what could actually be done. We started on the rewrite in January of 2002 and that work is just now coming to fruition. Good code doesn’t come easily, but at the end of the day I can say that I am proud of what we have accomplished.

About the Author

?>

John's websites and projects include dinerminor.com and now wyome.com. He is self taught in HTML, XHTML, CSS, Javascript, Perl, PHP among others tricks of the trade. John is best known for his work on the Nuke flavor of community management with contributions to PHP-Nuke and later as a founder of PostNuke. He is currently working with the Project Management Committee of Xaraya which is one of the more anticipated projects of 2004.


Have you had your PHP today?

• Subscribe to the PRINT edition • Subscribe to the ELECTRONIC edition

Visit us at http://www.phparch.com and subscribe today.

December 2003

●

PHP Architect

●

www.phparch.com

php|architect

33


F E A T U R E

by Marco Pratesi

Many developers use a database abstraction layer, which allows them to add a database layer to any application using almost any database as a backend, while maintaining a consistent interface to the data layer across all of their applications. A project born out of necessity, PHPLM is a unique solution to a problem some developers may not even know they have: the ability to add a menu to any application using a consistent methodology, and a reusable, flexible codebase. More importantly, this codebase already exists in the form of the PHP Layers Menu project, whose goals include an extremely broad list of supported browsers, XHTML 1.0 compliance, the ability to generate menus from a database, and lots more.

Introduction At the beginning of 2001, I was developing version 1.2 of the PgMarket e-commerce package (sourceforge.net/projects/pgmarket, www.pgmarket.net/). To ease the browsing of product categories, I integrated the PHP Tree Menu authored by Bjorge Dijkstra. However, it was a serverside menu system, and users asked for a faster way to browse the categories without having to go back to the server to expand sub-categories. A client-side menu system was the inescapable solution. I was very reluctant to implement this, as I absolutely did not like the idea of facing browser compatibility issues. Also, supporting Internet Explorer was a must, but I did not want to mess with the oddities inherent in Microsoft products. However, to satisfy the users’ feature requests, I reviewed the menu systems available at that time. The results of my review were rather discouraging; I did not find any free software/open source packages that were also sufficiently powerful to suit my needs. Furthermore, even the existing proprietary menu systems were not well suited to my needs. As an example, I found the JavaScript Menu Component authored by Gary Smith. It was a very interesting package, but it supported only Netscape 4.x and IE 4; the W3C standard DOM was not supported, hence it did not work on Mozilla / Netscape 6+ and it worked on IE 5+ thanks only to IE’s backward compatibility. I tried to extend this code, but the addition of DOM support did not seem straightforward; someone had already tried to add such support, but the resulting December 2003

●

PHP Architect

●

www.phparch.com

code did not work correctly for me. Furthermore, I was not an expert of software licenses, but the (royalty free) license of that package, which was copyrighted by the Netscape Communications Corporation, did not seem to be a free software/open source license. I wrote an email to the author to discuss these concerns, but his email address did not exist anymore, so I lost all hope and abandoned that package. Since then that package has been updated; currently, it does not work on Netscape 4 anymore. While it does work on Netscape Gecko based browsers (e.g. Mozilla and Netscape 6+), it does not work perfectly well, and it has problems with Konqueror (it freezes the browser in some cases). In addition, as can be read on the related URL, it is not supported anymore. I hope that its copyright holders change its license, as it is really a pity to abandon such an interesting package and waste all of that effort. A free software/open source license would allow the community to fix its bugs and restart its development. I also considered the HierMenus package by DHTML Lab. It was (and is) a very fine package, but I did not feel comfortable with its approach. The “user interface” was not based either on a “data format” or on a database scheme, and it did not seem immediately adapt-

REQUIREMENTS PHP: 4.2+ OS: N/A Applications: N/A Code: http://code.phparch.com/18/3 Code Directory: layers

34

FEATURE


able to my needs. One major stumbling block here was that URLs were handled through page loadings triggered by onclick mouse events, and the placement of the “menu bar” was absolute. I was aiming at a menu system with URLs handled through traditional links and the usual “anchor” tags, and took advantage of features like the right-button contextual menu and the middle-button click event - very handy features on browsers like Netscape and Mozilla. Moreover, I preferred a relative placement for the menu bar, so it could be handled like any other element of the page. And finally, it was a proprietary package, hence it could not be included by the PgMarket package anyway. Around that time, the dynamic layers used on the PHP web site caught my eye, and I began developing a system inspired by that site. I started writing a sort of dynamic menu system consisting of some PHP code to output HTML+JavaScript using data in the same text format used by the PHP Tree Menu. I decided to support Netscape 4, Mozilla, and Internet Explorer 4+, but without impairing the usability of PgMarket for other browsers. The HTML+JavaScript output was still not reliable after my first attempt, so I simply did not include that code in PgMarket 1.2. I added it to PgMarket starting from the subsequent development branch (1.3.x) and, after further improvements, PgMarket 1.4 provided a dynamic client-side menu system to browse the product categories. Subsequently, a friend of mine strongly suggested that I make the menu system usable as an add-on to applications other than PgMarket, as menu systems can be useful to people that do not need an e-commerce package. I took his wise suggestion, and isolated the menu-related code and split the PgMarket development starting a new project, and “PHP Layers Menu” was born. For many days I focused only on that code. I added support for Konqueror and Opera, fixed some bugs, and, after other relevant improvements, in August 2001 I released version 1.0.0. Since that first “stand-alone” release, PHPLM has captured the attention of many developers; I began receiving many comments, criticisms, and suggestions that have greatly helped the package to become what it is today. With the 1.0.4 release, I changed the license from the GPL to the LGPL to allow use of the package within non-GPLed software. I thought this license change would allow greater accessibility of the package, and encourage the use of a menu system that supported browsers available for open source operating systems (such support was lacking in some other packages). With version 1.1.x, in response to a user’s suggestion, I reorganized the code to write PHPLM as a PHP class so one could put more than one menu on the same page; starting from version 2.x, PHPLM is also compliant with W3C HTML and CSS standards. In particular, PHPLM is currently compliant with XHTML 1.0 Transitional. During the 2.3.x development branch, I added a December 2003

●

PHP Architect

●

www.phparch.com

client-side Tree Menu system. Now PHPLM provides two client-side menu systems — the Layers Menu and the JavaScript Tree Menu — and two server-side menu systems — a PHP Tree Menu that makes use of some code from the PHP Tree Menu project and looks like the JavaScript Tree Menu, and a Plain Menu for browsers not supporting JavaScript. The rest of the development history is relatively recent. But I’m not here to tell you every gory detail of the story. Mainly, I started almost only for fun. Sometimes it has been hard and tricky, but it has also been very exciting. Let’s move on to discussing the features, along with some tips and tricks on how to get the most out of the PHP Layers Menu System. PHPLM and the project it was born for: PgMarket Here I show how PHPLM is used in PgMarket with multiple menus and a database-based cache. PHPLM is used to generate the product category menus of PgMarket: as already explained, I started the development of PHPLM just for this purpose. At the time of this writing, PgMarket (version 2.3.1) provides three different menu options: • a vertical layers menu on the left navigation bar; • a JavaScript tree menu in the left part of the page “body”; • a PHP tree menu in the left navigation frame if frames are used. The tree menu options are shown from the demo of version 2.3.1 in Figures 1 and 2 (next page). The layers menu is used by default; the JS tree menu is used if the layers menu is turned off and frames are not turned on; the PHP tree menu is used when frames are turned on. Obviously, in PgMarket, menu data is read from the database. Figure 1

35

FEATURE


To achieve a higher level of efficiency, I suggest generating the menus only once and caching them, either using files, as I have done for www.telug.it, (we’ll look at this later) or through a database table (as in PgMarket). The HTML+JS code of the vertical layers menu and the JS tree menu is stored in the “cache” table, whereas caching of the PHP tree menu is not possible, as it is a server-side menu and its HTML code depends on the query string and can change at each page request.

“To achieve a higher level of efficiency, I suggest generating the menus only once and caching them...” Digging Into Code If you’re following along with a copy of PgMarket, the core portion of code related to PHPLM is in lib/pgm_common.inc.php, in the refresh_cache() function. This function is called by the 00_refresh_cache.php script, which has to be run during the PgMarket setup, and by the administration scripts when they change data related to the products categories. The list of available languages is retrieved from the “languages” table. The cache is deleted, and then, for each one of the available languages, the refresh_cache() function prepares the HTML+JS portions of code for the menus and stores the corresponding fields in the cache table. Note that, in PgMarket, the language is decided by the user by clicking on one of the flags, and stays stored in a session variable. The default configuration reads that variable, and the first

time the user loads a page of PgMarket, their preferred language is chosen according to the HTTP_ACCEPT_LANGUAGE value supplied by the browser (if you are interested, you can find the corresponding code in common.inc.php). To rebuild the cache, first the needed paths are set, according to the PgMarket configuration settings, using the methods setDirroot() and setImgwww(); then the arrow image and the templates are set. At this point, I have to set the dsn (Data Source Name) and tell PHPLM where to get the menu data. Empty field names can be used to disable an optional field, i.e. “title”, “icon”, “target”, “expanded”. A commented line shows how to use the “description” field as the “title” attribute of “anchor” tags; the “vanilla” PgMarket code does not foresee this option because, currently, the “description” field is intended as a field visible only for the shop administrator. Then I need to use the setPrependedUrl() method, to obtain the URLs corresponding to the respective categories “id”s. Finally, I generate the HTML+JS code portions to be cached and I insert them into the “cache” table. Now, let us look at the scripts that use these cached menus. PgMarket pages are prepared using the same template class used for PHPLM; the templates related to the vertical layers menu are templates/header.ihtml, templates/bar.ihtml, and templates/top.ihtml: templates/header.ihtml [...]

{bar} {top}

templates/bar.ihtml Figure 2 [...]
{layersmenu_vermenu} [...]

templates/top.ihtml [...]

December 2003

●

PHP Architect

●

www.phparch.com

36

FEATURE


The script that parses these templates is header.php: header.php

You can see here that header.php parses header.ihtml, which is a container for the bar.ihtml and top.ihtml templates: look at “{bar}” and “{top}” in header.ihtml, at the setFile() call in first lines of header.php and at the parse() calls in the last lines of header.php. To understand “visually” what bar.ihtml and top.ihtml are used for, run the following commands sh cd ln ln

00_addhtmlhead.sh templates -s bar.ihtml bar.html -s top.ihtml top.html

and then load bar.html and top.html in the browser. See Figures 3 and 4 below. Hopefully, this makes the use of templates more clear, and not less ;-) In the first lines of header.ihtml you’ll see {browser_detection}; we need the browser detection if the vertical layers menu or the JS tree menu is used, i.e. if JavaScript is used on the page. The JS tree menu is used if the layers menu is turned off and frames are not used. In other words, we need the browser detection if Figure 4

December 2003

●

PHP Architect

●

www.phparch.com

37

FEATURE


Now let us look at the layersmenu_used_header and treemenu_used_header template blocks in header.ihtml. The content of the layersmenu_used_header block is needed if the vertical layers menu is used, whereas the content of the treemenu_used_header block is needed if the JS tree menu is used. Hence, in header.php, I define these template blocks, set the corresponding content to an empty string, and then, with the two subsequent “if” statements, I parse (i.e., I output) only the block that is needed (if at least one of these two blocks is needed). Let us look at the first of these two “if” statements to understand what happens if the vertical layers menu is needed. Before parsing the layersmenu_used_header block, I connect to the database and refresh the cache if the corresponding configuration variable says that the menus must not be cached (this setting can be useful during development, to avoid caching problems if you change the database content by hand); then, from the “cache” table I retrieve the “layersmenu_header”, “layersmenu_vermenu” (i.e. the menubar), and the “layersmenu_footer” fields; then, the setVar() method sets the contents of the variables needed for the parsing of header.ihtml (“layersmenu_header”) and bar.ihtml (“layersmenu_vermenu”). Finally, the “layersmenu_used_header” block is parsed. The “layersmenu_footer” is used by templates/footer.ihtml and footer.php: templates/footer.ihtml

{layersmenu_footer}

footer.php

The JS tree menu is included through shopping/templates/index.ihtml and shopping/index.php, through code that is analogous to (and simpler than) the code explained w.r.t. the vertical layers menu. Finally, shopping/templates/navigation.ihtml and

December 2003

●

PHP Architect

●

www.phparch.com

shopping/navigation.php correspond to the PHP tree menu used in the left navigation frame if frames are turned on. Only a couple of considerations about their code: as already pointed out, the PHP tree menu is not cached; in navigation.php you can find some tricks for the setPrependedUrl() method, the query string, and the session ID (that is used if trans sid support is enabled and the browser has disabled the cookies) and a trick to set the targets for the categories links (I cannot use simply something like , as the links for the “+” and “-” tree icons must target the navigation frame). The rest of the code is analogous to what we have already seen in the refresh_cache() function. The “new generation” patch: www.telug.it Here I provide an explanation of how PHPLM can be used with server-side browser detection and a filebased cache. On the web site of our LUG (Teramo, www.telug.it/) we want to provide a good browsing experience to all users, as we do not want to keep anyone away from GNU/Linux. As an example, among people visiting our site, there are still a considerable number of Netscape 4 users (more than 1%), probably because it is a good option on old computers. Also, on a site like this, I think it is important to support text-only browsers to a reasonable extent. This benefits people like myself - sometimes I work from the console, in which case I use only Lynx and Links, but I do not want to be prevented from comfortably accessing the information available on our site. Also note that Lynx runs fine on very old computers. Furthermore, being a Linux-related site, we should support all browsers available for Linux, if possible. Supporting all browsers can be achieved by relying on client-side browser detection, and trimming down the menu system features accordingly. However, at some point, this becomes somewhat unreasonable. As an example, the NEW_GENERATION patch leads to a much more handy and beautiful menu, but it absolutely cannot work on old browsers such as Netscape 4. If we want to use it and to rely only on client-side detection, we have to send the code for both the “vanilla” and the “new generation” menu, thereby duplicating a large amount of client-side code and wasting a lot of bandwidth. Also note that Lynx and Links do not support DHTML, so to support them without resorting to a server-side detection, we would have to add an accessibility solution (e.g. the plain menu) that would waste bandwidth and space on the page for many browsers that just do not need it. I have decided instead to use a server-side browser detection scheme and to send

38

FEATURE


• the “new generation” version to sufficiently recent browsers; • the “vanilla” version to all other browsers supported by PHPLM • the “plain” version to other browsers, e.g. to Lynx and Links and to Konqueror 2.1- (some tests have convinced me that the plain version is more reliable than the vanilla version for Konqueror 2.1). Figure 5 is made with Mozilla and shows the menu sent to recent browsers. Using Figure 5 as a template, a generic page of this site can be subdivided into: • a “header” containing the HTML+JS code of the menu bar and of some other parts of the menu; • a “footer” that completes the HTML+JS code of the menu; • a “body” containing the information we want to put on that page. The “body” will be the same for all browsers, whereas we have to prepare different types of “header” and “footer” elements for different browsers. The browser detection result is used in header.php and footer.php, which are included at the beginning and at the end of each page. In header.php and footer.php I could put the PHP code needed to generate the HTML+JS code to be sent to the detected browser. However, to avoid wasting computing resources, I have preferred to “cache” the possible headers and footers using files. This is accomplished through the refresh_cache.php script, which detects the directory path and passes it to a “common” lib/refresh_cache.php. I have chosen this solution to enable use of the same approach, including the same code, for different menu contents on different parts of the site. Note that, to use the new generation version, I must: • apply the NEW_GENERATION patch; • rename lib/layersmenu.inc.php to lib/layersmenu-ng.inc.php and rename the LayersMenu class to “NGLayersMenu” to be

able to use both the “vanilla” and the “new generation” versions without conflicts; • change transparent-16x16.png to transparent-1x16.png: currently we are not using icons for any item, but try to omit any transparent image before the text of items and see what a stupid and clumsy bug is exhibited by IE 5.5... no comment. IE bugs speak for themselves. The NEW_GENERATION patch relies heavily on CSS features and I have developed it using suggestions provided by Shai Coleman, as it is documented in the ACKNOWLEDGEMENTS. For the telug.it site, I have removed the outer table as suggested in the menubar template: templates/layersmenu-horizontal_menu-ng.ihtml <meta http-equiv=”Content-Type” content=”text/html; charset=ISO-8859-15”> The PHP Layers Menu - Templates <pre> DONE If you eliminate the external table, the menu bar extends fills DONE horizontally the browsing window. —

{icontag}{text}{a rrow}

Note that you can write your notes outside the
Figure 5

December 2003

●

PHP Architect

●

www.phparch.com

39

FEATURE


BEGIN template —>... block, as the HTML code outside that block is not parsed. I have also renamed keramik.css as layersmenu-ng.css and customized it to obtain a look more suited to the telug.it site. The other templates used by lib/refresh_cache.php are: templates/header-common.ihtml <meta http-equiv=”Content-Type” content=”text/html; charset=iso-8859-15”> TELUG - Teramo Linux Users Group

templates/footer-common.ihtml

Finally, here’s a look at the code of header.php and footer.php: header.php

Note that the above code uses the wwwroot and dirroot parameters in such a way that header.php and footer.php can also be included by pages put in a subdirectory. The only “trick” is that all entries in menu_structure.txt are written as “absolute” paths, e.g.: menu_structure.txt .|TELUG|/index.php|Inizia da qui :-)|gnome-starthere-mini.png ^^^ [snip] ..|Marco Pratesi|/marco/|||linuxmarco ^^^ [snip]

If all pages to be linked by the menu are on the same site, an alternative (but more bandwidth consuming) solution may consist of using the setPrependedUrl() method (used in PgMarket). In Figure 6, you can see how the site looks on Netscape 4 (“vanilla” version, corresponding to “OLD” in lib/browser_detection.php) and on Links (“PLAIN” version) in Figure 7. As a final consideration for this section, you can note that a very deep customization of the menu look and behavior can be achieved through the “new generation” patch, which is very small. This illustrates the versatility of the PHPLM system and its approach. As the “new generation” patch is rather “quick and dirty”, in future versions I will change the code to integrate it in a clean way, without hardcoding HTML stuff into the class.

Figure 7 footer.php

Figure 6

December 2003

●

PHP Architect

●

www.phparch.com

40

FEATURE


PHPLM in Ampoliros and the “OnClick” patch (by Alex Pagnoni) The Ampoliros PHP web application platform is one of the packages using PHP Layers Menu. It uses it extensively and the user friendliness of the interface benefits greatly from it. A little introduction to Ampoliros: Ampoliros was born to provide developers the opportunity to reuse their code at the maximum level and to let system administrators do real administration stuff with minimum installation and management efforts for the applications. Another Ampoliros goal is to administer not only a site, but an unlimited number of sites with a single Ampoliros installation; this is very important for service providers. I also wanted to offer end users a pleasant and uniform interface. PHP Layers Menu lends itself nicely to these goals. Adding menus to an application greatly improves its functionality and, thanks to the PHP Layers Menu template feature, the menus can also be aesthetically pleasing. You can see PHPLM in action on the screenshots page at the Ampoliros homepage (located at www.ampoliros.com/en/screenshots.php). A little note on how the Ampoliros user interface is designed: the HUI (Html User Interface) is its name and it is completely object oriented, organized in containers (like groups, tabs, tables, grids) and widgets (buttons, form elements, and obviously menus). Adding a new widget (or container) to the system is only a matter of creating a new file with a class inside it (this class must extend the HuiWidget or HuiContainer ones), composed by its constructor for initializing and passing the widget arguments and the Build() method that does the real stuff. Thanks to the HUI design, implementing PHP Layers Menu inside Ampoliros and adapting it was very easy. In fact I only had to copy the PHP Layers Menu original code into a new widget file (the “menu” widget), define a new HuiMenu class and then let the HuiMenu>Build() method create a new instance of the PHP Layers Menu main class passing the menu structure and taking its output. Then I adapted the menu templates to the Hui interface standards and to the Hui Figure 8 theme feature. Being based on and introducing open technologies and standards, Ampoliros uses the original PHP Layer Menu specifications for implementing a menu structure in the Hui interface. So, once you already know Ampoliros architecture and Hui API, the PHP Layers Menu documentation is the only

December 2003

●

PHP Architect

●

www.phparch.com

guide you need to implement menus in an Ampoliros module. Iacopo Spalletti’s patch Iacopo Spalletti has developed a patch that brings 4 new features to PHP Layers Menu: 1. two custom JavaScript functions are called on opening and closing layers, respectively; 2. a fixed ordinate can be set for all levels in a menu; 3. a unique DOM ID is associated to each arrow image to allow to manage arrows via JavaScript; 4. if URL is empty for an item, no “href” attribute is used in the corresponding anchor tag (this feature removes the Netscape 4 support). With regard to feature 1 in the Iacopo Spalletti’s patch, LayersMenu::setCustomJsFunction($name) and LayersMenu::setCustomJsFunction($name) allow us to define two JavaScript functions that will be called on the opening and on the closing of each level in a menu, respectively. The mentioned custom JavaScript functions must accept the layer name as their only parameter. Feature 2 allows us to force the same fixed (absolute) ordinate for the upper border of all the sub menu layers of a given menu, using LayersMenu::setFixedPos($menuName, $ordinateFixed) . Feature 3 allows you to do things like keep the arrow images hidden, showing them only when the mouse pointer passes over the corresponding link, as can be seen in Figure 8 from www.toscanateatro.it, where the patch has been used. Something very similar will probably be applied, together with the “new generation” patch, to the PHPLM 3.1.x development branch to add the possibility of “switching” between two arrow images when the mouse passes over an item.

41

FEATURE


Trick: how to use the same database table for multiple menus As mentioned during our PgMarket discussion, PHPLM can retrieve menu data from a database, along with data for i18n support. However, the “vanilla” version implicitly foresees that a given table can store data only for one menu. Therefore, if you need to store data for two or more menus, you have to use two or more tables. For example, you can choose to use tables whose names are the same as the corresponding menus: “foo” and “foo_i18n” for a menu named “foo”, “bar” and “bar_i18n” for a menu named “bar”, and so on. However, you will see how some simple changes to the code allows us to put data for all menus in a single table. I prefer a PostgreSQL database, but for a MySQL database (or for another DBMS) there are only minor differences. We just add another field, i.e. the menu name, to the table(s), seen here in the start dump: —- DUMPS/pgsql.start.dump.orig +++ DUMPS/pgsql.start.dump @@ -8,6 +8,7 @@ CREATE SEQUENCE phplayersmenu_id_seq start 100 increment 1 maxvalue 2147483647 minvalue 1 cache 1 ; CREATE TABLE phplayersmenu ( + menuname text, id int2 DEFAULT nextval(‘phplayersmenu_id_seq’) NOT NULL, parent_id int2 DEFAULT 1 NOT NULL, text text, @@ -17,7 +18,7 @@ target text, orderfield int2 DEFAULT 0, expanded int2 DEFAULT 0, PRIMARY KEY (id) + PRIMARY KEY (menuname, id) ); CREATE TABLE phplayersmenu_i18n (

I have added the new “menuname” field to the primary key so we can use the same “id” for items belonging to different menus. Let us create the database and the table: bash$ createdb -U postgres phplayersmenu CREATE DATABASE bash$ psql -U postgres phplayersmenu < DUMPS/pgsql.start.dump

Now we have to add a simple condition to the WHERE clauses, and we’re done! —- lib/layersmenu.inc.php.orig +++ lib/layersmenu.inc.php @@ -889,6 +889,7 @@ $this->tableFields[“expanded”] . “ AS expanded FROM “ . $this->tableName . “ WHERE “ . $this->tableFields[“id”] . “ 1 + AND menuname = ‘$menu_name’ ORDER BY “ . $this->tableFields[“orderfield”] . “, “ . $this->tableFields[“text”] . “ ASC“); $this->_tmpArray = array(); @@ -909,6 +910,7 @@ $this->tableFields_i18n[“title”] . “ AS title FROM “ . $this->tableName_i18n . “ WHERE “ . $this->tableFields_i18n[“id”] . “ 1 + AND menuname = ‘$menu_name’ AND “. $this->tableFields_i18n[“language”] . “ = ‘$language’“); while ($dbresult->fetchInto($row, DB_FETCHMODE_ASSOC)) {

December 2003

●

PHP Architect

●

www.phparch.com

Future perspectives Some important issues have to be considered after the 3.0 release, starting from the 3.1 development branch. • Supported browsers

Until now, the set of supported browsers has been kept as broad as possible, with only one exception: the support of Netscape < 4.07 has been dropped starting from version 2.0, due to an evident bug for which there is no workaround. But, unfortunately, at this time, the support of some old browsers implies some constraints that prevent the implementation of a significantly better product. Moreover, to support such browsers, I have spent a large amount of testing and development time that could be dedicated to the development of new features. The following browsers are being considered for removal from the ‘supported’ list: • Netscape 4.x, whose DOM, unfortunately, is rather poor; • Internet Explorer 4, which is no longer supported even by Microsoft, and is very buggy and cranky, and whose DOM implementation is not standard compliant; • Opera 5 and 6 have many problems and bugs, also their DOM is still poor; • Konqueror 2.x that was still a “young” browser. In future releases, I will very probably drop the support of all of these browsers, in part because it would not reduce the number of supported platforms. For example, Mozilla supports an even larger number of platforms than Netscape 4, and all the named browsers can be upgraded without paying any fee. Furthermore, PHPLM provides “accessibility solutions” that allow support for any browser capable of handling simple HTML code. Of course, someone will be averse to this support removal, but, at the time of this writing, I am speaking about realtively few people. If you are among the ‘change averse’, please let me hear your voice and let me know the reasons why you disagree, either participating in the discussion on the sourceforge forums dedicated to the project, or writing me an e-mail. By the way, a reasonable middle-ground solution could consist of leaving the current layers-based menus unchanged, renaming its methods to show that it is an “old” solution, and starting the development of a “new generation”, more modern, layers-based menu type, supporting only “modern” browsers. In any case, the final decision will be made by me. I won’t feel too horrible about it either way, since PHPLM is free software and its license allows everyone to reuse the code and/or to fork the development (and to continue it if one day I have to give up for whatever reason). I am not forcing anyone to accept my decisions. With the “call for flames” out of the way, I want to

42

FEATURE


speak about some interesting features that can be added in the future and some possible changes. • Forms and windowed elements - the “see through” problem

I often receive bogus bug reports about a “z-index bug”, corresponding to the pass-through effect: layers are “perforated” by some form elements (known as “windowed elements”), as if they had a z-index value that places them below such elements. Well, this is not a z-index related problem, it is not even a bug of PHPLM. It is a known bug, or, if you prefer this term, a known limitation of some browsers. This happens each time a browser creates an element using a system’s built-in widget: the browser does not draw the region covered by the widget anymore, and the widget “perforates” the layers. This problem is markedly browser dependent: each browser is associated to its own set of “problematic” form elements. The most problematic browsers are Netscape 4, Konqueror, and Opera < 7, whereas Mozilla, Opera 7, and Safari seem to be the best guys from this point of view. I do not find a lot of problems in Mozilla 1.4 and Opera 7. As I have said, we are not talking about a PHPLM bug, we are dealing with browser limitations. However, a workaround could be implemented: each time a layer is popped up, the menu system could hide the page’s windowed elements that overlap with that layer and are problematic for the browser being used. Some interesting references about this topic: http://www.geocrawler.com/mail/msg.php3?msg_id=442660 6&list=119 http://www.webreference.com/dhtml/diner/seethru/ http://www.intranetjournal.com/ix/msg/36271.html

use tools like VIM, MC, and BASH even to prepare coffee). However, a GUI that allows the final user to prepare data without touching any menu structure file and/or any data dump could be useful and cool and could increase the user base. • Code reorganization

Probably I will reorganize the code a bit and the classes tree to use less code in building a single menu; currently, the code is better suited to use the package as in the demo, i.e. to put more than one type of menu on the same page. Conclusions These are the most relevant changes and improvements I am considering for future development of PHPLM. If you have other interesting ideas, feel free to submit them either on the sourceforge discussion forums or sending me an e-mail. A loud “ciao” to everyone! :-) Acknowledgments I would like to thank Alex Pagnoni and Iacopo Spalletti for their contributions to this paper.

References

• More comfortable layers menus

This is an important improvement that requires sufficiently rich DOM and CSS support and hence it would conflict with the option of supporting browsers like Netscape 4. To provide more comfortable menus and improve the imitation of traditional ‘system-like’ menus, I will have to do something like what I have done in the “new generation” patch.

DIJKSTRA - PHP Tree Menu, authored by Bjorge Dijkstra, whose home site was on www.zinc.f2s.com/scriptorium/index.php/treemenu; nowadays, this is a broken link, and, alas, I am unable to find that menu system elsewhere. SMITHMENU - The JavaScript Menu Component, authored by Gary Smith, whose home site was, very likely, on developer.netscape.com/viewsource/smith_menu/menu.html (sorry, I cannot find it anymore among my old bookmarks), that is now a broken link; currently, related URLs are: developer.netscape.com/viewsource/smith_menu2/menu.html and developer.netscape.com/viewsource/smith_menu/smith_menu.html

• A Graphical User Interface to build the menus

Some people have asked for a tool to input the menu data through a GUI (Graphical User Interface). Currently, the logical way to prepare data for the menus to be built is to write - by hand - the menu structure file, using a text editor, or, eventually, something like a spreadsheet. If you want to use a database rather than a menu structure file, the right conversion method allows you to obtain a data dump corresponding to the text file prepared by hand, as it is shown in an example script bundled with the package. In my opinion, preparing the menu structure is neither difficult nor annoying (maybe this is my opinion because I like to

December 2003

●

PHP Architect

●

www.phparch.com

DOM - Document Object Model (DOM) - www.w3.org/DOM/ HIERMENUS - HierMenus by DHTML Lab www.webreference.com/dhtml

About the Author

?>

Marco Pratesi lives near Teramo (Italia), where he was born in 1971. He is an Electronics Engineer and teaches at the universities of L'Aquila and Roma. In his spare time, he likes to develop and promote free software and documentation. He is a founding member of the Teramo LUG. He is also involved in the "Progetto Linguistico Italiano OpenOffice.org".

Click HERE To Discuss This Article http://forums.phparch.com/113 43

DBDesigner4

P R O D U C T

R E V I E W

http://www.fabforce.net

by Eddie Peloke

I

am, by nature, not a planner. I am the one in the development design meeting always asking..”ok...so when can we code?”. It is not that I don’t see the need for planning and the benefit of a well thought out design before coding begins, I just would rather be coding than writing design specs. That is why I am not a regular user of database modeling programs. Sure, I have used them in the past, but typically only to ‘reverse engineer’ an existing database into a model so the customer can see a ‘pretty picture’. One major excuse I have often used as to why I don’t use them is the price. Typical commercial products are just out of reach for the average programmer to use on their own. Another excuse is time. Typically your database will change tremendously once you begin actually writing code and unless you continually keep your database diagram up to date, you can find yourself with a backlog of catch up work. Fabforce.net has strived to solve both of these issues with their database design tool DBDesigner4. Fabforce.net calls DBDesigner4 “ a visual database design system that integrates database design, modeling, creation and management into a single, seamless environment”. DBDesigner4 was created, developed and optimized for MySQL although it does contain connection options for Oracle, MSSQL, and SqlLite. DBDesigner4 has some nice features (see end of review for full feature list) which will allow you to quickly and efficiently design your database as well as keep it updated. Best of all, DBDesigner4 is a free Open Source product licensed under the GPL. So, if database

December 2003

●

PHP Architect

●

www.phparch.com

design and maintenance is a part of your coding routine, pull up a chair and let’s get started. Get the Software DBDesigner4 is available via download from Fabforce.net. The software is available for Windows

QUICK FACTS Description: DBDesigner 4 is a visual database design system that integrates database design, modeling, creation and maintenance into a single, seamless environment. See the feature list at the end of this review. Supported platforms for DBDesigner4: • Windows 2000, and XP • Redhat Linux (7.0 and higher on i686) Price: FREE! (Donations are welcome!) http://www.fabforce.net/dbdesigner4/donations.php

Download Page: http://www.fabforce.net/dbdesigner4/downloads.php

Product Homepage http://www.fabforce.net/dbdesigner4/

45

PRODUCT REVIEW and Linux. Windows users are treated to a nice executable walking you through the installation process or you can opt for the zipped binaries. Linux users can find installations instructions on the Fabforce website. I chose the Windows executable and within a few minutes from download, DBDesigner4 was up and running. Let’s Start Modeling! When DBDesinger4 is started up, you will be taken into ‘Design Mode’. In Design Mode, you will see a nice uncluttered workspace with an empty canvas surrounded by the basic tools for the task at hand. The tools available to you are not as extensive as some of the commercial, and consequently more expensive products, but are enough for the average programmer. Design Mode allows you to build database models from scratch or reverse engineer an existing database (see Figure 1). Once placed on the canvas or model as the help describes it, DBDesigner4 allows you move the objects around and change their structure. You can add/delete columns, change column names and datatypes and

DBDesigner4

create indexes and foreign keys. Some of the objects, such as foreign keys, are automatically created when you use the Relation tool from the tools palette. Making a relationship between two tables creates a visual relation in the model and also automatically creates the foreign key in the table, depending on the relationship tool used. Other graphical tools include notes, images and regions all of which can be placed in your model to better visualize and annotate your database. Besides the graphical tools, there are also some nice edit windows where you can create and assign table indexes, datatypes, etc. much like you would find in any good db administrator. In listing 1 you will notice some interesting and helpful features to the right of your model. The first feature is a Navigator window which lets you quickly move around your model. With large models, this can be extremely helpful. Below the navigator you will find a Datatypes pane where you can get information on specific datatypes as well as edit their descriptions, add parameters, etc. Lastly, under the Datatypes pane you will find a tree view of your database model. So, your model is complete, now what? DBDesigner4 includes two nice features to help you

Figure 1

December 2003

●

PHP Architect

●

www.phparch.com

46

PRODUCT REVIEW transform your model into the actual meta information of the database, Database Synchronization and Create Table Scripts. As their name implies, one allows you to automatically make the changes to your database, the latter creates the necessary sql scripts so you can do it later (Figure 2). The other DBDesigner4 mode is ‘Query Mode’. One interesting feature of the Query Mode is the ability to let the application help you build your sql statements. Simply clicking within your model, you can build select, insert, update and delete statements. One down side to this, however, is that the statement may not be in the format you need. For example, when you choose to join two tables, it creates a statement with the older style join instead of joining using the join keyword. This may be fine if that is what you want but may not work for others. If you like to get your hands dirty and write your own queries, don’t worry, DBDesigner4 allows you to do that as well. No matter if you write them yourself or have the application help, any query can be executed against your database. DBDesigner4 has a nice results grid where you can scroll your data results, apply and discard changes (See Figure 3).

DBDesigner4

Figure 2

Figure 3

December 2003

●

PHP Architect

●

www.phparch.com

47

PRODUCT REVIEW

DBDesigner4

Figure 4

Figure 5

December 2003

●

PHP Architect

●

www.phparch.com

48

PRODUCT REVIEW Expanding DBDesigner4 supports the use of plugins which help to expand the product’s capabilities (Figure 4). DBDesigner4 currently ships with three plugins which are a nice compliment to the product, SimpleWebFront, HTMLReport, and DataImporter. FabForce.net notes SimpleWebFront “was designed to be an easy-to-use tool that allows the automatic creation of php-webpages. The created php-webpages allow you to insert/edit/delete and search for datatuples in your mysql-databases.” Note the ‘mysql-databases’ as SimpleWebFront only works with MySQL. HTMLReport as the name implies generates a simple HTML report showing the structure of your database. Lastly, DataImporter allows you to import data from other sources such as text files and other databases. Help! A general downfall of many open source products is their lack of good documentation. That is not the case with DBDesigner4. DBDesigner4 has a very nice html manual which covers all aspects of DBDesigner4 and should give you a great step in the right direction. The only downside of the documentation is that is isn’t searchable (Listing 5). What I liked Overall, I am very happy with the product. It did everything I asked and will suit my needs well. Design mode synchronization will help me keep my database and model easily in tune while the Query mode’s query execution capabilities will allow me to easily manage my data and possibly replacing my other MySQL administration tool. If you need help with your queries, the query generator can be a huge benefit. From the built in ‘optimize’ and ‘repair’ script generators to the ‘export model as MDB xml file’ option, DBDesigner4 has many ways to help you take your model into actual code. What I didn’t Like There aren’t may things about the product that I didn’t like but I do have a few gripes. For one, the product is tailored around MySQL, which in my case is fine but will not necessarily serve others. Second, the product has no UML support. Many of the commercial products, although much more expensive, not only allow for database modeling but also UML diagrams, flow charts, etc.

Conclusions Overall, if you use MySQL as your backend database than this is a great tool. It is light enough so that you can have a database model quickly and easily up and running, yet has enough features to keep the average

December 2003

●

PHP Architect

●

www.phparch.com

DBDesigner4

DBDesigner4 Feature List • Available on Linux / MS Windows • User Interfaced based on industry standard layouting software - Canvas navigation similar to Adobe Illustrator® and Photoshop® - Palettes (docked / floating) including “Bird Eyes view” - Available objects include tables, realtions, labels, regions, images - Extensive Drag’n’drop support - Extensive Popup-Menu support - Advanced Editors - UNLIMITED Undo-/Redo- functions - Copy-/Cut-/Paste clipboard functions (XML, DDL) - Align functions • Design Mode / Query Mode • Reverse engineering MySQL, Oracle, MSSQL and any ODBC databases • Userdefined schema-generation • Model-To-Database syncronisation • Index support • Automatic foreign key placement • Weak entity support • Standard Inserts storing and sync • Full documentation capabilities • Advanced model printing • Output as image • All MySQL datatypes with all options • User defined datatypes • Database storage, ability to save model within database • Network-/Multiuser access through database storage • Version control* • SQL Query Builder • SQL Command History • SQL Command storage within model • Plugin interface * Version control only available when using database storage

programmer happy. If you currently use one of the larger commercial modeling tools, DBDesigner4 may not have all the features you want but I find it well suited for the average programmer looking for a fast and easy way to design and maintain their MySQL database.

php|a

49

Customized Mailing List Management with PHPMailer

F E A T U R E

by Brent R. Matzelle While the mail() function may be sufficient for the simplest email needs of your application, more complex and demanding applications may benefit from a more flexible and robust solution, capable of grabbing user data from a pre-existing system, dealing with large amounts of user data and emails, and working in a consistent manner on any platform. This article discusses how the idea for PHPMailer came about, how it was created, how it is used, and why it is useful. Introduction Electronic mail, or email, is one of the primary technologies that helped the Internet become the popular global network that it is today. Even though many of the original standards have evolved since their creation in the 1980s, email is still fundamentally the same now as it was then. However, with time and maturity, implementing email has become a much more complex task. In order to send a simple email several events must occur. First, a mail client such as Outlook or Evolution creates an email message. The message is composed of a header and a body. The body is the portion of the email that is most visible to users. This contains the message content of the email. The header is appended to the top of the message and contains various bits of information used by mail servers and other mail clients to determine the destination of the email message and tells other mail clients to display the email. With a mail client you have some control over these headers with the “To”, “Cc”, or “Bcc” fields. After composing a message the client then sends the message to a mail server that is versed in the Simple Mail Transport Protocol (SMTP), the TCP based protocol that mail servers use to transport email messages between clients and each other. Once the message is successfully received, the SMTP server relays the message to the mail server of the destination domain using the information contained in the headers. The mail clients that most people are familiar with are the “fat client” types like Evolution. These clients work very well for composing and sending out individual December 2003

●

PHP Architect

●

www.phparch.com

emails. But what if you want to send out emails to a database of hundreds or thousands of users? If you used a fat mail client it would take a very long time to send out each personalized message individually. A very popular solution to this problem is using a mailing list program. This software allows one to manage the sending and customizing of large numbers of email messages all at once with a minimal amount of effort. There are several free mailing list managers available for download around the Internet. However, many of us do not have the luxury of using these managers because our user data is stored in our own custom system. If you are in this situation, then it is often easier to write your own mailing list management program. This article explains how to write your own mailing list manager from your own custom web system. The Solution About two years ago I started to look for ways to integrate PHP programming into an enterprise web environment. Electronic mail was and still is a very important part of each system that I worked with so I looked for the support that PHP had to offer. Some of you might be familiar with the mail function in PHP. It allows you to send a list of email addresses a subject,

REQUIREMENTS PHP: 4.2+ OS: Any Applications: N/A Code: http://code.phparch.com/18/6 Code Directory: mailing

50

FEATURE


message, and additional headers in a single function. This function allows you to send simple mail messages quickly. However, it becomes very cumbersome if you have many addresses, have to add your own headers, or if you want to add attachments. Furthermore, it is implemented differently on Windows and Unix platforms. The Windows version connects to a given SMTP server, while the Unix version uses the command-line sendmail executable to send messages. This means that your PHP-based mail application might react differently on a separate platform, something that the PHP language is usually known to avoid. After working for a while with the PHP mail function I realized that while it worked for the simplest of web site setups, its limitations for large complex projects would cause me problems in the future. As I normally do when I need something from PHP, I checked out the major free software sites and found several examples of email library software. None that I found truly met my particular needs. Since I had a lot of experience with email library software I thought that perhaps I could write one myself. On prior projects I had used a good object-oriented programming interface written by a proprietary software company. The properties and methods of this class suited me very well, so I modeled my own project with the same interface. The next step was to define the base requirements for the class. My primary concern was that it be scalable to a large number of users. Additionally, I work with PHP in both win32 and Linux environments, so I needed the class to work the same way in each environment. So, unlike the PHP mail function, it had to behave the same way in separate environments. The best solution was a class to send email via SMTP directly from PHP code. These primary goals make up the essence of the project that I later named PHPMailer. This project works to create a full-featured programmer’s library for sending emails. It abstracts all the processing necessary to write complex emails easily and flexibly. It is composed of two classes. The first is an SMTP class originally authored by Chris Ryan that I later adopted and enhanced. It provides a complete interface to sending mail messages via SMTP. Its guidelines closely follow RFC 821, the well known standards document that describes the SMTP protocol. This class gives PHPMailer very fine-grained control over sending messages over SMTP. The second layer is the PHPMailer class itself, which creates the structure of an email for the user. These classes combined offer the unique features of the PHPMailer project. The Full Featured Email Transfer Class PHPMailer was designed to give you complete programming control over sending email. I’ve tried to include lots of handy features. One nice feature is its ability to send to multiple address types. This includes December 2003

●

PHP Architect

●

www.phparch.com

the normal recipients (“To”), carbon copy (“CC”), and blind carbon copy (“BCC”). You can also send mail with either plain text or full HTML. The HTML can either point directly to images located on remote web sites or it can use embedded images that are attached directly to the email. This is useful if the user has email but has no direct Internet access (or is reading mail offline). PHPMailer has support for attachments of several types. The first is through ordinary files. It loads an attachment from a file located on a remote web server’s filesystem. It can also send attachments that are based on string or binary data. This is advantageous to use if you want to load an email from a data source other than the filesystem. For example, you could load a binary file from a remote source like a database. Another neat use would be to load a file from a remote FTP or HTTP server via the PHP fopen() function and then attach it to an email. That could be very handy! What if you have more than one SMTP server in your network and you would really like to use both of them? PHPMailer has a feature to meet that need as well. You can add multiple SMTP servers with multiple ports. While sending, if one mail server times out because of server overload or something, PHPMailer will switch to the alternate server. It works as a kind of simple SMTP failover system. Some mail systems use special headers to identify properties of an email. If this is the case in your system then you can use the PHPMailer method for adding your own custom headers. Unless simplicity is a must I would suggest sending via PHPmailer’s native SMTP capability. If that solution does not fit best with your configuration then there is another option in which PHPMailer can help you. By calling a single class function you can switch between several sending methods. The default method is to use the native PHP mail method. You can also choose to send via the sendmail executable (on Unix-like systems). Both of these methods tend to send emails faster if there are not many emails to send. Not all email clients support HTML email. There are several popular clients, like Mutt, which are designed to only read text-based email. In an attempt to cater to both mail clients that will only read text and those that can read HTML multipart-alternative emails were developed. This email message format allows you to send both a text and HTML version of an email in a single message. When the message is received by the client it can decide what type of message format it would like to display. This is a good option for mailing lists where you are not sure if the user can support (or wants to see) one or more of the formats. Structuring the Database So you have your own mailing system and you are interested in developing a mailing list program to send

51

FEATURE


out emails to a large number of your users. I will assume that you already have your own custom database that you use to store all your user information. Since each database is unique to you or your organization I will demonstrate the proper structure of a database through what I would consider to be a common setup. The database creation and access examples in this article are based on the MySQL database management server (http://www.mysql.com/). Support for this server is built into PHP by default and there are a huge number of people familiar with it so it was an easy choice for this article. If you have a different database then you will find that the examples can be quickly adapted for whichever one you use. An even better solution would be to alter my examples to use your favorite PHP database abstraction layer. For my example only two tables are needed to adequately handle the mailing list application. The first table I call subscriber (see Listing 1), as it represents the generic user data for your web system. The only other table is subscriber_email, which contains all of the information useful to PHPMailer. It contains columns to store the email address of the user, whether the user is subscribed to the mailing list and if they want HTML email. You will notice that two of the fields are SMALLINT types, the is_subscribed and is_html columns. I chose SMALLINT because these fields are to represent boolean values. When I want to determine if a user option is turned on I indicate this with the value of 1 (one) and off if the value is set to 0 (zero). This technique is probably familiar as it is used in many systems. Choosing an SMTP Server You simply cannot send mail efficiently without the help of a well designed SMTP server. You will find that there are many to choose from and each one usually fits into its own niche. For the purposes of this article I suggest a general purpose, speedy SMTP server. You will probably find dozens of free and commercial types out there. Postfix on Linux has always been my SMTP server of choice. It does an excellent job of queuing messages while keeping system resources low even under a high load. Nowadays most mail servers are configured by default to prevent untrusted sources from relaying mail Listing 1 CREATE TABLE subscriber ( subscriber_id INT PRIMARY KEY, first_name VARCHAR(70), last_name VARCHAR(70) );

●

PHP Architect

mynetworks = 192.168.0.0/24

This line means that Postfix should allow all IP addresses from the 192.168.0.x subnet to relay mail. Your mail server will no doubt have a different method to set this configuration. A quick browse through some documentation should get you the right setting. Writing the Mailing List Manager Now that we are finished with all of the external components required for the mailing list system we can get to the source code. The first step is to install the PHPMailer library. Download the latest version of PHPMailer from the project web site, phpmailer.sourceforge.net/, and extract all files from the archive. Copy the PHPMailer class files into the php.ini include_path as explained in the README. If you do not have control of the include directory and you are running PHP 4.0 or higher you can use this function to set it to the correct directory: ini_set(“include_path”, “.:/path/to/phpmailer/dir”);

As of the latest version of PHPMailer there is now multilanguage support. This allows developers to choose a default language for error messages at runtime. So if you have a system that supports more than one language you can switch to the users preference with a single call method called SetLanguage. All of the PHP source code for this mailing list manager is stored in the progress_meter.php file. To make configuration of the list manager easier I placed all variables that are specific to your environment at the top of this file (see Listing 2). All of the variables that start with “db_” are database related variables. For instance, I named my database “mailing_list” so I set the $db_database variable to this value. The $smtp_host variable is the name or IP address of your SMTP server. If you want to add more than one SMTP server then Listing 2

CREATE TABLE subscriber_email ( subscriber_email_id INT PRIMARY KEY, subscriber_id INT /* REFERENCES subscriber */, address VARCHAR(100), is_subscribed SMALLINT, is_html SMALLINT );

December 2003

through them. In the past SMTP servers were not configured in this way and email spammers would use them to send out loads of email without having to use their own resources and bandwidth. You will have to configure your SMTP server to relay email sent from your web server. I set this up on Postfix by allowing the machine on my local intranet to relay by adding one line to Postfix’s main.cf file like this:

●

www.phparch.com

// Configuration variables $db_host = “localhost”; // $db_username = “root”; // $db_password = “”; // $db_database = “mailing_list”; // $maximum_send = 2; // // each page $smtp_host = “192.168.0.1”; // // $log_path = “c:/temp/”; //

database host database username database password database name max number of emails to send load SMTP host name/IP address(es) path to the log file

52

FEATURE


you can if you separate each one with a semi-colon like this: $smtp_host

= “smtp.mydomain.com;192.168.0.50”;

The $maxiumum_send variable is the maximum number of messages that are sent each time the page is loaded. I will explain what this variable is for later. I will explain the $log_path variable in a later section as well. The List Manager Interface The list manager interface is very simple. The interface is HTML, with a form containing three fields (see mailing_list.html). Subscribers can choose to receive either HTML or text versions of the list email. These options are represented by a field for each choice. Each field points to a version of the list email of the appropriate type located on the web server. This enables you to write list emails in your favorite text or HTML editor. Then when you are done with each email you can just place it on the web server and point to the path with the list manager interface. Remember that the web server has to have access to the directory in order to read the file. The only other field is the Subject field. This field is used by PHPMailer to set the subject line for the outgoing emails. This subject is exactly the same subject line that you are used to seeing in your personal mail clients. There is a Send Messages button at the bottom of the page. When you click this the page will post to the progress meter page, progress_meter.php. This is where the mail sending actually takes place. The page sends out emails while displaying a progress meter showing the percentage of the total number of emails sent. Managing Large Lists Web servers and browsers are designed to quickly load individual pages. If a web server takes too long to send data to the browser two things can happen. Either the web server will send a timeout message to the browser or the browser itself will display a timeout message. Inevitably, the number of users in a system will grow to a much higher number over time. This can put a heavy load on a mailing list system. The more messages you have to send, the longer the web server will take to return a message to the web browser. As a result, you will eventually get to a point when timeout problems become a common occurrence. To combat this problem you could increase the timeout on both your web server and browser. This solution is not adequate for several reasons. First, it makes your software more difficult to port, since each web server has a different method to set the timeout. Also, you would not want to turn the timeout off because the timeout is good for preventing high server load if there is a processing

December 2003

●

PHP Architect

●

www.phparch.com

problem. You would need to configure all web browsers that used the interface to the higher timeout. Thankfully, there is a solution to this problem. Rather than sending all email messages at once, just send them out in smaller batches. If you only send out several messages at a time then the server will be finished with the processing much earlier so that neither the web browser or server timeout is ever reached. To accomplish this task all you need is a small amount of web programming trickery. If you take a look at the mailing_list.html page you will notice a hidden field called start_with is set to zero. This value tells the mailing list manager what subscriber record to start with so that it can send out all emails, but in much smaller numbers each time. The start_with variable gets incremented as emails are sent and then re-passed to the page as the new value. The subscriberRecords() method returns all subscribed user information in a set of records. The code then checks if the total number of subscribers is less than the value of $start_with. If the start range is higher, then all the emails have been sent. If not, it will continue to send messages. In the mail sending part of the routine (see Listing 3 on the next page) a new instance of PHPMailer is created. At this point several of the email properties are set. These include setting the subject of the email, the SMTP host, and the From address of the message. A call to mysql_data_seek() sets the subscriber list at the correct position so that the sending can commence. It is here that you can see what the purpose of $maximum_send variable is. The $sent variable that was initialized to zero earlier gets incremented whenever a message is sent. If this value is higher than $maximum_send then the current batch of emails is complete and the page can continue to show the current percentage in the progress meter. What value you should set as $maximum_send should reflect the capabilities of your mail and web server. If these servers are very fast then you can increase this number. Test it with different values to determine the optimal number for your system. When the current batch is finished sending, it will display the progress meter with the current completion statistic. There is a JavaScript method called pause that waits for one second then determines if the page should be re-posted if it is not totally complete. This is how the page knows to continue sending messages. A new feature of PHPMailer is the SMTP keep-alive functionality. It allows a programmer to maintain the connection to an SMTP server between each sending to eliminate the overhead of disconnecting and then reconnecting between each sending. This reduces the time that it takes to send mail while reducing the load. I am using this functionality to make list sending more efficient.

53

FEATURE


Customizing Emails A bit of customization in a web system can really improve the experience for users. This holds true in mailing lists as well. I added just a touch of customization to this example to demonstrate how you might do it yourself. There are many more ways to customize emails outside the examples that I give here. Just use your imagination and develop some of your own. If you take a look at the database structure you can see that we know a few things about each subscriber. We will use all of this information to customize the list email. In this example we know whether or not they requested HTML email. If you notice the main code loop (see Listing 3) the code checks if the is_html field is set to one (“1”). If it is, then I turn on HTML email with PHPMailer with the IsHTML() method. As an added touch I want to have the name of the person who I am sending the email to in the actual email. I do this by borrowing an idea from the template engines out there. You can see that in the message.txt and message.html files I have added {NAME} where a normal greeting might be. This identifier allows me to use the str_replace() function to replace this text with the name of the current mailing list subscriber. If you want to get really fancy with this functionality you can use a template engine like Smarty to accomplish this.

Catching Errors When you are dealing with sending a large number of emails, problems are bound to eventually occur. Issues like incorrect email addresses and mail server issues can be a cause of problems. If a problem occurs while you are sending messages you want to know about it but at the same time you do not want to stop sending out your mailing list of possibly thousands just for an issue with one user! The answer to this problem is a simple log file. Logging allows the code to continue sending messages while saving the error messages of any problems that occurred along the way. To handle this issue I wrote a function called logError() (see Listing 4) that saves all error messages to a mail_errors.txt file along with the time the error occurred. When an error occurs in PHPMailer the message is stored in the $ErrorInfo variable. All errors in PHPMailer bubble up to the Send() Article continued on page 66 Listing 4 /** * Log an error to a file. */ function logError($message) { global $log_path; $file = fopen($log_path . “mail-errors.txt”, “a”); $date = date(“Y-m-d H:i:s”); fwrite($file, $date . “ - “ . $message . “\r\n”); fclose($file); }

Listing 3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

php|architect (December 2003)

Point Sur L'epidemie de SIDA: December 2003

December

December

December

December

December)

December)

December

December

Multiwavelength AGN Surveys: Proceedings of the Guillermo Haro Conference 2003, Cozumel, Mexico 8 - 12 December 2003

Logic Programming: 19th International Conference, ICLP 2003, Mumbai, India, December 9-13, 2003, Proceedings

Multiwavelength AGN Surveys: Proceedings Of The Guillermo Haro Conference 2003, Cozumel, Mexico 8 12 December 2003

High Performance Computing -- HiPC 2003: 10th International Conference, Hyderabad, India, December 17-20, 2003, Proceedings

2003)

2003)

2003)

2003)

December Moon

December Moon

December 6

December Secrets

December 6

December 6

2003)

2003)

December 6

December 1988)

Our December

Miss December

12 December

php|architect (December 2003)

Point Sur L'epidemie de SIDA: December 2003

December

December

December

December

December)

December)

December

December

Multiwavelength AGN Surveys: Proceedings of the Guillermo Haro Conference 2003, Cozumel, Mexico 8 - 12 December 2003

Logic Programming: 19th International Conference, ICLP 2003, Mumbai, India, December 9-13, 2003, Proceedings

Multiwavelength AGN Surveys: Proceedings Of The Guillermo Haro Conference 2003, Cozumel, Mexico 8 12 December 2003

High Performance Computing -- HiPC 2003: 10th International Conference, Hyderabad, India, December 17-20, 2003, Proceedings

2003)

2003)

2003)

2003)

December Moon

December Moon

December 6

December Secrets

December 6

December 6

2003)

2003)

December 6

December 1988)

Our December

Miss December

12 December

Recommend Documents