PEAR + PHPUnit on Windows

Windows? Yes, I know. No one does real development under Windows unless they’re either insane or one of those weird types who likes (and I mean really likes) Powershell. Sure, I’ll grant them that .NET is reasonably well done, but I’d counter that anyone who’s used a proper shell (I see Powershell as a hybrid REPL/shell for .NET) and done it the Unix Way would soon find that Windows feels quite anemic. I’m biased; I confess that I essentially use Windows only for games these days, and my Real Development occurs under Arch Linux (with apologies to Gentoo). That said, there are some useful tools and utilities that can coexist under both but often with some unnecessary frustration on the Windows front unless you install 3rd party package managers. There are a few good ones available for basic needs, but it’s something a stock Windows install sorely lacks–unless, of course, you have a strong affinity for Microsoft products. And no, before you ask, I don’t think the promise of an app store with Windows 8 will bridge the gap. Windows 8 is a whole ‘nother can of worms…

PHPUnit is probably the de facto standard unit testing suite for PHP5.2+. It’s also easiest to install using PEAR, but as of this writing, PEAR is not installed with the PHP for Windows distribution. Worse, a cursory Google search for running PEAR on Windows and, more importantly, installing PEAR apps like PHPUnit yields mostly unhelpful results. Sure, there’s a few moderately helpful links here and there, but most of them seem to link to other blogs, probably with the intent to siphon off some Google juju for themselves. There’s even one such result that appears to be a domain that was once hijacked and taken over by spammers. Also, the Stack Overflow results are oddly unimpressive.

Bummer.

So, here’s my answer to the doldrums, but mostly so that I can reference this instructional write up in the future should the need arise. Indeed it probably will given my terrible memory.

Install Pear

First, don’t listen to anyone else. Second, listen to your instinct. It is possible to install pear, and it is possible to get the PEAR script running perfectly fine such that you can use it from cmd.exe, just as you were suspecting all along. It’s also exceptionally easy; simply follow the standard installation instructions to install pear (but with some minor twists!). Also, if you’re afraid something could go wrong and bork your PHP installation, make a backup of your PHP installation folder prior to installing PEAR. I emphasize this point because it most certainly will happen. Remember: The necessity of a backup increases asymptotically as the difficulty of restoring such data also increases, up to and including the point where there is no such backup.

Here’s what you’ll need to do:

  • Download and install go-pear.phar from pear.php.net. You may also need to modify your php.ini in order to get PHARs working, but I’m fairly certain it ought to work from a stock PHP installation.
  • When the installer runs, correct the paths it prompts for as appropriate for your particular situation; be aware that if you don’t want pear.ini in your Windows directory, you will need to change this! For the most part, it should automatically locate everything it needs.
  • Update your environment variables as hinted by the installer.

Now, for that last bit, you can either merge the PEAR_ENV.reg registry entries as hinted by PEAR’s installer or, if you’d rather do it by hand, you can add these–modifying where appropriate:

  • PHP_PEAR_SYSCONF_DIR=C:\php – Should be the root of your PHP install.
  • PHP_PEAR_INSTALL_DIR=C:\php\pear – Should be the root of your PEAR install.
  • PHP_PEAR_DOC_DIR=C:\php\docs – Presumably, this is where PEAR apps will dump their documentation, if requested or required.
  • PHP_PEAR_BIN_DIR=C:\php – Path containing your pear.bat script.
  • PHP_PEAR_DATA_DIR=C:\php\data – PEAR’s data directory. Various odds and ends get lumped in here, including licenses.
  • PHP_PEAR_PHP_BIN=C:\php\php.exe – Obviously, your PHP binary.
  • PHP_PEAR_TEST_DIR=C:\php\test – PEAR applications will stick their unit tests into this directory.

Now, obviously, you could probably have a working PEAR install without setting all of these. I wouldn’t recommend it, though. You’re apt to encounter a package that really wants to distribute documentation (or license text), and if you’ve installed PHP in a location that PEAR doesn’t expect as a reasonable default, well, you can guess that this probably won’t work.

At this point, you’re probably curious to see whether or not PEAR is working. To check this, fire up a command prompt and run pear help or similar. If it runs, you should be OK. If it fails, you probably skipped a step. Don’t worry if you do. It should be fairly easy to fix, but you might have to remove every directory except dev and ext from your PHP install and start from the beginning. If you’re paranoid, make a backup of your PHP installation folder prior to installing PEAR. I said this already, didn’t I?

Installing PHPUnit

Here’s the fun part. If you’ve successfully managed to install PEAR and pear help hasn’t griped, this step will either be exceptionally informative and hint that you skipped something or it will work. If you encounter trouble installing PHPUnit via PEAR, you most likely forgot to configure the appropriate environment variables; check these first, ensure they’re correct, and close/reopen all command prompts.

Otherwise, simply running:

pear config-set auto_discover 1
pear install pear.phpunit.de/PHPUnit

Should work, and you’ll have a PHPUnit install that also works. Try it out with: phpunit –help!

At this point, you should be able to continue forward, run your unit tests under Windows, fix any breakage that results (trust me, you’ll probably have some if you weren’t developing with Windows in mind–and sometimes even if you were), and commit changes where appropriate. Believe me when I say it: Some things should just work out of the box, but there are others that will spectacularly fail even if you used DIRECTORY_SEPARATOR everywhere in your paths (though it shouldn’t matter) and were careful to avoid non-Windows-only extensions.

But hey, that’s what you wrote those unit tests for, right?

No comments.
***