PHP

First steps with PHP - booting a script, Part 2

developer — Fri, 25 Apr 2008 22:22:13 +0000

If you haven't already, you may want to start with Part 1 of this topic. Part 2 of my discussion on booting begins with a digression.

Frameworks and libraries

Some time ago, I read an article by Rasmus Lerdorf titled The no-framework PHP MVC framework. It got me thinking about my framework, which at the time I was converting from PHP4 to PHP5.

In the good old days, if you wanted to create re-usable code, you would create a library of related functions or objects. Now, the excitement is all around frameworks. Everyone has one. What is the difference between the two?

In my mind, a library:

Is under the control of the application
Provides a set of functions or objects for performing a closely related set of tasks
Has few pre-requisites
Works independently of other libraries

A framework:

Controls the application
Tends to enforce a methodology
Performs a wide range of tasks
Contains code that is heavily dependent on the framework environment. It would be difficult to extract a single piece of functionality without dragging in most of the rest of the framework.

I like the synergy of the framework, but I also like the flexibility and lighter weight of a library. Frameworks tend to be biased to solving a specific kind of problem. I wanted something more general.

My framework would:

Be object-oriented
Be under the application's control
Provide an architecture that allowed addressing a wide range of tasks
Consist of "libraries" which worked synergistically but which would also allow integration of external functionality (through base classes and interfaces)
Minimize the amount of core classes needed to use the framework

I know that calling my framework a "framework" creates some confusion. It is not a framework like CakePHP but it is a framework like the Java framework. Until a better term comes along, I'll stick with it.

Back to booting

Let's return to our main topic. The digression was necessary because it led me to completely separate the boot and framework code. Each operates independently from the other.

Returning to where we left off last week, we know that each Web page begins with

require 'include.inc';

where include.inc contains:

$fileTop = ...;
require "$fileTop/res/boot/boot.inc";

The boot.inc performs certain tasks but never directly accesses the framework code. The framework, in return, never directly uses any of the variables or functions defined in boot.inc.

Directory structure

This is the directory structure I use:

Notes:

The "res" directory contains all resources except images. This includes CSS, Javascript and PHP code.
The "boot" directory contains just one file, boot.inc. I just the same boot.inc file to boot many sites.
The "site" directory contains all the site-specific files. The boot system requires two files in res/site/php: conf.inc and setup.inc.
The "th" directory contains the Tiger Heron framework which I will cover in future articles.

The boot sequence

I can finally describe the boot sequence:

The server loads the Web page
The Web page loads include.inc
In include.inc, define $fileTop and load res/boot/boot.inc
In boot.inc, load res/site/php/conf.inc
Define some variables, set the include path and perform some basic initialization
Finish boot.inc by loading res/site/php/setup.inc

The conf.inc file gives the site a "hook" for any special setup that must be performed immediately. It also allows the site to configure some site-specific values for boot.inc. Code in conf.inc is limited by the fact that the include path has not been set up. It also cannot rely on any functionality other than what is in boot.inc and what is bundled with PHP.

While conf.inc is customized for each site, I usually start with a template. The template indicates some values I may want to define and speeds up construction of new Web sites.

Boot.inc will:

Define $webTop, the relative path to the top of the site. This is usually, but not always, the same as $fileTop. I use $fileTop to reference files in the file system and $webTop to reference files through the Web server (e.g. CSS files, Javascript files, etc.).
I determine whether this site is running on my PC, on a staging site or on a production site.
The error reporting is set based on where the code is running. On production sites, all error reporting is suppressed, while PC and staging sites report all errors.
I set up the include path based on the system type and values passed in by conf.inc.
I turn off user aborts, as these can wreck a database.
I remove magic quotes if they have been applied.
I allow for Macintosh line endings.
I set the content type to either text/html or application/xhtml+xml depending on whether I am using XHTML (a conf.inc option) and whether the browser supports application/xhtml+xml.
I use UTC as the timezone.
I define some absolute and relative paths to various commonly accessed places.

Having completed this list of tasks, res/sites/setup.inc is called to finish off any site-specific setup. It is the setup.inc file that determines whether the framework code will or will not be included.

I've left off one important step. The Web page, before including any code, can set define some values of its own. Let's say, for example, that you wanted to enable caching for some files and not others. The conf.inc file could include the default choice and each Web page could override that choice.

To make this clear, the Web page would start with:

$useCache = false;
require 'include.inc';

And the conf.inc file would contain:

if (!isset($useCache)) $useCache = true;

Finally, the setup.inc file would set up the caching based on the value of $useCache.

The caching example points out that boot.inc doesn't include all the tasks you may need for some Web sites. For instance, there is nothing in boot.inc for handling caching and sessions. These are more complicated tasks and are supported by the framework. Since the boot sequence can't depend on the framework, these additional tasks are left to setup.inc. For rapid site building, I have a template for setup.inc, but I am free to change it as appropriate for the site.

The .htaccess file

One of my goals was to be able to copy the entire site from my PC to the staging or production servers without requiring any code changes. Sometimes, code in the .htaccess file cannot be written to be system independent.

I used to have to maintain two copies of the .htaccess file, one for my PC and one for the hosting site. It occurred to me one day that I could start up my PC's Apache server with a -D DEVELOPMENT_ENV command-line option. This allows me to separate PC and hosting options using

<IfDefine DEVELOPMENT_ENV>
  ...
</IfDefine>

and

<IfDefine !DEVELOPMENT_ENV>
  ...
</IfDefine>

Mission accomplished

If you go back to Part 1 of this topic, you'll see I have met all the goals I set for myself without violating any of the restrictions I listed.

The boot sequence is fast, performing only what I need to support my PC/staging/production development approach. It also initializes the PHP environment, since I can't count on being able to set php.ini or using php_flag and php_value in my .htaccess file.

The boot sequence provides two hooks for site customization. I can also choose to use it with or without my framework. This gives me a lot of flexibility.

If you want a closer look at this, I have packaged up the boot code for a site at www.sample.com. The package includes two Web pages, index.php and subdir/index.php with the supporting boot files. It does not include any framework code.

First steps with PHP - booting a script, Part 1

developer — Tue, 18 Mar 2008 23:57:56 +0000

Having covered downloading and installing PHP and setting up a development environment, I'm now actually going to talk about writing PHP code! Specifically, I will describe how I boot my PHP scripts and why I boot them the way I do. Part 1 shows how my requirements for code portability and maintainability influence the boot process. Part 2 will go into more detail about the specific steps executed by the boot code.

My environment

Here's some background: I develop sites for multiple clients. Initial coding occurs on my Windows XP system. When the code is running well, I upload it to the client's hosting system, which is typically Linux based.

I start by creating a new directory for my client's Web files (on my PC) and then creating an alias in my Apache configuration file to point to this location. For this article, let's assume I reach the Web site using http://localhost/sample.

A sample task

For our first PHP class, let's tackle something easy—let's use PHP code to generate our sample site's navigation menu. Here's a quick sketch of the navigation class:

<?php
class Navigation
{
    public function printMainNav()
    {
        echo '<ul><li><a href="index.php">Home</a></li>....';
    }
}
?>

and here is the index.php page using the class:

<?php require 'Navigation.inc'; ?>
<html>
  <head>
    ...
  </head>
  <body>
    <?php $navigation = new Navigation(); $navigation->printMainNav(); ?>
      ...
  </body>
</html>

At this point, the directory we created contains two files:

index.php
Navigation.inc

The code works, but we're already seeing some potential pitfalls. First, we don't want to place the PHP classes in the same directory as the Web pages. Secondly, our sample system will eventually grow to where we will use sub-directories to organize our Web pages. The problems we see are:

Each Web page will need to include the Navigation.inc file based on the Web file's location. If we ever change our mind about where to place Navigation.inc, a lot of files will need changes.
The link to the home page (in the navigation), as written, only works for Web pages at the top of the directory tree.

It may seem that there are some easy work-arounds for these two problems. For instance, setting the path to the Navigation.inc file in the php.ini file solves the first problem. And linking to "/sample/index.php", solves the second. The reason these solutions aren't ideal lies with the environment in which I work.

Goals and requirements

These are my goals:

I want to use a consistent approach for all my clients.
I want to allow for sub-directories in the Web site.
I want all Web files to have a consistent way of including PHP code, regardless of their location on the site. This lets me use the same template for all files and to move a file from one place to another without having to edit it.
I don't want the Web pages to use any complicated calculations in order to include PHP code. Complicated code should be stored in one place, not scattered in every Web page.
I want to be able to upload the code from my Windows system to the hosting system without any changes and have it work in both environments.
Occasionally, I also want the code to work without change on a testing site on the hosting system. This lets the client preview site changes without affecting the site the customers sees.

These are the restrictions I have:

I can't alter the php.ini file since shared hosting services usually don't provide access to this file.
I can't place php_flag or php_value statements in the .htaccess file. These only work if PHP is run as an Apache module and some hosting companies use Fast CGI. (Note: apparently, this limitation will disappear in PHP 5.3.)
I can't assume I can reference a Web page at the top of the site by starting the path with "/". This might work for the final site, but not for the site on the PC, where the top is at /sample.

My current solution

I have not found the perfect solution. What I use is pretty close:

Each Web page begins with <?php require 'include.inc'; ?>.
Each Web site directory contains an include.inc file with the following contents:
```
<?php
  $fileTop = '.';
  require "$fileTop/res/boot/boot.inc";
?>
```

The advantages are:

We can move Web files from one directory to any other without editing.
The variable $fileTop identifies the file path to the top of the root of the Web site.
$fileTop is a relative path, so the Web site tree can be located anywhere in the site's document root.

It's not a perfect solution because I still have to create one include.inc file per directory. Of course, that's not very many files and the contents are not complicated. Any heavy lifting can be relegated to the boot.inc file.

It's also not perfect because it requires an extra file load for the include.inc file.

It assumes that '.' is in the php.ini search path. So far, this has proven to be a safe assumption.

Alternatives

Drupal and a number of other systems use a common dispatcher page for all Web site accesses. Every page loads index.php, which then includes the desired content. $fileTop is always '.'.

Using Apache's mod_rewrite module, the process could work like this:

The user enters http://www.sample.com/somepage.
Mod_rewrite converts this to http://www.sample.com/index.php?q=somepage.
The index.php file is loaded.
The index.php can directly contain the boot.inc code. This saves one include/require.
It uses the 'q' parameter to determine which page the user really wanted.
That Web page somepage.inc is included.

This eliminates two file includes. There is some hidden cost in that the mod_rewrite script probably has to do a file check to see if the requested Web file actually exists—this allows access to CSS, Javascript and image files that you may not want handled by PHP.

One problem with this approach is that my Web pages can set some options before loading the include.inc file and these options control aspects of the boot process (e.g. whether to use caching, whether to use sessions, etc.). I will discuss this more in Part 2 of this article; we might lose this flexibility in the single dispatcher approach or we might have to work around it in a way that voids the performance gain. Not having tried this alternative, I'm not sure of the answer.

Do you have an even better approach? Please let me know.

More to come

In Part 2, I will discuss what happens when the boot.inc file is executed. Stay tuned!

Eclipse and PHP

developer — Wed, 09 Jan 2008 16:29:44 +0000

In my last article, I talked about installing PHP. With PHP installed, you will want to start writing code, so today's article is about developing PHP using the open source Eclipse integrated development environment (IDE).

Eclipse started as a Java IDE and evolved into a generic IDE with a strong Java bias. If you start out with a standard Eclipse installation and without any Eclipse experience, it may take you a while to figure out the best way to set it up for use with PHP. This article will make the PHP setup fast and easy.

Why use Eclipse?

The reasons for using Eclipse are the same as those for using most IDEs:

Syntax highlighting
Syntax validation as you type
Editing assistance (indentation, auto-completion, etc.)
Access to documentation as you type
Refactoring assistance
Debugging assistance
Integration with other tools (documentation creation, source control, etc.)

Currently, the PHP version of a feature is often more limited than the Java version. For example, refactoring is limited to moving files; if you want to rename a class, method or function, you will need to use the Find/Replace tool (which, luckily, can be applied to all files in a project). I expect that the PHP tools will improve with time.

PDT

Eclipse consists of a core set of functions and a flexible plugin system. The plugins provide many of the features that we usually think of as standard parts of an IDE. This is what makes it possible to adapt Eclipse to many computer languages.

PDT is the PHP Development Tools plugin, which is essential for working with PHP inside Eclipse. Over time, you may choose to enhance your Eclipse installation with other plugins, but for PHP development, you only need PDT (and its few dependencies).

Getting started: Download

Begin by downloading the all-in-one Eclipse/PDT ZIP file. This contains all you need to start using Eclipse with PDT.

If you don't have Java Runtime Environment (JRE) 5 (or greater) installed, then you'll also need to download the latest JRE.

Getting started: Install

Start by installing the JRE, if you need it.

The Eclipse all-in-one package comes as a ZIP file. On Windows, you can extract the contents to C:\Program Files. This will create a folder called "eclipse". For easy access, copy the eclipse.exe file in the folder and paste it as a shortcut on the desktop.

Getting started: Configure

Start Eclipse by running the eclipse.exe file. This will ask you to select a "workspace", a folder that will store a collection of your projects. You can have more than one workspace.

Eclipse will suggest a location for the workspace. If you're happy with it, click OK. On Windows, I would suggest using something like My Documents\Eclipse. If you don't intend to create multiple workspaces, select "Use this as the default and do not ask again" before clicking on OK (you can change your mind later).

Eclipse should appear and display the Welcome screen (you can return to the Welcome screen through the Help menu). Now I will introduce you to Eclipse's rather intimidating preferences system: select Window > Preferences. Under PHP > PHP Interpreter, select PHP 4 or 5.

There are many other options you will want to customize, but this is sufficient to get started. You'll return to this menu many times to tweak how Eclipse works.

Getting started: Update

You should also become familiar with Eclipse's update system. Select Help > Software Updates > Find and Install > Search for updates of the currently installed features > Finish. Select a mirror or let Eclipse select one for you. Eclipse will now begin a rather slow search for updates. You can place the update dialog into the background and continue to work while the search takes place.

When Eclipse locates all the updates, a window will appear, showing you your update options. Select everything and begin the update. Once you have installed all updates, you may need to restart Eclipse. Your installation is now up-to-date.

The update method is also the way you add new features to Eclipse. Use Help > Software Updates > Find and Install, but this time select "Search for new features to install". You'll be able to search for features on a collection of sites.

For example, let's say you use doxygen to generate your PHP documentation. You would click on "New Remote Site", enter "Eclox" for the name and http://download.gna.org/eclox/update/ for the URL. This creates a new entry in the sites list.

You can visit Eclipse Plugin Central to find additional plugins to install. But let's leave that for later.

Creating a project for existing PHP code

Your Eclipse installation may coincide with the creation of a new PHP project, but it is more likely that you already have existing code you want to use within Eclipse. This is where most people get a little stuck—if you know the magic incantation, the process is easy.

Let's say you have a PHP Web site at My Documents\Sample\Web Site and that you test the Web site using the local server address http://localhost/sample.

Fire up Eclipse and select File > New > PHP Project. Enter a project name. Disable the Project contents > Use default toggle and browse to the My Documents\Sample\Web Site folder. Click Next. The files in the My Documetns\Sample\Web Site folder are now part of an Eclipse project.

You probably also reference code through a PHP include path. Select Libraries > Add External Folder to include folders in your Web site's include path. Click Finish.

Our project now appears in Eclipse's PHP Explorer pane. Eclipse will place a .project file in the My Documents\Sample\Web Site folder, but your content is otherwise undisturbed. You are ready to use Eclipse. You can also continue to work on your code using your existing development tools.

Editing with Eclipse

Using the PHP Explorer pane, you can double-click on a file and have it appear in Eclipse's editor pane. The features here are pretty standard, so I won't talk about them too much. You may want to return to the preferences dialog to customize the editing features.

One nice editor feature is called "code assist". Eclipse will pop up various displays that offer documentation or auto-completion help. If the code assist popup doesn't appear automatically, you can call it with Ctrl + Space. One caveat: if you have enabled the Emacs key bindings, the magic sequence is Alt + /.

Executing PHP

You can still run your Web pages by typing http://localhost/sample/some_page.php into your Web browser. But let's try running the page from eclipse.

First, some setup: Using Window > Preferences > PHP > PHP servers, we create a new server, Sample, with a URL of http://localhost/sample. If you would like to use your default browser, go to General > Web Browser, select Use external browser and enable Default system Web browser.

Open up your Web page in the editor. Select Run > Run As > PHP Web Page. In the dialog that appears, verify that the Launch URL is correct. The page will appear in your Web browser.

You may notice that the URL has many parameters attached to it. These are for coordinating with the debugger. This may be a bug in Eclipse since debug parameters should only be added when debugging a script.

Go to Run > Open Run Dialog. You'll see that you can create a "run configuration" that controls what happens when you select Run. For my "sample" project, I right-clicked on PHP Web Page and selected New. I set the debugger to XDebug, the PHP Server to Sample and the file to /Sample/index.php. On the Common tab, I toggled Run under Display in favorites menu.

Now I can run the index.php page by selecting the Run icon on the tool bar and then selecting the run configuration I created from the tool bar drop down. Using this method, the page appears without the debugging parameters attached.

As far as I can tell, you would have to create one run configuration per page. Or, as I pointed out earlier, you could just enter the page address directly in your browser and bypass Eclipse.

Debugging PHP

If you have your system set up to use either the Zend debugger or XDebug, it's easy to debug with Eclipse.

Configuring PHP for debugging is beyond the scope of this article. The Eclipse portion of the setup involves using Run > Open Debug Dialog to get to a dialog very similar to the Run Dialog. Create a configuration for debugging index.php and enabled the Debug toggle on the Common tab.

On the tool bar, you can use the debug button drop-down to select your debug configuration. Normally, the debugger will break on the first line.

When you start debugging, Eclipse will offer to switch to the PHP Debug perspective, which will give you the right panes and controls to run the debugger.

Additional resources

I hope these instructions give you a head start at using Eclipse for PHP. Here are some other places you may get assistance.

Visit http://www.eclipse.org/, the home page of the Eclipse project.
Visit http://wiki.eclipse.org/PDT, the home page for PDT.
Visit http://wiki.eclipse.org/PDT/FAQ for a list of frequently asked questions about PDT.
Use Help > Help Contents and open up the PDT User Guide for the online manual.

A Tale of Two Patterns

developer — Wed, 28 Nov 2007 23:24:16 +0000

Originally, I planned to write about how to configure the Apache server to run both PHP4 and PHP5. With the push toward PHP5 (see Go PHP5), there are now hundreds of articles covering that topic. Instead, I will talk about two IT patterns I use for PHP development on Windows. The patterns are ancient and familiar to most Unix developers, but little used in the Windows world.

Since the patterns existed long before the term "design patterns" came into vogue, they don't have any names that I am aware of. In this article, I will call them the Bait-and Switch and the Shell Game patterns.

Junction points

On Unix, the Bait-and-Switch pattern is implemented using soft links. On Windows, the equivalent feature (at least for folders) is a junction point. Since this is an obscure feature for many Windows users, let me start by describing what junction points do and how to manage them.

Junction points can be used to assign the address of one directory to another. Once created, file operations performed on the junction point are actually forwarded to the linked directory. Essentially, you are reaching the same files through alternate file paths.

The concept is similar to a Windows "shortcut", but shortcuts are limited in the number of file operations they support. Junction points are much better at "fooling" the operating system.

How do you create a junction point? Microsoft must feel that this feature is too confusing for most users as they omitted creating a user interface for it. I've been using a great open source tool: NTFS Link, written originally by Michael Elsdoerfer and now maintained on SourceForge.

I won't go into the details of installing and configuring NTFS Link since there is plenty of information on Michael's site. The only tip I'll give is to take advantage of the icon overlays feature in the configuration dialog so that junction points are easy to see in an Explorer window. You won't have any trouble spotting the junction points in my screen capture below.

I don't believe NTFS Link will work on Vista, since Microsoft has introduced a replacement for junction points called NTFS symbolic links. These can point to files as well as folders, which is somewhat closer to the Unix soft link command. You can use the "mklink" to create these links, but that's quite a step down from the beautiful interface that NTFS Link provides.

One caveat, specially for Unix users on Windows: if you delete a junction point, you will also delete the files in the folder pointed to by the junction point. On Unix, deleting a soft link only removes the link. This is one reason why it's important to ensure that junction points are easy to spot. The good news is that the NTFS Link package intercepts folder deletions and implements the Unix behavior. This works only for the junction points it creates.

Folder copies can also pose problems, but NTFS Link helps us there as well. When you attempt to copy a junction point, it will ask whether you want to copy just the junction point or to copy it as they it were a real directory.

The Bait-and-Switch pattern

To use the Bait-and-Switch pattern, start by installing multiple versions of a software package. Each version is usually placed in a directory with the package and version as part of the name; for example, php-5.2.5-Win32. Then create a junction point to the version you want to use. Finally, have the rest of the system access the package through the junction point. Now, changing the package version is as easy as redirecting the junction point.

Junction points can be cascaded. For example, you could use "php" to point to the latest version of PHP. Then use "php4" and "php5" to point to the latest version of PHP 4 or 5. So "php" would point to "php5" which would point to the latest version of php5. When PHP 6 is released, "php" would change to point to "php6", but "php5" would continue to point to the latest PHP 5 version.

The Shell Game pattern

The Shell Game pattern uses a different way of fooling the operating system. The idea is to run a program by first running a script that configures the program environment and then starts the program. If set up properly, the command you type to start the script can be the same as what you would normally type to start the program (e.g. typing "php" to start the CLI PHP program). On Unix, the script is usually a sh (shell) script and thus my name for this pattern.

This pattern is not as useful on Windows as Bait-and-Switch because so many programs store their environment in the registry. Unix programs rely more on environment variables and command-line options. The registry is global and any change affects all versions of the running program. Environment variables and command-line options, however, can be set per-application, so that we can simultaneously run multiple copies of a program, each tailored to behave different from the others.

PHP uses environment variables and command-line options for its behavior, so the Shell Game pattern works well for it.

On Windows, you can write the script using any of a number of tools. A batch file should be sufficient, but I use Perl. Perl is fast and also provides a solution for properly starting a windowed application based on PHP-GTK. You can get a version of Perl for Windows from ActiveState. I use IndigoPerl, but it hasn't been updated since early 2005.

Some Windows scripting tools are very slow, so be careful with your choice.

Applying Bait-and-Switch to a PHP installation

Here's a screen shot of my PHP installation.

I've installed PHP in C:\Program Files\php instead of C:\php. A few things to note:

The files with the large green arrows are junction points.
There are multiple PHP 4 and 5 installations as well as PHP-GTK.
The junction points point to one of the PHP 4, PHP 5 or PHP-GTK installations (typically, the latest, but it can be any version).
The "bin" directory is the only directory in the execution path.
There is one "pear" directory shared by all PHP versions. When I add a new PEAR package, all PHP versions have access to it.
There is one "php5-ext" directory where I place extensions that are independent of the PHP 5 version (currently, I have XCache and XDebug).
All the files needed to run PHP are stored in C:\Program Files\php. This includes the php.ini file. Each PHP version has one php.ini file, although I could also have had one copy shared by all versions.

Why did I configure PHP this way?

I was able to place PHP where I wanted it.
I was able to keep the php.ini file with the rest of the PHP installation.
I can easily switch from one version of PHP to another.
I can quickly install a new version of PHP without deleting my current version.
I need to maintain only one version of PEAR.
I can simultaneously run CLI versions of PHP 4, PHP 5 and PHP-GTK without any conflicts.

There may be other and better ways to achieve these goals, but this approach works well for me.

Playing the PHP Shell Game

My Bait-and-Switch configuration wouldn't work without the support of the Shell Game pattern.

The first step is to place C:\Program Files\php\bin in the execution path (Control Panel > System > Advanced > Environment Variables). None of the PHP installations should be placed on the path.

Next, create a set of Shell Game scripts that will take the place of the php.exe, php-cgi.exe and php-win.exe. Since I use perl, I make the process easier by adding PL to the PATHEXT environment variable and then running a batch file that contains these two lines:

assoc .pl=pl_auto_file
ftype pl_auto_file="C:\indigoperlperl\bin\perl.exe" "%%1" %%*

If you use ActivePerl, you will need to adjust the path to perl. Having done all the steps listed so far, you could now write a perl script called sample.pl, place it in the bin directory and execute it from any directory by typing "sample". Because we need to ensure that the PATH and PATHEXT variables are properly inherited by all processes, you may want to log out and back in again.

Here's the Perl script I use for the CLI version of PHP5:

#!/usr/bin/perl
# Command line (CLI) PHP 5

our $phpMainDir = "C:\\Program Files\\php";
our $phpDir = "$phpMainDir\\php5";
our $phpBinDir = "$phpDir";
our $phpExtDir  = "$phpDir\\ext";
our $phpBin = "$phpBinDir\\php.exe";
our $phpMibsDir = "$phpDir\\extras\\mibs";
our $pearDir = "$phpMainDir\\pear";
our $pearBin = "$phpMainDir\\bin\\php5.pl";

$ENV{'PATH'} = $phpDir . ';' . $ENV{'PATH'};
$ENV{'MIBDIRS'} = $phpMibsDir;
$ENV{'PHP_PEAR_BIN_DIR'} = $pearDir;
$ENV{'PHP_PEAR_DATA_DIR'} = "$pearDir\\pear\\data";
$ENV{'PHP_PEAR_DOC_DIR'} = "$pearDir\\pear\\docs";
$ENV{'PHP_PEAR_INSTALL_DIR'} = "$pearDir\\pear";
$ENV{'PHP_PEAR_PHP_BIN'} = $pearBin;
$ENV{'PHP_PEAR_SYSCONF_DIR'} = $pearDir;
$ENV{'PHP_PEAR_TEST_DIR'} = "$pearDir\\pear\\tests";

system "\"$phpBin\"", "-c", $phpDir, @ARGV;

The initial set of variable definitions set up a number of locations. The code is structured so that this is the only section that needs to be altered when creating CGI and CLI versions of PHP 4, 5 or GTK. GTK has no CGI version, so there are five scripts total. If you'd like to see all five versions, you can get them from this ZIP file (3KB).

We're not done yet! If you want to run a CGI version of PHP in Apache, you can just point Apache at the appropriate script. If you want to run PHP as an Apache module, however, you will also need to use the Shell Game pattern for the Apache executable. Start with the same script as for the CGI version of PHP you want use, delete the last line and append these instead:

our $apache = 
  "C:\\Program Files\\Apache Software Foundation\\Apache2.2\\bin\\httpd.exe";
system ""$apache"", @ARGV;

Save the result in a file called httpd.pl, place it in the Apache bin directory and change the Apache service to use "C:\indigoperlperl\bin\perl.exe" "C:\Program Files\Apache Software Foundation\Apache2.2\bin\httpd.pl" -k runservice. (I edited the entry by using a registry editor—does anyone know a better way?).

Finally, if you want to run some of the scripts in the pear directory (pear.bat, pecl.bat, phing.bat), you will need to modify the scripts to use the Perl scripts rather than directly calling the PHP executables. I'll leave this as an exercise for the reader.

One caveat: there are some programs (such as IDEs) that will ask you for the location of your installed PHP. Then they get very clever and try to determine if you have a valid installation. Well, the installation is valid, but the program won't be able to figure that out and will refuse to accept your choice. The solutions vary with the programs. Sometimes you can tell the program to set up an environment for the PHP subprocess. Sometimes you will need to write a Shell Game script for that tool. I haven't encountered many of these types of problems and haven't found any that I couldn't work around.

High-performance debugging

developer — Mon, 17 Sep 2007 03:14:32 +0000

In this article, I will show you how to use PHP 5 input filters to support debug, trace and assert statements so that a one-line change disables these statements and restores your script to full production performance.

Background

The typical debug statement looks like this:

echo "<p>Hello, I am a debug statement</p>";

This is the workhorse of PHP debugging—at least, when we aren't using a debugger. We insert it as needed and remove it when done.

Sometimes the debug code takes some work to produce or has some permanent benefits. The easiest way to preserve it is by placing it in a comment:

// echo "<p>Hello, I am a complicated debug statement</p>";

This can be inconvenient if we frequently need to enable debugging or if we need to enable multiple debug statements. So the next variation is to enable debug statements based on a flag:

if ($debugEnabled) echo "<p>Hello, I am a debug statement</p>";

Now, we can turn a number of debug statements on or off with a single setting. But we've also added some overhead that occurs even when the debug statements are disabled. We have also added some extra typing that will make us less inclined to use this tool.

You can gain some flexibility by using:

debug("Hello, I am a debug statement");

This opens the door to creating an elaborate debug system, but adds a performance penalty. Not only do we have the overhead of the function call, but the function argument is evaluated each time the statement is executed, whether debugging is enabled or not. We're back to:

if ($debugEnabled) debug("Hello, I am a debug statement");

PHP provides an assert() function which helps check program logic and can be disabled in php.ini. This function could be subverted to serve as the base for a debug system, but it appears to function much like the debug function above, at least in PHP 5.2.4.

For code that services thousands of requests per hour, the small overhead of these debug statements is significant and they are rarely left in place.

Why use debug statements?

Before going further, I need to answer the obvious question: why not use debuggers, profilers or other tools instead of debug statements?

The answer is that it's not an either-or; each tool has its place. Debug statements are sometimes faster to use or provide information that is easier to understand. For example, the ability to easily trace all database queries and send the output to a log file might be more effective in resolving some problems than stepping through the code with a debugger.

The debug system I will present to you has these goals:

It should support debug, trace and assert statements.
It should be easily and completely disabled for production code.
It should be easy to enter debug statements.

Setting the stage

Let me start with the three simple debugging classes I will use in this article. Each class name is prefixed with "th" for "Tiger Heron".

The first is the thDebug class, which allows us to format the output appropriately for Web or CLI use:

class thDebug
{
    static public function debug($msg)
    {
        if (php_sapi_name() == 'cli') echo $msg . "n";
        else echo '<p>' . nl2br($msg) . '</p>';
    }
}

The second class is thTrace. Tracing can be enabled or disabled, and you can set a threshold for the level of messages that are displayed.

class thTrace
{
    static private $isEnabled = false;
    static private $level = 0;

    static public function enable($isEnabled) { self::$isEnabled = $isEnabled; }
    static public function isEnabled() { return self::$isEnabled; }
    static public function setLevel($level) { self::$level = $level; }

    static public function trace($msg, $level = 0)
    {
        if (self::$isEnabled && $level <= self::$level) {
            thDebug::debug($msg);
        }
    }
}

The final debug class is thAssert, which generates an message only if an assertion fails. The "precondition" and "postcondition" methods are aliases for assert. Assertions, like tracing, can be enabled or disabled at run-time.

class thAssert
{
    static private $isEnabled = false;

    static public function enable($isEnabled) { self::$isEnabled = $isEnabled; }
    static public function isEnabled() { return self::$isEnabled; }
    static public function assert($cond, $file, $line, $title='Assertion')
        { if (!$cond) thDebug::debug("$title failed! $file:$line");  }
    static public function precondition($cond, $file, $line)
       { self::assert($cond, $file, $line, 'Precondition'); }
    static public function postcondition($cond, $file, $line)
      { self::assert($cond, $file, $line, 'Postcondition'); }
}

To enable the entire debug system, we use:

class thDebugManager
{
    static private $isEnabled = false;
    static private $isFilterRegistered = false;

    static public function enable($isEnabled)
    {
        if (!$isFilterRegistered && $isEnabled) {
            require 'thDebugFilter.inc';
            $isFilterRegistered = true;
        }
        self::$isEnabled = $isEnabled;
    }

    static public function isEnabled() { return self::$isEnabled; }
}

The references to the filter are explained in the next section. It might seem to make more sense to place this code in the thDebug class, but we want to avoid loading any debug-related classes when they are not used. The thDebugManager contains the minimum amount of code that we must load all the time.

PHP input filters

We'll now introduce the key PHP 5 feature we'll use for our solution: the input filter. We will create a filter that will transform PHP code as it is loaded, essentially acting as a dynamic pre-processor.

I started with some code from Adam Trachtenberg's book, Upgrading to PHP 5, and tweaked it a bit to create a reusable abstract class. To create a new filter, simply subclass this class and implement the missing function.

abstract class thAbstractStreamFilter
    extends php_user_filter
{
    private $data;
    private $bucket;

    public function onCreate()
    {
        $this->data = '';
        return true;
    }

    public function filter($in, $out, &$consumed, $closing)
    {
        while ($bucket = stream_bucket_make_writeable($in)) {
            $this->data .= $bucket->data;
            $this->bucket = $bucket;
            $consumed = 0;
        }

        $consumed += strlen($this->data);
        $this->data = $this->filterData($this->data);
        $this->bucket->data = $this->data;
        $this->bucket->datalen = strlen($this->data);
        stream_bucket_append($out, $this->bucket);
        $this->data = '';
        return PSFS_PASS_ON;
    }

    abstract public function filterData($data);
}

I'll refer you to Adam's book for the details on input filters.

The Debug filter

Using the thAbstractStreamFilter class, I can finally create the core of my debug solution, the thDebugFilter:

class thDebugFilter
    extends thAbstractStreamFilter
{
    public function filterData($data)
    {
        $data =
            preg_replace(
                '!//CODEs*([^nr]*)!m',
                '$1', $data);
        $data =
            preg_replace(
                '!//DBGs*([^nr]*)!m',
                'thDebug::debug($1);', $data);
        $data =
            preg_replace(
                '!//TRACEs*([^nr]*)!m',
                'if (thTrace::isEnabled()) thTrace::trace($1);', $data);
        $data =
            preg_replace(
                '!//ASSERTs*([^nr]*)!m',
                'if (thAssert::isEnabled()) ' .
                'thAssert::assert($1, __FILE__, __LINE__);', $data);
        $data =
            preg_replace(
                '!//PRECONDs*([^nr]*)!m',
                'if (thAssert::isEnabled()) ' .
                'thAssert::precondition($1, __FILE__, __LINE__);', $data);
        $data =
            preg_replace(
                '!//POSTCONDs*([^nr]*)!m',
                'if (thAssert::isEnabled()) ' .
                'thAssert::postcondition($1, __FILE__, __LINE__);', $data);

        return $data;
    }
}

I've introduced some special "keywords" to PHP: //CODE, //DBG, //TRACE, //ASSERT, //PRECOND and //POSTCOND. When the filter is not used, these all look like PHP comments. When the filter is enabled, each of these statements is transformed into live code.

You could do everything with //CODE. This is used to hide or expose any arbitrary line of code. The other statements reduce the typing needed to use the debug classes.

Here are some examples and their translations

//CODE $x = $x + 10; 
  -> $x = $x + 10;
//DBG "This is a debug statement."
  -> thDebug::debug("This is a statement.");
//TRACE "Level 4 message", 4
  -> if (thTrace::isEnabled()) thTrace::trace("Level 4 message", 4, __FILE__, _LINE__);
//ASSERT $x == 10
  -> if (thAssert::isEnabled()) thAssert::assert($x == 10, __FILE__, __LINE__);
//PRECOND $data == null
  -> if (thAssert::isEnabled()) thAssert::precondition($x == 10, __FILE__, __LINE__);
//POSTCOND $data != null
  -> if (thAssert::isEnabled()) thAssert::postcondition($x == 10, __FILE__, __LINE__);

Before using an input filter, we have to register it. The following line does the job:

stream_filter_register('phpCode.thDebug','thDebugFilter');

Tying it all together with __autoload

Now that we have the filter, how do we use it? Here is one way:

function thRequire($file)
{
    if (thDebugManager::isEnabled()) {
        require 'php://filter/read=phpCode.thDebug/resource=' . $file;
    }
    else {
        require $file;
    }
}

You would call thRequire() in place of any require statement. You would need similar methods for require_once, include and include_once.

I prefer using anothe PHP 5 feature, the __autoload() method. It allows us to dispense with most include and require statements, at least for classes. When a class is needed but not defined, the function registered with __autoload will be given a chance to load the class. Most of my code is objected-oriented, so this works well for me.

Here is the class that that handles class loading. For this article, I have deliberately created a very basic autoloader: it assumes that the class name maps to a file with an "inc" extension and exists in the include path.

class thAutoload
{
    static public function load($className)
    {
        if (thDebugManager::isEnabled()) {
            require
                'php://filter/read=phpCode.thDebug/resource=' .
                $className . '.inc';
        }
        else {
            require $className . '.inc';
        }
        return true;
    }
}

I still need to register my autoload handler with __autoload(), but that would be bad style. There's only room for one __autoload() method, so to allow sharing with other packages, I use spl_autoload_register() instead:

spl_autoload_register(array('thAutoload', 'load'));

If we were really using other autoloaders, we should also check if the file exists and return false if it doesn't, so as to give other autoloaders a chance to try loading the class.

In any case, all the pieces are present and the solution is complete:

thAutoload and thDebugManager must be loaded with a normal require or include.
To enable debugging, call thDebugManager::enable(true) before loading any classes containing debug statements.

So how well does it perform?

One way to see if I achieved my goals is to itemize all the overhead imposed by the debugging system when it is disabled.

The compiler will have to compile the thDebugManager class.
The thAutoload class also a small bit of code that is compiled but not used.
One if statement and a function call is executed per loaded class.
The compiler has to discard some extra comment lines.

To me, the overhead appears acceptably low. However, for the highest performing scripts, where you count nanoseconds, this is still not good enough. Here are options for increasing performance:

Using __autoload() is slightly slower than direct loads, so the scripts could use thRequire().
The thDebugManager can make the $isEnabled variable public—bad OO style, but it eliminates a function call.
Need more speed? Comment out the unused parts of thRequire(). This involves changing a few lines, but it is far easier than commenting out all the debug statements, which is what you would be doing if you used debug statement in the typical fashion.
Need even more? Edit all thRequires into straight requires. If we're talking high-performance scripts, you shouldn't have very many of these anyway. While this is not very convenient, you can enable a lot of debugging capability with a few edits.
Finally, use an opcode cache. This eliminates all compiler overhead.

Getting the code

I've put all the code together in a ZIP file, along with a sample sorting class that uses the debugging features and a main program that can be run using the command-line version of PHP.

Download high-performance-debugging.zip ( 7KB)

Where to go from here

The ability to trasnform code dynamically opens up a lot of pre-processing possibilities: how about running the code through the C pre-processor? Or a macro processor like m4? Or even adding new syntax to the PHP language? I'll explore some options in later articles.

A special request for opcode cache developers

The extra filter processing creates undesirable overhead that could be easily eliminated with an opcode cache, but it is unclear how many opcode caches support input filters. The dynamic nature of input filters make it almost impossible to determine when the cached code needs to be updated (after all, I could create a filter where the generated code would vary depending on the time of day) and this could discourage developers from adding suport.

I hope instead that the developers will provide some way of enabling this capability with the caveat that the user must manage the cache, either manually or programmatically. Without some caching support, there is a limited future for using this technique in production code.

In the beginning...

developer — Sun, 16 Sep 2007 02:11:02 +0000

Welcome to the first of a series of PHP articles. I hope to present you with useful tips, novel ideas, and code you can use or adapt. My reward will be learning more about PHP, both from researching the articles and from the suggestions and criticism you offer.

All my PHP articles will use PHP 5 as a base. Many will focus on OO programming and PHP performance, two topics I hope will generate lively discussions.

Many of the articles will include some working code. The code is provided under a Creative Commons license, and may be used in commercial and non-commercial works with attribution. I ask that you not sell the code except when embedded as part of a larger system.

Here's a list of the articles I plan to write. I will update it as I go. If any of these topics sounds interesting, subscribe to my developers' feed now to ensure you receive the article when it comes out.

High-performance debugging*
In support of the goPHP5 movement (and to start this series with a bang), I'll show you how to include debug statements in production code with no overhead. The technique can be extended to support dynamic pre-processing.
A Tale of Two Patterns
Using junction points and Perl, I'll show you how to easily manage multiple PHP installations on Windows, including multiple versions of PHP 4, PHP 5 and PHP GTK.
Eclipse and PHP
Create, edit and test PHP with the Eclipse 3.3 IDE.
First steps with PHP—booting a script, Part 1
First steps with PHP—booting a script, Part 2
Learn how to get PHP scripts going in a flexible and efficient way.
Autoload: the good, the bad and the ugly
The first in a set of articles introducing PHP 5's __autoload() method.
Autoload: Using class loaders*
Following up on the previous article, I'll discuss the contentious topic of class loaders.
Autoload: Overcoming session problems
Mixing __autoload() and sessions spells "trouble". I'll cover one possible solution.
Extending PHP syntax by using streams*
This article returns to territory covered by my first article and suggests ways in which the PHP language can be easily extended by using streams.
How much performance do you really need?*
To achieve maximum PHP performance you may have to sacrifice some coding flexibility. Should you?
Short and sweet: compression
How to compress for bandwidth savings.
Increase performance through caching
How to benefit from server and browser caching.
PHP and CSS*
Does it make sense to use PHP code in your CSS? Can you do it without sacrificing performance?
Database classes that make your life easier
This topic could easily become a set of articles. Can we improve on the mysqli library? How well do high-level database classes perform?
Iterators you can use
PHP 5 comes with a basic set of iterator classes. Here are some extensions.
Components*
I'll present my Component classes and ask: fantastic building blocks or huge performance drain?
An OO approach to forms and wizards
I lose tons of time developing forms and wizards. Here's my OO-approach to making their creation easier.
Opcode caching: the manual
I don't know what I'll write, but I know this is an article I'd like to read!

I hope you'll visit and contribute your ideas. Subscribe now!

* Unusual topics that should lead to some great debates.