software developers

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.

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.