Setting Up PHPUnit

I've put off setting up unit tests for my code far too long. I am ashamed. I've set aside this entire month to do all these things that appear like luxuries to non-developers, even though they're really essential.

For those of you who haven't been following, this is a Windows installation. I'm attempting to install the latest and greatest PHPUnit3 (3.2.4 at the time of this writing). It seems that either no one cares about doing this on Windows or only really smart people who find it so simple that they didn't bother to write about it have ever done it. Because half way through writing this (after publishing it half-done), I searched for "installing phpunit on windows" and this very blog article came up on the 2nd page.



Nice going Google, but not very helpful.

Quick Summary

For the impatient, here's a quick summary of what I had to do. Afterwards is the detailed story of how I got to this. I assume you already have PHP installed in C:\php.

1. C:\php>go-pear.bat
   
2. Merge C:\php\PEAR_ENV.reg
   
3. C:\php>pear channel-discover pear.phpunit.de
   
4. Change memory_limit in php.ini to something high like 64M. (Remember the old setting.)
   
5. Save php.ini. Restart Apache.
   
6. C:\php>pear install --alldeps phpunit/PHPUnit
   
7. Change memory_limit in php.ini back to what it was before. (The default is 8M I think.)
   
8. Save php.ini. Restart Apache.
   

Detailed Story

Now for the detailed story of how I got to the above steps.

1. Install PEAR
   I currently have PHP 5.2.3 installed, and I installed PEAR on 8 December 2007 getting the following output accepting the default options.
   
   C:\php>go-pear.bat
   
   Are you installing a system-wide PEAR or a local copy?
   (system|local) [system] : system
   
   Below is a suggested file layout for your new PEAR installation. To
   change individual locations, type the number in front of the
   directory. Type 'all' to change all of them or simply press Enter to
   accept these locations.
   
   1. Installation base ($prefix) : C:\php
   2. Temporary directory for processing : C:\php\tmp
   3. Temporary directory for downloads : C:\php\tmp
   4. Binaries directory : C:\php
   5. PHP code directory ($php_dir) : C:\php\pear
   6. Documentation directory : C:\php\pear\docs
   7. Data directory : C:\php\pear\data
   8. Tests directory : C:\php\pear\tests
   9. Name of configuration file : C:\WINDOWS\pear.ini
   10. Path to CLI php.exe : C:\php\.
   
   1-10, 'all' or Enter to continue:
   Beginning install...
   Configuration written to C:\WINDOWS\pear.ini...
   Initialized registry...
   Preparing to install...
   installing phar://go-pear.phar/PEAR/go-pear-tarballs/Archive_Tar-1.3.2.tar...
   installing phar://go-pear.phar/PEAR/go-pear-tarballs/Console_Getopt-1.2.2.tar...
   
   installing phar://go-pear.phar/PEAR/go-pear-tarballs/PEAR-1.5.4.tar...
   installing phar://go-pear.phar/PEAR/go-pear-tarballs/Structures_Graph-1.0.2.tar...
   pear/PEAR can optionally use package "pear/XML_RPC" (version >= 1.4.0)
   install ok: channel://pear.php.net/Archive_Tar-1.3.2
   install ok: channel://pear.php.net/Console_Getopt-1.2.2
   install ok: channel://pear.php.net/Structures_Graph-1.0.2
   install ok: channel://pear.php.net/PEAR-1.5.4
   PEAR: Optional feature webinstaller available (PEAR's web-based installer)
   PEAR: Optional feature gtkinstaller available (PEAR's PHP-GTK-based installer)
   PEAR: Optional feature gtk2installer available (PEAR's PHP-GTK2-based installer)
   
   PEAR: To install optional features use "pear install pear/PEAR#featurename"
   
   ******************************************************************************
   WARNING! The include_path defined in the currently used php.ini does not
   contain the PEAR PHP directory you just specified:
   <C:\php\pear>
   If the specified directory is also not in the include_path used by
   your scripts, you will have problems getting any PEAR packages working.
   
   
   Would you like to alter php.ini <C:\php\php.ini>? [Y/n] : Y
   
   php.ini <C:\php\php.ini> include_path updated.
   
   Current include path : .
   Configured directory : C:\php\pear
   Currently used php.ini (guess) : C:\php\php.ini
   Press Enter to continue:
   
   ** WARNING! Old version found at C:\php, please remove it or be sure to use the
   new c:\php\pear.bat command
   
   The 'pear' command is now at your service at c:\php\pear.bat
   
   
   * WINDOWS ENVIRONMENT VARIABLES *
   For convenience, a REG file is available under C:\php\PEAR_ENV.reg .
   This file creates ENV variables for the current user.
   
   Double-click this file to add it to the current user registry.
   
   Press any key to continue . . .
   
   C:\php>
   
   
   I then merged the PEAR_ENV.reg file as specified.
   
   You should make sure that running pear at the command-line dumps a list of commands.
   
2. Install PHPUnit
   
   C:\php>pear channel-discover pear.phpunit.de
   Adding Channel "pear.phpunit.de" succeeded
   Discovery of channel "pear.phpunit.de" succeeded
   
   C:\php>pear install phpunit/PHPUnit
   Did not download optional dependencies: pear/Image_GraphViz, pear/Log, use --alldeps to download automatically
   phpunit/PHPUnit can optionally use package "pear/Image_GraphViz" (version >= 1.2.1)
   phpunit/PHPUnit can optionally use package "pear/Log"
   phpunit/PHPUnit can optionally use PHP extension "pdo_sqlite"
   phpunit/PHPUnit can optionally use PHP extension "xdebug" (version >= 2.0.0)
   downloading PHPUnit-3.2.4.tgz ...
   Starting to download PHPUnit-3.2.4.tgz (198,003 bytes)
   .........................................done: 198,003 bytes
   
   Fatal error: Allowed memory size of 8388608 bytes exhausted (tried to allocate 73 bytes) in C:\php\PEAR\PEAR\PackageFile\v2\Validator.php on line 1021
   
   C:\php>
   
   
   Now what?
   Did it seriously run out of memory?
   ...I'll finish this post another day (tomorrow?), and hopefully I'll figure it out.
   
   ::day passes::
   
   ...Okay, I'm back. After checking my php.ini file, I found that the memory limit was indeed 8M. So I changed
   memory_limit = 8M
   to
   memory_limit = 64M
   
   Save, and restart Apache (necessary if you're running PHP as a module).
   
   This time I decided to use the --alldeps option as indicated by my last run. If PHPUnit can use GraphViz to make pretty output, that would be great. So here goes another shot.
   
   C:\php>pear install --alldeps phpunit/PHPUnit
   WARNING: "pear/DB" is deprecated in favor of "pear/MDB2"
   phpunit/PHPUnit can optionally use PHP extension "pdo_sqlite"
   phpunit/PHPUnit can optionally use PHP extension "xdebug" (version >= 2.0.0)
   pear/Log can optionally use PHP extension "sqlite"
   downloading PHPUnit-3.2.4.tgz ...
   Starting to download PHPUnit-3.2.4.tgz (198,003 bytes)
   .........................................done: 198,003 bytes
   downloading Image_GraphViz-1.2.1.tgz ...
   Starting to download Image_GraphViz-1.2.1.tgz (4,872 bytes)
   ...done: 4,872 bytes
   downloading Log-1.9.11.tgz ...
   Starting to download Log-1.9.11.tgz (38,479 bytes)
   ...done: 38,479 bytes
   downloading DB-1.7.13.tgz ...
   Starting to download DB-1.7.13.tgz (132,246 bytes)
   ...done: 132,246 bytes
   downloading MDB2-2.4.1.tgz ...
   Starting to download MDB2-2.4.1.tgz (119,790 bytes)
   ...done: 119,790 bytes
   install ok: channel://pear.phpunit.de/PHPUnit-3.2.4
   install ok: channel://pear.php.net/Image_GraphViz-1.2.1
   install ok: channel://pear.php.net/Log-1.9.11
   install ok: channel://pear.php.net/DB-1.7.13
   install ok: channel://pear.php.net/MDB2-2.4.1
   MDB2: Optional feature fbsql available (Frontbase SQL driver for MDB2)
   MDB2: Optional feature ibase available (Interbase/Firebird driver for MDB2)
   MDB2: Optional feature mysql available (MySQL driver for MDB2)
   MDB2: Optional feature mysqli available (MySQLi driver for MDB2)
   MDB2: Optional feature mssql available (MS SQL Server driver for MDB2)
   MDB2: Optional feature oci8 available (Oracle driver for MDB2)
   MDB2: Optional feature pgsql available (PostgreSQL driver for MDB2)
   MDB2: Optional feature querysim available (Querysim driver for MDB2)
   MDB2: Optional feature sqlite available (SQLite2 driver for MDB2)
   To install use "pear install pear/MDB2#featurename"
   
   C:\php>
   
   
   It looks like it worked. :-)
   
   Run phpunit at the command-line to test that it worked. You should get a version and usage message dumped.
   
   Change the memory limit back to 8M. Save, restart.
   
3. Test the Test Framework
   To further test that my installation was actually working, I made a dummy test that always fails. Like so...
   
   <?php
   require_once 'PHPUnit/Framework.php';
   
   class DummyTest extends PHPUnit_Framework_TestCase {
   
   public function testFail() {
   $this->fail('Your test successfully failed!');
   }
   
   }
   
   
   ...and put it in my C:\ root directory as DummyTest.php. This way I can make sure my path is setup correctly to use PHPUnit from anywhere.
   
   Sure enough, I get some good test-output.
   
   C:\>phpunit DummyTest
   PHPUnit 3.2.4 by Sebastian Bergmann.
   
   F
   
   Time: 0 seconds
   
   There was 1 failure:
   
   1) testFail(DummyTest)
   Your test successfully failed!
   C:\DummyTest.php:7
   
   FAILURES!
   Tests: 1, Failures: 1.
   
   C:\>
   
   
   

That's it! I hope this is helpful to someone.

Updated ZF .htaccess

A while back, I talked about how to setup a bootstrap on Apache to use with ZF. Since then, I've made a few modifications to my .htaccess file that I think are worth documenting.

First of all, I ran into a problem where flash files were referencing other binary files (.swf and .flv) relatively. But with ZF's URL rewriting, this was getting totally messed up, and only certain components of Flash objects were showing up. The fix I needed was in the .htaccess RewriteRules. The new rules I have are like so.

RewriteEngine on
RewriteBase /

RewriteRule !\.(js|ico|gif|jpg|png|css|flv|swf)$ index.php

Of course, if I had read the updated ZF documentation, I would have already known that.

Another "fix" I've used in my .htaccess file has to do with caching. Back in the day when websites were static, site-wide .css files were great. Not only did it allow for updating the entire site in one place, but it allowed browsers to cache the CSS so downloading pages that used it was even faster.

Problem: What if you add a feature to your site which requires new style rules. Since browsers have cached the .css file, any updates to it won't be seen until either the browser decides to refresh its cache or the user specifically Refreshes. Having that designer blood in me, I just can't stand the thought that some people will view that new feature without having the styles for it.

I came up with a bunch of ways to fix this, and they all suck in one way or another. One method that is particularly appealing to me as a programmer is to ditch browser-level caching by making everything a page style (in a style tag in the head of every page). This way, when a browser gets updates to a page, it will also get the updates to the CSS, and they will always be in sync. If you want to keep the ability to change one thing and change the whole site, simply move common CSS rules into a separate file which is included by your PHP.

The way we ended up doing it though — since my designer wanted to avoid PHP as much as possible — was with a .htaccess modification. The idea was that we wanted to disable browser-level caching of .css files. So I added the following to our .htaccess file which tells browsers to only cache .css files for 5 minutes.

<IfModule mod_headers.c>

# Cache library files for 5 minutes
<FilesMatch "\.css$">
Header set Cache-Control "max-age=300"
</FilesMatch>

</IfModule>

The nice thing about this is Apache simply adds a header to all your .css files without you having to modify anything in your code.

Peculiar Workarounds

I just wanted to capture some miscellaneous workarounds that I've had to use while creating a site in PHP on a shared host.

For now, I've just been using a shared Linux hosting plan. (BTW, don't ever use 1&1! Besides being terribly slow and going down randomly for hours in the middle of the day, their support is just atrocious. I once had a problem scheduling cron jobs, so I decided to email them for help. Their reply was of no use. I ended up figuring it out on my own though, so I sent another email to them to tell them how I solved the problem — the crontab file needed a newline at the end. They completely didn't get what I was saying and acted as if I was still having a problem.)

And on this shared host, PHP5 is run as a cgi. Running phpinfo(), I found that in order to modify the php.ini settings, you had to include the php.ini file in every directory. (Be careful. A php.ini file overrides all settings, and defaults are used for unspecified settings. It doesn't extend the current settings.) So I made a script that copies the php.ini file I made into every subdirectory.

An alternative if you're using a bootstrap file, is to set the ini settings programmatically in the bootstrap using ini-set.

Another peculiar problem I found on this shared host using the Zend Framework had something to do with the rewriting of URLs. When I had a controller named Posts and tried to go to a URL like /posts/view, it would work perfectly on my server but would give a 404 on the shared host. I actually already mentioned this at the end of another post, but I thought it should be pointed out because I just know this is the kind of thing I will forget about and spend hours trying to fix again.

The workaround I found was to create a dummy directory called posts (or whatever your controller is named) and duplicate the RewriteRules in a .htaccess file in that directory. In other words, something like this:

RewriteEngine on
RewriteBase /

RewriteRule !\.(js|ico|gif|jpg|png|css|flv|swf)$ index.php

I think it had something to do with the fact that I was using Apache 2.0 while the shared host was using 1.x. On the shared host, it was looking for a directory called posts instead of using the RewriteRules in the .htaccess file in the web root directory.

Zend Framework Overview

Bootstrapping

All requests are sent to a single application entry-point. The bootstrap file loads classes and libraries common to all pages on the site. It then does things that need to be done for every request like setting up the database with Zend_Db or loading permission rules via Zend_Acl or starting the session with Zend_Session. It then creates an instance of the Zend_Controller_Front class which is used to dispatch the request to the correct controller and return the response to the client.

For objects that may need to be accessed by controllers or other classes after dispatching, a registry has been created. The bootstrap file can create objects with complicated initialization, possibly utilizing config files, and store these objects in the registry with the Zend::register function. Values can then simply be pulled out of this at will with the Zend::registry function. The advantage of using this over globals is that it is clear whenever you are accessing a shared variable, which can be especially important with PHP's lack of variable declaration. (Although, if you stick to an all-object-oriented design, this might not be a problem.) Additionally, the Zend_Registry class can be subclassed, allowing for exotic data structures, logging of registry use, persistence, etc.

// Create the view and store it for later use.
$view = new Zend_View();
$view->setScriptPath('./application/views');
Zend::register('view', $view);

Controllers and Actions

Every valid URI must have a corresponding action that is executed when it is requested. If the router does not find one, an exception is thrown — either an instance of Zend_Exception or one of its subclasses like Zend_Controller_Exception. The current default router, implemented in the Zend_Controller_Router class, matches URIs against the pattern "/controller/action/param1/value1/param2/value2". There can be zero or arbitrarily many parameters. If the action is omitted, it defaults to the index action, and if the controller is omitted, it defaults to the index controller. The parameters are stored in an array that can be accessed via the _getParam or _getAllParams methods of the Zend_Controller_Action class, the class which all controllers must subclass. Trailing slashes are ignored, mapping to identical actions with identical parameters.

To map a URI to an action method, first create the controller class by postfixing its name with "Controller" and extending Zend_Controller_Action. In this class, any method named with the postfix "Action" will be mapped to a URI. For example, to create a handler for the URI "/" — which gets routed to the index action of the index controller — we need a class named IndexController that extends Zend_Controller_Action, with a method named indexAction. In order for the framework to load this class automatically, put this class definition in a file named IndexController.php your controller directory — /webroot/application/controllers/ if you're using the standard bootstrap file I described.

<?php

class IndexController extends Zend_Controller_Action
{
// Handles "/", "/index", "/index/", "/index/index", "/index/index/"
public function indexAction()
{
}

// Handles "/index/foo", "/index/foo/"
public function fooAction()
{
}
}

Regardless of how many parameters are expected, action methods are always called with zero parameters. But parameters specified in the URI can be accessed with _getParam and the like. For example, if /index/index/param1/value1/ were requested, $this->_getParam('param1') in the indexAction method would return 'value1'.

To handle the URI /downloads/list, create a file named DownloadsController.php in the controllers directory. Make a class named DownloadsController extending Zend_Controller_Action, and in it, create a method named listAction.

<?php

class DownloadsController extends Zend_Controller_Action
{
// Handles "/downloads/list", "/downloads/list/"
public function listAction()
{
}
}

When you echo or print in an action method, the output is sent in the body of the response to the client. The Zend_Controller_Response_Abstract class was created to abstract over this and allow for easy switching between output formats, say, from XML to JSON. The interface though is a little annoying since

echo coolStuffToOutput($howCool);

becomes

$this->getResponse()->appendBody(coolStuffToOutput($howCool));

which is much clumsier. One might argue that this method of outputting shouldn't be used often anyway since most output will be part of a template and output using a view.