First step is to get a working install of PHP.

1. Download PHP 5.4.latest ZIP file from the PHP Windows website
2. Unpack the ZIP file into c:\php. You should end up with c:\php\php.exe
3. Copy c:\php\php.ini-development to be c:\php\php.ini
4. Edit c:\php\php.ini to suit (e.g. set date.timezone)
5. Make sure you add c:\php to your system PATH (via Computer’s Advanced Properties -> Environment Variables)
6. Reboot (this is Windows, after all :)

At this point, you should be able to open up a Command Prompt, and type ‘php -v’, and see the response ‘PHP v5.4.latest …’ appear as expected.

Now for PEAR itself.

1. Open http://pear.php.net/go-pear.phar in a browser, save this file into c:\php
2. In a Command Prompt, cd to c:\php and then run “php c:\php\go-pear.phar”
3. At the prompt, select ‘system’. A text menu of paths will appear
4. Fix the default path for pear.ini (option 11) to be c:\php\pear.ini
5. Fix the default folder to look inside for php.exe to be c:\php
6. Make sure the binaries folder (option 4) is c:\php
7. Check all of the other options, make sure they are prefixed with c:\php
8. Press ENTER, and you should see PEAR downloading various PEAR packages onto your system
9. Double-click the PEAR_ENV.reg file in c:\php
10. Reboot again to make sure PEAR_ENV registry entries have taken effect

At this point, PEAR is installed and should be available to use in your own projects, or with something like Phix.

Personal Notes

Some reminders to myself for the next time I have to do this.

• Documentation for PHP for Windows and PEAR for Windows both seem to be out of step with current downloads. There’s currently no Windows installer for PHP available, and the PHP .ZIP file doesn’t contain the ‘go-pear.bat’ file.
• You have to pay close attention to the default folders offered when running ‘go-pear.phar’. They appear to use the current working directory as the prefix even when installing system-wide, except for the location of pear.ini and php.exe – neither of these defaults are sane, and must be manually changed during the install :(
• After install, pear command doesn’t seem to be 100% compatible with its behaviour on Linux and OS X. -D switch didn’t work, there may be other problems too that I haven’t yet found.
• Both reboots are required – I’m not taking the piss there – for all running Windows apps to pick up the changes.

As the interest seems to be there, I thought it would be a great idea to follow up with a post taking you step by step through how I’ve set up Sublime Text 2 for PHP development, and showing you some of the useful features that you get out of the box with Sublime Text 2.

You’ll find the details below, and as a bit of an experiment, I’ve also put the details together in a series of YouTube videos for those folks who’d prefer to see ST2 in action. The video directly below is the first in the playlist, and I’ve also put the video for each feature separately further down. If you like the videos, please do click the ‘Like’ button on YouTube so that I know :)

Tip: If you can’t see any YouTube videos on this page, you might need to switch off your browser’s AdBlock plugin and then reload the page.

Install Package Control, Soda, And A Syntax Highlighting Scheme

Out of the box, Sublime Text 2 is a very good text editor. It’s so good, in fact, that I’ve seen people use it in its vanilla form perfectly happily for days and weeks before realising that it can be enhanced with third-party plugins!

The first plugin I recommend installing is Will Bond’s Package Control (installation instructions). Package Control is a plugin that automates the job of installing and upgrading plugins. After you’ve installed it, restart ST2, and then you’ll find a new “Package Control” menu option at the bottom of the “Preferences” menu.

There are over 200 community plugins currently available for ST2. You’ll find them by going into Package Control and selecting the ‘Discover Packages’ option. This takes you to the community packages webpage, where you can browse or search through the available packages. It’s worth going back and checking this page from time to time, as new packages are being added on a regular basis.

The next thing I normally do is reskin ST2. This is entirely a personal preference! Using Package Control, install the ‘Soda’ Theme plugin; this downloads the plugin, but does not activate it. Then, open up the ‘Settings – User’ preferences file (this is a JSON file), and add the following to tell ST2 to use the new theme:

"theme": "Soda Dark.sublime-theme",

You’ll notice a change straight away, but will probably need to restart ST2 for it to pick up all of the new theme properly.

Finally, I setup syntax highlighting to suit. ST2 ships with a number of these, and you can (if you wish) feed it any colour scheme originally created for TextMate. I prefer to use the ‘Phix Color Scheme’, which is available through Package Control.

Editing User Preferences

In ST2, nearly all of the configuration is done by creating and editing config files. There are no user interfaces to click through, just JSON files to edit by hand. There are a few of these files, and the basic idea is that there’s nearly always a ‘default’ config file (which contains the defaults that ST2 or its plugins ship with), and ‘user’ override files.

If you go into the Preferences menu, you’ll see a ‘Settings – Default’ option. This opens the default settings file that ST2 ships with. It’s very well documented, and well worth a browse through to see if there’s anything in there that you’d like to tweak. Don’t make changes to this file; instead, open the ‘Settings – User’ option on the Preferences menu, and put your changes in there. That way, your preferences will be preserved between ST2 upgrades.

Finding Classes With The Goto Anything Pane

There are two ways you can open files in ST2. One way is to navigate through your list of folders in the Project pane on the left hand side of the screen, clicking around with the mouse and drilling down to find the file that you’re looking for. It works … but there’s a faster alternative.

Hitting CTRL+P (CMD+P on the Mac) opens up the Goto Anything pane. Here, you can type in the name of the file that you’re looking for, and in real time, you’ll see a list of matches appear. The searching supports fuzzy matching; you can type in partial search strings, and ST2 will use them to filter out. This is a godsend for working with projects that include vendor folders (which you might not want to search inside), and any Subversion checkouts that include trunk, branches and tags.

Jump To A Line Using The Goto Anything Pane

Press CTRL+G (CMD+G on the Mac), and this brings up the Goto Anything pane, ready for you to type in a line number. As you type, ST2 goes to the line number starting to form in the input box. You can also do exactly the same by pressing CTRL+P and typing a colon at the start of the search. (CTRL+G simply opens the Goto Anything pane and puts the colon there for you as a shortcut).

You can also combine this with the file search. Hit CTRL+P and start searching for a file. Then, at the end of your search, add a colon, and then the line number that you’re looking for. This will take you to that line number in that file – all from the keyboard.

Goto A Defined Symbol Using The Goto Anything Pane

Press CTRL+R (CMD+R on the Mac), and this brings up the Goto Anything pane, ready for you to type in the name of a function or method. As you type, ST2 narrows down the list of matching functions, methods and classes in your file. You can do the same by pressing CTRL+P and typing an @ symbol at the start of the search.

You can combine this with the file search. Hit CTRL+P and start searching for a file. Then, at the end of your search term, add an @ sign, and then the name of the function or method that you’re looking for. This will take you to that function or method in that file.

Coding Quicker With The Additional PHP Snippets

The Additional PHP Snippets plugin [disclaimer: I'm the author of this plugin] provides a few simple text snippets to speed up everyday chores such as creating getters and setters, and add license text to the top of the file. It is available via Package Control.

Pull requests (or requests for features) are most welcome.

To use it, inside your PHP code, simply type ‘php-’, and ST2 will show you a list of all of the matching snippets. Select the snippet you want, hit TAB, and hey presto – the snippet is dropped into your code, ready for you to adapt as required.

Creating Doc Blocks Using DocBlockr

The DocBlockr plugin makes it very quick and easy to create doc blocks for your classes, attributes, and methods. It is available via Package Control.

To use it, open a new doc block as normal by typing ‘/**’ and then pressing ENTER. The plugin will create a template doc block for you to fill out to suit.

Real-Time Syntax Checking Using SublimeLinter

Real-time syntax checking is something you take for granted with an IDE, and it’s available in ST2 in 2 main flavours. I use the SublimeLinter plugin myself, and have had no trouble with it at all, but I know that some folks have had to use the sublime-lint plugin instead. Both are available via Package Control.

Once installed, your code is checked in real time for syntax errors. Lines that contain syntax errors are highlighted, and in the status bar at the bottom of the screen, you’ll see an explanation of what the error is.

Sometimes, the syntax error will appear to be on the wrong line – on the line below where the real problem is. SublimeLinter uses the ‘php -l’ command behind the screens – PHP’s built-in linter, and is simply reporting back exactly what the PHP runtime thinks is wrong. This might puzzle you at first if you’re used to IDEs that have their own lint algorithm built in.

Consulting The PHP Manual Using Goto Documentation

The PHP Manual is, imho, PHP’s true killer feature: all that detailed documentation, and it’s all freely available on the web (no need to go away and buy books on the language). Like many PHP developers, I’ve always got the PHP Manual open when I’m working.

The Goto Documentation plugin allows me to look up any PHP function from inside ST2. The plugin is available via Package Control, and once installed, you need to bind it to a key before you can use it. This is done by opening the ‘Key Bindings – User’ option on ST2′s Preferences menu, and adding a line like the following:

{ "keys": ["f1"], "command": "goto_documentation" }

Save the file, and you’re ready to go.

To use it, just put your text cursor on the PHP function that you want to look up, and hit your chosen key combination. Goto Documentation will switch to your browser, and search the PHP Manual for the function you’ve selected.

Handling Trailing Whitespace Using The TrailingSpaces Plugin

I know it’s a small thing, but trailing whitespace annoys the crap out of me, and I’ve always been deeply frustrated with how Netbeans never reliably stripped this from files that I created or worked on. Thankfully this isn’t a problem with ST2, and you can add the TrailingSpaces plugin to strip files in between saving them.

Testing Using PHPUnit

The PHPUnit plugin [disclaimer: I am the plugin's author] allows you to run your unit tests right from inside ST2. You can run the tests for just the file you’ve got open, or you can run all of your project’s unit tests in one go. You can also switch back and forwards between your PHP code and your unit test files, and you can quickly open your project’s phpunit.xml file.

To use the plugin, your project needs to have either a phpunit.xml file, or a phpunit.xml.dist file. This is a simple config file that tells PHPUnit where your tests are, which folders to include / ignore for code coverage purposes, and what reports / logs PHPUnit should create once the testing is done. If you’re using something like Phix, you get all of this for free, and I believe that Symfony’s standard app skeleton also includes a phpunit.xml file too.

The plugin navigates around your project, switching from file to file, using the following algorithm:

1. It takes the full name of your PHP class, including the namespace, and uses the PSR0 autoloader algorithm to try and find the same class with ‘Test’ appended on the end. If that doesn’t work, it strips off the namespace and tries again.
2. To find the phpunit.xml file, the plugin finds the test code first, and then searches each folder upwards for phpunit.xml or phpunit.xml.dist. If that doesn’t work, it looks in a number of pre-determined locations (defined in the plugin’s settings file), and then as a last resort it searches your whole project downwards starting from the top folder.

When you run your tests, the full output from PHPUnit appears in a panel at the bottom of ST2′s window – and that includes information on the full command executed, and which folder it was executed from. To close the panel, just hit ESC.

Alignment Plugin

This is a very simple plugin; it allows you to select some lines of code, and have all of the equals signs line up under each other. I find that this can make code (and especially array definitions) much clearer to read, but I know that it isn’t for everyone :)

Software Archaeology Using CTags

One of the ways that IDEs add a lot of value is that they truly understand the code you’re working on, and that allows them to offer features like ‘goto source definition’ et al. There’s a way you can do this in ST2, by installing the CTags plugin.

Once you’ve installed the CTags plugin, before you can use it, you need to go to the plugin’s website and follow the instructions there to get a suitable ‘ctags’ command line program installed. The plugin is a wrapper around this command’s functionality, and cannot work without it.

Then, the next step is to build a tags file. This is an index of all of your code, that the plugin can use to look up classes, functions and methods so that you can quickly jump to their definition from anywhere in your project. This is done by hitting CTRL+T and then CTRL+R, and then waiting for the ‘finished building’ message to appear in the status bar.

After that, you can navigate around your code by hitting CTRL+T and then CTRL+T again. This works particularly well for exploring code you haven’t seen before, something that I demo in the video below.

One last word of advice. CTags understands the syntax of your code, but not the strategy. It doesn’t understand the difference between trunk/ and branches/ folders, for example, or vendor/ folders. If there’s code in there, CTags by default will index it. This might be what you want, but if you find that it’s picking up duplicates that you’re not interested in, you’ll need to create a CTags.sublime-settings file in your User/ package folder to override the ctags_command setting and add in some exclusions.

What Else?

There’s one notable exception that I haven’t covered here, and that’s SublimeCodeIntel. This is a plugin that aims to bring Komodo’s autocompletion over to ST2. It’s a great idea, but my own experience with the plugin isn’t good. I’ve seen it installed on two different computers running the same OS and version of ST2, and it work fine on one and not work at all on the other. I’ve seen it stop working after a new version of the plugin was released. I’ve learned to live without it. But do go try it out, because if it works for you, you might really like it.

Are there any other ST2 plugins that you use on a daily basis? Mention them in the comments below, and I’ll check them out :)

I’ll be the first to say that Sublime Text 2 isn’t for everyone.

• It’s a beta product, which means there are some rough edges (mostly in the plugin API I feel), but it’s more than stable enough for production use. It has crashed a couple of times, which might put some people off, but I don’t recall losing any work as a result. File management in the project pane still needs work. The regular dev builds occasionally break things.
• It isn’t a full-blown IDE; it’s more like the spiritual successor to TextMate, an editor that I never personally cared for. In particular, it doesn’t support interactive debuggers, which means no Xdebug support, and there’s currently no obvious way for a plugin to add that functionality in [3].
• Auto-completion isn’t anything like what you’re used to. The built-in auto-completion is based on a mix of static knowledge of languages and fuzzy matching against what you’ve recently typed. There’s no obvious intelligence about the code you’re working on, nor the parameters for any method or function. These are two things that many people will deeply miss. [4]
• It isn’t free, but you can evaluate it for free with no time limit. If you decide to buy, it’s substantially cheaper than both PhpStorm and Zend Studio, and there’s no annual subscription element to the licensing. You’re buying a license to support and encourage an independent developer, and to show your appreciation for a very nice piece of software.
• It’s a closed-source product. You can’t fix it yourself if it breaks, and no-one can pick up the reigns if it gets abandoned. There seems to be just one guy behind it, and if anything happened to him, that’d probably be the end of the product. That said, most of the alternatives are also closed-source too.

Given all of that, why have I switched?

1. Sublime Text 2 is very very fast. Sublime Text 2 itself opens instantly. Files open instantly (provided they’re not 100 megabyte test data files). In fact, everything happens instantly – even inside a virtual machine running on a 3 year old laptop. There are no pauses for anything to be indexed, and I’ve never seen CPU usage spike – important for us untethered users and our suffering laptop batteries [5]. And if a plugin slows things down at all, Sublime Text 2 tells you which one is the culprit so that you can go and disable it. I’d compare the importance of the speed difference to switching from a hard disk to an SSD. You don’t realise how much you’re waiting for your slow Java-based IDE until you use something that’s properly fast.
2. It renders fonts properly – Droid Sans Mono and Ubuntu Mono in particular both look gorgeous – and even after a long day of use, my eyes don’t feel like they’ve been scratched on the inside by sharpened kitty claws all day long [6]. True story: one of my colleagues came over to ask what I was using, because he thought it looked so nice from a distance. When was the last time anyone ever thought that about a desktop Java app?
3. All of the searching is based on an extremely powerful fuzzy matching approach. Netbeans supports regexes, which can be very handy, but most of the time when I’m looking for something, a regex is overkill but a simple string search isn’t powerful enough. If I’ve got both a class called ‘IpcProcess’ and ‘IpcProcessID’, in Sublime Text 2 I can find the ‘IpcProcessID’ class by searching for ‘ipi’; I just have to type the shortest set of characters that uniquely matches what I’m looking for. It’s much quicker than writing (or running) a regex, and soon becomes second nature.
4. There’s a “goto anything” search panel which is lightning quick. Combined with the fuzzy matching approach, I find this a godsend for working on multiple large code bases, where there may be different classes with the same base filename, or duplicate installs of a class in vendor folders, or where I’ve got both trunk and branches checked out for the same project. It’s a killer feature, and one that has changed my workflow for the better, especially combined with my next reason. The panel’s also like using Google Instant – you get results as you type, giving you the instant feedback you need to refine your fuzzy search. (There is also a “goto symbol” search panel, and a “command palette” which allows you to search through the available editor commands to execute).
5. Everything can be done from the keyboard. Everything can be done from the mouse too, but I found that doing everything from the keyboard is both faster and doesn’t break the flow of what I’m working on. This is something I didn’t appreciate until after I’d switched, but it’s a fantastic help to me when I’ve got another developer sat next to me and we’re looking at (or for) something together. Together with the fuzzy matching, it’s like doing software archaeology with a JCB digger instead of a trowel.
6. It does a great job of auto-detecting whether a file uses spaces or tabs for indentation, and how big the tab stop is. There are days when it seems like no two files I open are consistent in how the code is indented, and it’s rare for anyone to have tagged on a modeline to give any hints. With Netbeans, which has a rigid config-based approach to indentation, I end up playing code-formatting table tennis with the original author of the file, as we always seem to have different indentation settings. Sublime Text 2 works out what the existing indentation approach is, and just auto-configures itself to match. It’s a great time saver [7].
7. It strips trailing spaces from the ends of lines when I save my files. This has been broken in Netbeans for years! It’s a small thing, I know, but it really annoys the crap out of me that Netbeans doesn’t get this right. As a bonus, in Sublime Text 2 trailing spaces actually get their own setting in color schemes, so you can see exactly where they are. In Netbeans, they’re bloody invisible :(
8. There’s a healthy ecosystem of plugins for it – over 200 plugins and counting – thanks to Will Bond’s Package Control package manager. Will is doing a great job of making sure that each plugin is tightly focused on sorting one problem only, to keep Sublime Text 2 as flexible and adaptable as possible – something to keep in mind if you start writing plugins yourself.
9. Creating new plugins is very easy. It took me just one evening to add and release the initial PHPUnit plugin, and that included the time it took to learn both Python and the plugin API from scratch. To make an update to your plugin, simply push your changes to your master branch on GitHub. It’s as close to frictionless as you can get.
10. I can own the tool, and set it up to suit my approach to programming. Because extending the editor is so effortless, I can automate anything that I want, to suit exactly how I want it done. I can create snippets, intelligent macros, and full-blown plugins to suit, and I can make them as and when some new need occurs – even one-off tasks. In this, it reminds me most of JED, which was my text editor of choice back in the 90′s for exactly the same reason. It’s the same reason folks love Vim. (Btw, Sublime Text 2 has a Vim mode. I haven’t tried it, so I can’t vouch for whether it’s good enough to tempt Vim users over or not).

Like Netbeans, Sublime Text 2 works on OS X, Linux and Windows [8], so I can use it everywhere I used to use Netbeans. I reckon it occupies a sweet spot that makes it very well suited to scripting languages and C/C++ development, albeit minus support for interactive debuggers.

At work, some of us have taken to it, and some of us haven’t. I’m happy to recommend it to anyone who’s looking for a change. You can take advantage of the open-ended free evaluation period, and see if it suits you or not. It’s working for me so far, and I probably spend more time using it than any other app on any of my computers.

If you do like Sublime Text 2, I’d love for you to leave a comment below with your own reasons why.

Footnotes

1. Dear Java, the 1990′s called and asked for their crappy non-aliased font renderer back. I think Windows 3.11 is missing it terribly.
2. There was a similar parallel around 20 years. At the time, Emacs was by far the most fully-featured editor, but everyone I know chose vi because of how slow and bloaty Emacs was at the time. It was so bad, we used to say that Emacs stood for “Eight megs and constantly swapping” (this was back in the days of 640K of RAM).
3. The lack of debugger support is, for me, the one feature that I miss every single day.
4. There is a plugin that tries to bring Komodo’s auto-completion to Sublime Text 2, but it stopped working for me before Christmas sadly.
5. It’s like when you switch from Firefox to Chrome for the first time … your laptop just gives a sigh of relief, and you don’t have to worry quite so much about how far away you are from the next convenient wall socket to recharge from. I can easily imagine running this on a netbook, or a laptop with very aggressive CPU throttling in place – both places where a Java-based IDE would struggle.
6. I’m highly visual, and find it really tiring to spend 10-12 hours a day in front of poorly-rendered fonts.
7. Now, if only everyone just did the right thing in the first place and used spaces instead of tab characters, we wouldn’t need functionality like this … :)
8. The keybindings are different from one platform to another, and because Python isn’t a platform-agnostic language, some plugins may not work properly on Windows at first. But most plugin authors are happy to accept pull requests with portability fixes.

One thing it didn’t have was support for PHPUnit, so I’ve made a plugin. It’s available to install via Package Control.

You Need A phpunit.xml or phpunit.xml.dist File

To use this plugin, your project needs to contain either a phpunit.xml or a phpunit.xml.dist file. This file contains all the configuration that needs to be passed to PHPUnit. The plugin searches upwards from your code, and will favour a phpunit.xml file over a phpunit.xml.dist file if it finds both.

If you don’t have one, you need to go and create one now.

How To Use

If you have your code open in a Sublime Text 2 window, right-click inside the window to see what your options are:

• Test This Class – click this option to run just the unit tests for this class.

  This option appears if the PHPUnit plugin can find your unit tests. It takes the name of your class, and uses the standard PSR-0 transformation to figure out what the name of your test file should be.

  For example, if your class is called ‘Phix_Project\CommandLineLib\CommandParser.php’, the PHPUnit plugin will search for a file ‘CommandLineParserTest.php’ that’s in a folder called ‘Phix_Project/CommandLineLib’.

• Open Test Class – click this option to open up your tests in Sublime Text 2. If you already have the tests open, this will switch tabs to your tests.

  Again, this option only appears if the PHPUnit plugin can find your unit tests.

• Run All Unit Tests – click this option to run all the unit tests for your code.

  This option just points PHPUnit at your phpunit.xml or phpunit.xml.dist file.

If you have your tests open in a Sublime Text 2 window, right-click inside the window to see what your options are:

• Run These Tests – run these unit tests, using the phpunit.xml or phpunit.xml.dist file that the PHPUnit plugin has found.
• Open Class Being Tested – open the class that these tests are for in Sublime Text 2. If you already have the class open, this will switch tags to your code.
• Run All Unit Tests – click this option to run all the unit tests for your code.

If you’re someone who prefers keyboard over mouse, then you’ll probably want to run the PHPUnit plugin commands from Sublime Text 2′s Command Palette:

You get the same commands that appear on the right-click menu … the right commands will appear for the file that you’re currently editing, just as you’d expect.

Finally, you can also right-click on your phpunit.xml (or phpunit.xml.dist) file in the Project Sidebar, and run your unit tests using that specific config file.

Helpful Snippets

Like TextMate before it, Sublime Text 2 also has a handy snippets feature, where it can insert a pre-crafted block of text (or, in our case, PHP code) to speed up your coding. I’m collecting most PHP-related snippets in my Additional PHP Snippets plugin (hat-tip to Rob Allen for the inspiration for this), but the PHPUnit plugin includes a few PHPUnit-related snippets to help.

• phpunit-testcase – will create a new test class for you to fill out.

  I find this handy mostly so that I don’t have to remember which class my test class has to extend :)

• phpunit-test – will create a new test method for you to fill out.

To use any snippet, type its name and then press the <TAB> key. Sublime Text 2 will insert the snippet, and then you can use the <TAB> key to cycle through any placeholders that you need to edit.

If you find snippets useful, please don’t forget to check out my Additional PHP Snippets plugin too!

Feedback, Contributions Welcome

I’d love to hear how you get on with the plugin, and any ideas you might have for additional features. And pull requests via GitHub are most welcome too!

This release is dedicated to my Dad, Leslie Herbert, who passed away in December 2011 whilst I was recovering from surgery. He was always encouraging me to spend as much time as possible working on my own software, and I’m sure he’d be happy that his PC has become my new dev box for working on things like Phix.

What’s New In This Release

• phploc support – the “phing code-review” command now also calculates the size of your component using phploc.
• subset support – you can now do “phix php-library:init –subset=<role>[,<role> ...]” to create components that only contain some of the different file types supported by the PEAR Installer. There’s also a “phix php-library:removeunusedroles” command if you want to strip unused roles from an existing component.
• phpunit.xml.dist support – components now use phpunit.xml.dist by default, so that you can put your own phpunit.xml in place if you ever need to override the default settings.
• src/README.md – we now drop a (hopefully helpful) README file inside the src/ folder to explain what goes where.
• misc robustness improvements to build.xml files – I’ve made some small tweaks to the build.xml file to try and catch a few error conditions and display helpful messages.
• internal debugging – “phix -d …” (which has been documented for several release now) enables internal debugging tests inside Phix and its components. It’s mostly there for me to use, but I thought I’d mention it in case you’re testing a patch for phix before sending it to me.

A big thanks to everyone who attended my workshop at PHPNW11 in October for their feedback and feature requests for this release.

How To Install

To install Phix, we have handy one-line install scripts on the Phix project homepage. And I’ve put together a screencast of how to install Phix on Ubuntu. It’s my first ever screencast, so please be gentle :)

How To Upgrade

To upgrade from an earlier release of Phix, please do the following:

sudo pear clear-cache
sudo pear upgrade phix/phix4componentdev

Once you’ve upgraded phix itself, don’t forget to go into each of your components, and run

phix php-library:upgrade .

to upgrade all of the skeleton files (build.xml et al) for your component.

What’s Coming In Phix 0.16

Windows support hasn’t happened yet, but I hopefully have a volunteer who is going to look into that during February.

My priority for phix-0.16 is to make it easy to build phix-based components in Jenkins, based on Sebastian’s Jenkins Template. I’m doing this next because I’m not sure how much I’ve got to change things to suit Jenkins, so I’d rather get it done sooner so it’s done and out of the way. (And I promise that I haven’t forgotten docblox support either …)

Our roadmap has all the details.

Side By Side Comparison

The Differences Explained

The key difference is one of philosophy. assert() sits well with the PHP4 style of error reporting and handling, whereas ContractLib is firmly in favour of the OO world’s approach to reporting errors.

It’s a personal preference, but I think that PHP4-style errors have no place in code that has any desire to be robust. Exceptions aren’t perfect, don’t get me wrong, but their core property of unwinding the call stack in an orderly fashion makes writing robust code much easier. And they also carry a payload – information about what went wrong and why – which PHP’s assert() cannot provide to the same extent.

It’s much quicker to debug something when there’s a record of the value that failed the test. For that reason alone, I’d always prefer something like ContractLib over the built-in assert() approach.

But we can’t ignore the fact that these are tests that get shipped to, and executed in, the production environment. Unlike unit tests, adopting programming by contract will slow down your PHP code in production. The question is: by how much?

What About The Performance?

I’ve done some benchmarking between the two, using the five tests listed in the final example in yesterday’s blog post. It’s a real-world example of the kind of tests that I would look to add to code to improve robustness.

Here are the results I gathered, calling the tests 10,000 times in a tight loop. The tests were run from the command line, and the times do include PHP start-up / shutdown time and the time taken to parse each test file. I assumed a best-case scenario, where the tests would always pass.

When tests are disabled, using assert() is much cheaper than using ContractLib today. That’s to be expected, as assert() is written in C. I imagine that we could get close to the same performance if ContractLib was rewritten in C as a PHP extension.

But, when tests are enabled, assert() is much slower than ContractLib. Why? Because the recommended way to use assert() is to pass the test in as a string. PHP has to convert that string into bytecode to execute, and that conversion appears to be quite expensive.

Given the choice, I’d rather trade things running a little slower in production for having much faster tests when I’m writing code, and that’s why I created ContractLib. Plus I get much better information to understand why the test failed, and if I wanted to run the tests in production, I can handle their failures in a much saner way.

Final Words

In my experience, the time it takes to develop and ship code is normally more critical than how fast the code runs in production. Developer time has become a scarcer resource than CPU time.

Used intelligently, these kinds of tests in your code can help your team deliver quicker, because the code they are using and reusing is more robust first time around. Programming by contract is different to, and complements, unit testing because contract tests catch errors in using the code.

Whether you use ContractLib, assert(), or you create your own solution, you should really consider how much it is costing you when you don’t use these kinds of tests.

Installing ContractLib

ContractLib is available from the Phix project’s PEAR channel. Installing it is as easy as:

$ pear channel-discover pear.phix-project.org
$ pear install -a phix/ContractLib

At the time of writing, this will install ContractLib-2.1.0. We use semantic versioning, so these examples will continue to work with all future releases of ContractLib-2.x.

Adding ContractLib To Your Project

Assuming you’re using a PSR-0 compatible autoloader, just import the Contract class into your PHP file:

use Phix_Project\ContractLib\Contract;

Adding A Pre-condition Contract To Your Method Or Function

Take a trivial method like this:

class ActionToApply
{
    public function appendNow($params)
    {
        $params[] = time();
    }
}

This method works fine … until someone passes a non-array as the parameter. At that point, your code stops working – not because your code is wrong, but because someone used it in the wrong way. This is a classic cause of buggy PHP apps. Thankfully, it’s very easy to address using ContractLib.

If we were certain that the $params parameter was always an array, then we can keep the method itself extremely simple and clean. We can ensure that by adding a pre-condition using ContractLib.

use Phix_Project\ContractLib\Contract;

class ActionToApply
{
    public function appendNow($params)
    {
        Contract::Preconditions(function() use ($params)
        {
            Contract::RequiresValue(
                $params,
                is_array($params),
                '$params must be an array'
            );
        });

        // original method code continues here
        $params[] = time();
    }
}

Now, if someone passes in a non-array, the caller will automatically get an E5xx_ContractFailedException, which makes it clear that the fault is in the caller’s code … not your’s.

PHP 5.4′s upcoming support for better type-hinting is another way to catch this kind of error, but not only does ContractLib work today with PHP 5.3 (which means you don’t have to wait to migrate to PHP 5.4), but also that you can write tests for anything, not just the checking that’s built into PHP.

This means you can make your code much more robust, by tightening up on the quality of the parameter passed into your code by other programmers. To extend our example, we might decide that an empty array is also unacceptable:

use Phix_Project\ContractLib\Contract;

class ActionToApply
{
    public function appendNow($params)
    {
        Contract::Preconditions(function() use ($params)
        {
            Contract::RequiresValue(
                $params,
                is_array($params),
                '$params must be an array'
            );
            Contract::RequiresValue(
                $params,
                count($params) > 0,
                '$params cannot be an empty array'
            );
        });

        // original method code continues here
        $params[] = time();
    }
}

The point here is that we can go way beyond type-hinting checks (important as they are) and look inside parameters to make sure they are suitable.

Here’s a real example from Phix’s CommandLineLib:

use Phix_Project\ContractLib\Contract;

class CommandLineParser
{
    // ...

    public function parseSwitches($args, $argIndex, DefinedSwitches $expectedOptions)
    {
        // catch programming errors
        Contract::Preconditions(function() use ($args, $argIndex, $expectedOptions)
        {
            Contract::RequiresValue(
                $args,
                is_array($args),
                '$args must be array'
            );
            Contract::RequiresValue(
                $args,
                count($args) > 0,
                '$args cannot be an empty array'
            );

            Contract::RequiresValue(
                $argIndex,
                is_integer($argIndex),
                '$argIndex must be an integer'
            );
            Contract::RequiresValue(
                $argIndex,
                count($args) >= $argIndex,
                '$argIndex cannot be more than +1 beyond the end of $args'
            );

            Contract::RequiresValue(
                $expectedOptions,
                count($expectedOptions->getSwitches()) > 0,
                '$expectedOptions must have some switches defined'
            );
        });

        // method's code follows on here ...
    }
}

In this real-life code, we start off by checking for basic errors first (by making sure we’re looking at the right type for each parameter), and then we follow up with more specific tests, that ensure that we have data that we’re happy to work with. We’ve done these tests at the start of the method, so that it isn’t cluttered with error checking, which makes our code much cleaner that it might otherwise be. And, because all the tests are in one really easy to spot block, anyone reading your code can immediately see what they have to do to meet the contract you’ve created.

Because these tests are just plain-old PHP code, and don’t rely on annotations or any other such nonsense, the contracts you create and enforce are limited only by your choices.

But Aren’t All Those Tests Slow?

They are. PHP’s getting better and better at this, but function/method calls have always been painfully slow in PHP. I’m afraid that if you want robust code, you can’t have it for free. (You can in C, but that’s a topic to discuss over a decent whiskey at a conference).

I’ve done key two things with ContractLib to keep the runtime cost down:

1. Contract::Preconditions() accepts a lambda function as its parameter. Your contract’s tests go inside this lambda function, and Contract::Preconditions() only calls the lambda function if contracts are enabled.
2. By default, ContractLib does not enable contracts. You have to choose to do so by calling Contract::EnforceWrappedContracts().

This keeps the overhead down to just one method call (to Contract::Preconditions()) when contracts are not enabled. It isn’t as good as having no overhead, but it’s cheaper than the developer time lost trying to track down bugs in code that always assumes the caller can be trusted to do the right thing every time.

Any Questions?

I hope these examples have given you an idea on how to get started with ContractLib. If you have any questions or suggestions, please let me know, and I’ll do my best to answer them.

ContractLib is loosely inspired by Microsoft Research’s work on the Code Contracts Library for .NET.

What Are Programming Contracts?

Programming contracts are tests around functions and methods, and they are normally used:

1. to catch any ‘bad’ data that has been passed into the function or method from the caller, and
2. to catch any ‘bad’ data generated by the function or method before it can be returned to the caller

These are pre-condition and post-condition tests, and they are tests that either pass or fail.

Why Have Programming Contracts?

Two reasons: code robustness and time saved.

Programming contracts catch errors early, and (unlike unit tests) they don’t just catch your errors, they catch errors made by programmers who reuse your code.

• Catching errors early

  There is a class of bugs best described as garbage in, garbage out. The “garbage in” is data that is of the wrong type, or out of range, or missing (think empty arrays, empty strings, nulls). Often, the garbage being fed in is also garbage that has come out of a buggy function or method.

  Simple pre-condition checks at the start of your functions and methods quickly catches garbage data before it can propagate through your code. The more functions and methods contain pre-condition checks, the easier it becomes to catch garbage data closer to where it is being created. This allows you to spend less time tracking down the original source of a bug, and more time writing new code.

  These pre-conditions also greatly increase the chances of bugs in your code being caught in development, especially when combined with a healthy amount of unit testing.

  You can also add post-conditions at the end of your functions and methods, to make sure that you’re never returning any garbage back out of your function or method. There’s a lot of overlap between post-conditions and unit tests; the main difference is that your post-conditions will run 100% of the time, whereas your unit tests will only run when you run them and against the (often extremely limited) data you use in your unit tests.

• Catching errors when code is reused

  Unit tests are great, and a very important part of creating high-quality code. But they’re your tests. They’re written to prove that your code does what you think it does.

  Unit tests don’t prove that someone else is reusing your code the way you meant them to.

  And neither do integration tests, because if someone is reusing your code, integration tests are their tests. Integration tests are tests to prove that they have glued their code on top of your code in a way that they are happy with.

  Simple pre-condition checks at the start of your functions and methods are your best opportunity to test how someone else is reusing your code, and to tell them if they’re getting it wrong.

Programming contracts are about building trust (just like unit tests). Code that you can trust is normally code that is quicker to work with. They’re really quick to write (normally far quicker than unit tests), and they can make it really quick to track down the origin of bugs in your code.

Don’t Programming Contracts Make Code Stupidly Strict?

An appropriate amount of strictness is a requirement of all high-quality code. The trick is knowing what to be strict about. Not strict enough, and you let in shitty data that causes your code to fail or be insecure. Too strict, and people will think that your code is too much trouble to work with.

As a general rule, pre-conditions should check for:

• data that’s in an incorrect format
• data that’s out of range
• data that’s missing

Post-conditions should check the same things. They can also be used to check for data that should have been changed, but hasn’t been changed.

Aren’t Programming Contracts Too Old-Fashioned For PHP?

The concept has been around for decades. As a C programmer, I first learned about programming contracts in the early 90′s, when I was writing code that had to run for months at a time with zero downtime. We were debugging and improving code dating back from the 1980′s, and introducing programming contracts played an important role in getting to the bottom of many of the bugs that users reported.

PHP code (and other modern languages like Java, Ruby, Scala etc) is fundamentally similar to older languages like C, although you may not realise that this is the case. It’s the same fundamental paradigm – data is passed into blocks of software, and blocks of software may also pass data out too.

The advantage we have with PHP is that our programming contracts don’t have to be as lengthy as they would for a C program, because PHP itself can enforce type checks through type hinting, and we don’t have to worry about low-level details like proper handling of null-terminated strings.

Examples

You can take a look at ContractLib’s unit tests on GitHub.

I’ll post some detailed examples in my next blog post.

What’s New In This Release

• Snapshot versions of components – not ready to release a stable version of your component, but still need to publish your component to your PEAR channel for testing? You can now set the project.snapshot property in your build.properties file, and get non-stable packages for distribution.
• Code coverage improvements – when you run phing test to run your component’s unit tests and generate the code coverage report, the code coverage report now automatically picks up all of your component’s PHP code, regardless of whether there is a test for it or not.
• phpunit.xml support – phix now puts a phpunit.xml file inside your component, which includes all of the settings required to execute your component’s unit tests. This should help TextMate users a lot. This change was requested by attendees at the PHPNW11 conference.
• More hooks in build.local.xml – for every target in your component’s build.xml file, you can now add “local.<target>” in build.local.xml, to perform any additional steps that you want to do. This feature was contributed by Martin Wernståhl.
• Usability improvements – your component’s build.xml file now traps more errors than before, hopefully making it even easier to learn how to work with components.

How To Upgrade

To upgrade from an earlier release of Phix, please do the following:

sudo pear clear-cache
sudo pear upgrade phix/phix4componentdev

Once you’ve upgraded phix itself, don’t forget to go into each of your components, and run

phix php-library:upgrade .

to upgrade all of the skeleton files (build.xml et al) for your component.

What’s Coming In Phix 0.15

Phix 0.15 is all about making sure that Phix works as well on Windows as it already does on Linux and OSX. The feedback from the ZendCon session (which I was gutted to be unable to attend) was that there isn’t much needed, mostly setup instructions. Once that is done, we’ll continue to support Phix on Windows just as we already do on Linux and OSX.

Our roadmap for Phix 0.15 has all the details.

My last set of photos from PHP North West 2011 are the odd ones out, the ones that didn’t really fit into any of the other sets.

I hope you’ve enjoyed my photos from the conference, and maybe – just maybe – they’ve made you think about going to a PHP conference somewhere near you in the near future.