I used Eclipse on a Mac to work with Java during my PhD, so familiarity made it seem the logical choice for some recent PHP development I've been doing. This post runs through the various plugins I added to support the development process, including checking code quality, running unit tests, and creating documentation.
The first step is obviously to install Eclipse. To ensure compatibility with all the plugins mentioned, I found it necessary to download the standard version of Eclipse and then install the PDT tools afterwards. The dedicated all-in-one PDT version of Eclipse didn't play ball with everything I needed it to.
Version Control – Subclipse
I use Subversion (SVN) for version control, and Subclipse seems to to be the de-facto client for Eclipse. However, there are some pitfalls to be aware of. If you install Subclipse and then try to add a respository in the SVN Perspective, you may get an error telling you that you need version 1.7 or higher of the JavaHL library. This is part of the Subversion binary, so your copy of SVN must be out of date. If you nip over to Collabnet for the latest version you'll find that they only have 1.6, so instead you'll need to visit WANDisco. Once 1.7 is installed, you should then be able to connect with Subclipse using the JavaHL library. Thanks to peeps on Stackoverflow for pointing this out.
Unfortunately JavaHL still failed for me, telling me that the network connection closed unexpectedly. I tried to use the SVNKit adapter instead of JavaHL, but it turns out that SVNKit isn't supported in version 1.8 of Subclipse, (the most recent version). I therefore uninstalled Subclipse v1.8 and installed v1.6 instead. That still didn't work because apparently SVNKit doesn't currently support SVN 1.7 (see previous link). Anyway, this turned out to be all a bit misleading, because when I tried it everything just worked.
Debgugging – Xdebug
If you want to debug PHP, then you'll need either Xdebug or Zend Debugger. I chose the former for reasons I can't quite recall. But setting it up required the following steps in Eclipse:
- In Preferences > PHP > PHP Executables, set up your PHP executable. Mine, the default Lion version, was at /usr/bin/php, and php.ini was at /etc/php.ini
- In Preferences > PHP > PHP Servers, set up your PHP server. I had to delete the "default" one first.
- In Preferences > PHP > Debug, set your debugger, server and executable.
- If you've changed the Xdebug port from the default of 9000 for any reason (I had problems with my initial Xdebug install, and that was one of the suggested fixes), don't forget to correct it in Preferences > PHP > Debug > Installed Debuggers.
Debugging with Xdebug. The 'debug' panel shows the methods which are currently running, while the relevant code is shown below. Panel on the right shows variables and their current values.
Coding Standards – PHP Code Sniffer
To ensure that your code is up to standard(s), you can install PHP_CodeSniffer with PEAR:
pear install PHP_CodeSniffer
There's more detail on their homepage, including information on the –report flag to get a summary of the errors in your entire project instead of all the detail for every file. I'd recommend creating your own customised standard so you can exclude errors you're not bother about (variables with single-letter names, for example). Once you've done that, you can also make your standard the default to be used each time you run PHPCS.
PHP Code Sniffer summary report.
Coding Problems – PHP Mess Detector
PHP Mess Detector does a good job of finding nasty bits of code. This includes 'dead' code that's never run, complicated loops / nested ifs, It's worth reading the section on how to create a custom ruleset, because the defaults may include tests that you want to exclude.
Unit Testing – PHPUnit
Unit testing is a great habit to get into, and test-driven development takes this to its logical conclusion. PHPUnit and SimpleTest both provide unit testing in PHP; I chose PHPUnit because there seemed to be more material online about how to use it. To install PHPUnit you can use PEAR. Unfortunately PEAR wasn't installed on my Lion system, but you can install it using wget. Unfortunately wget wasn't installed on my Lion system, but you can install it with a number of terminal commands.
Once wget is installed and then PEAR is installed and then PHPUnit is installed (!), you can set up Eclipse to run it as an external tool. However, it's much nicer to get it integrated into your Eclipse installation. To do this, I used MakeGood. The instructions on their website are pretty easy to follow and essentially boil down to:
- Install the MakeGood plugin from within Eclipse, using http://eclipse.piece-framework.com as the URL
- DON'T ignore the lines about having to specify a PHP executable; I did (because I already had an executable defined), but for some reason the executable had disappeared from my Eclipse preferences and so I had to add it again after much head-scratching.
- DO display the MakeGood 'view' in your Eclipse window as soon as possible – it has a nice little message which explains what might be stopping you running your tests.
- A message about Stagehand_Testrunner led me to install that separately, using PEAR (instructions are on the Stagehand website)
- Despite adding my PEAR folder as a library to the project build path, I was still getting a message saying that PHPUnit_Framework_TestCase could not be found when I ran a test. I resolved this by adding /Users/Haydn/pear/share/pear/PHPUnit to the build path too, and using require_once in the test class: require_once 'PHPUnit/Autoload.php';
MakeGood showing a successful test in Eclipse.
Once PHPUnit is working correctly, if you want to test database operations too then you'll need the DbUnit extension. There's extensive help regarding this whole subject area in the PHP Unit manual. Note that SQL Server isn't supported by default.
Documentation – PHPDoc
If you're documenting your code then you'll want phpdoc – installation instructions are on their website. Just use the two PEAR commands on their homepage, and ignore other websites (which generally omit the '-alpha' reference). If you try and generate some documentation but get an error about GraphViz not being installed ("Unable to find the `dot` command of the GraphViz package. Is GraphViz correctly installed and present in your path?"), go to the GraphViz website to download a .pkg file for Lion and install it. If you get a message about timezones, ensure that the correct one is set in your php.ini file (e.g. date.timezone = Europe/London).
Once all the above are in place, it's nice to be able to run them all together. You can use ANT to do this; here's an example of my ANT build.xml file:
<?xml version="1.0"?>
<!DOCTYPE project>
<project name="MyProject" default="test">
<property name="docs_dir" value="docs" />
<property name="log_file" value="MyLogFile.log" />
<target name="dtd" description="Creates a DTD for this build.xml file.">
<antstructure output="project.dtd"/>
</target>
<target name="clean" description="Deletes temporary and compiled files.">
<delete dir="${docs_dir}"/>
<delete dir="output"/>
</target>
<target name="messdetect" description="Runs PHP Mess Detector on PHP files.">
<exec executable="/Users/Haydn/pear/bin/phpmd" failonerror="true">
<arg value="." />
<arg value="text" />
<arg value="anciliary/PHPMD_custom_ruleset.xml" />
</exec>
</target>
<target name="codesniff" description="Runs PHP Code Sniffer on PHP files.">
<exec executable="/Users/Haydn/pear/bin/phpcs" failonerror="true">
<arg value="." />
<arg value="--standard=MyStandard" />
<arg value="--extensions=php" />
<arg value="--report=summary" />
</exec>
</target>
<target name="test" description="Runs all PHPUnit tests.">
<exec executable="/Users/Haydn/pear/bin/phpunit" failonerror="true">
<arg value="test" />
</exec>
</target>
<target name="document" depends="clean" description="Generates documentation for PHP files.">
<exec executable="/Users/Haydn/pear/bin/phpdoc" failonerror="true">
<arg value="-d" />
<arg value="." />
<arg value="-t" />
<arg value="${docs_dir}" />
</exec>
</target>
<target name="build" depends="clean,messdetect,codesniff,test,document" description="Run everything.">
</target>
</project>
