Digital Darkness

Unit testing headers in PHP

2015-02-23T15:54:00.000-06:00

There's plenty of questions about unit testing code that sets headers using PHPUnit. PHPUnit officially assumes that neither the test code nor the tested code emit output or send headers:

(from https://github.com/sebastianbergmann/phpunit/issues/720#issuecomment-10399612)

And rightfully so. Headers are essentially global state, which is hard to unit test. However, if you're willing to install the PECL extension Runkit, you can actually unit test headers if you really want to.

I use the setupBeforeClass hook to only run the code once before the entire class runs. If you only have one method that you're testing it can all get stuck in the single test. I check if the runkit extension is loaded to avoid breaking the unit test suite if someone tries to run it that doesn't have runkit installed. The test that actually looks at the headers is marked with a requires annotation, which will mark that test as skipped if runkit isn't loaded. If every test in your test class tests headers, you can move that up to the class level if you'd like. My particular class had some tests that didn't need runkit and I wanted those to still run for people that didn't have runkit loaded.

Public key crypto

2014-03-24T09:00:00.000-05:00

I recently received an invite for keybase.io. For those of you that haven't looked into it, it boils down to a public repository of public keys attached to certain geeky identities (Github and Twitter, for now). It's a new way to build a web of trust.

Where keybase.io shines

It is easy (relatively speaking) to install the tools and create your identity. It's easy (again, relatively speaking) to verify your identity on the two public sites that they've picked for verification. The UI is much prettier than the open keyservers that we already had. For example, keyserver.ubuntu.com is obviously written by geeks, for geeks as is pgp.mit.edu.

It's easy enough to invite your friends (if you have invites, that is) and publicly track them.

The most important piece that Keybase brings to the table is some minimal verification. With the public keyservers, you generate a key attached to an email address, then upload it to a keyserver. There's nothing that verifies that you actually own that address. With Keybase you've got a key attached to an email address and to a Twitter account and a Github account.

Where keybase.io fails

Unfortunately, this is a longer list.

It is relatively easy to install. It is far from easy. It requires command line access and node installed, which is far from trivial for non-geeks.

They don't really tell you what tracking means. When you track someone, you're saying that you vouch for their identity. There are plenty of people that I "know" on Twitter that I've never met in real life. They may or may not be who I think they are.

They encourage you to upload your private key to their server. You should never give your private key out to anyone, no matter how much you may trust them. They make a big deal about how they encrypt it and never see it, but you're expected to just trust them. They seem on the level, but for all that I know they're nothing more than a front for the NSA to get your private keys.

Once you've connected with others and verified their identity, what then? For most people, cryptography is another step in the way of communicating with people. I doubt Keybase will convince many people to start encrypting their communications. Hopefully it will at least convince people to start signing their git commits. But without a plugin for Gmail and Outlook, I doubt many people will even be bothered to sign their emails, much less encrypt them.

While it's easy enough to connect to people you know once you find them, it's not particularly easy to find them in the first place. This might be just because it is still in alpha. Hopefully they'll allow you to search your Twitter friends. Seems like an oversight since Twitter is one of the ways to verify your identity.

Overall thoughts

I doubt Keybase will ever fully replace the existing public key infrastructure. It's pretty easy to verify identities there, but there's not much value-add over a prettier front end to the existing solutions. I hope there's a lot more to come as it leaves alpha.

That being said I really hope that it takes off in a big way. Our email may be sent in the clear and stored in the clear. It was never really designed to avoid being read by third parties. Hopefully recent disclosures about the NSA make people realize that their communications are not safe. If just one more person protects their communications from spying, Keybase will have been a success in my eyes.

Midwest PHP 2014 wrap up

2014-03-18T13:00:00.000-05:00

Let's get the negative stuff out of the way first. It was cold. Like, really cold. And I'm a wimp when it comes to the cold.

Whew. Thanks for struggling through all of that. With that out of the way, let's talk about how awesome the conference was. This was the second year I was invited to speak, so I'll also do some comparing with 2013's conference.

Location, location, location

They moved into the city to a bigger college. It was a big improvement over last year's venue. The rooms were big enough for the audience and had plenty of power in the two smaller rooms. I only heard one speaker mention having A/V trouble: two sets of dead batteries for the microphone. I had a bit of trouble figuring out which building the conference was in, but once I did, it was easy to get from session to session.

The food was pretty good as well, with soft tacos the first day and sandwiches the second. They took good care of those with special dietary needs as well.

The after party's location was very intimate, and really helped to mix up the speakers and attendees, which I feel very strongly about. I talked to every single person at the after party except for the people sitting down around the edges.

Content is king

The worst talk that I saw was still very interesting to me. The selection of speakers was fantastic in both breadth of topics and depth of knowledge. The only knock I have on the list of speakers is that it's pretty much the same group of speakers you see at other conferences such as SkiPHP and Lone Star PHP. The community really wants you (yes, you) to start speaking at your local user group and then at conferences. Trust me, you've got some knowledge worth sharing and can do this.

And for some reason, I spoke as well. Despite my fear of public speaking and my nerves almost derailing my talk, it went over very well. The attendees were very welcoming and friendly.

Conferences can be so humbling to see the amazing stuff that people are doing and willing to share with you. Many of the speakers literally wrote the book on their topic. You can see them talk about it, and then chat with them about it more afterwards. That's just amazing to me.

The Atmosphere

Wow. So energy. Much connections.

The attendees were a friendly bunch, and the hallway track seemed to be on fire. The IRC back channel was very talkative, owing to some well-timed tweets to get new people on to Freenode to join the conversation that.

Overall Impression

I really hope that certain non-MidwestPHP events don't conspire to keep me from being able to submit a talk to Midwest PHP 2015. I really like this conference, the people, and the experience and would love to come back next year.

Coding for easier and quicker code reviews

2014-02-13T09:54:00.000-06:00

If your company doesn't do code reviews, you most certainly should. If you're bound and determined to ship crappy software by not doing reviews, this post won't do much for you.

Code is meant to be read

Many people are under the mistaken impression that their code is meant for the computer's consumption. While it's true that a computer will consume your code, it is not who you're writing for. Programmers are your intended audience. That includes you. Coding a new project is the easy and short part of the software's lifecycle compared to the time code spends in the maintenance and upkeep phase.

So, assuming that you want to write code that's easier to read as well as easier to review, here's a few tips. All of them come from dealing with real coworkers. If you've worked with me and recognize something that you still do, you should feel bad. You're probably the reason I wrote this.

Descriptive variable names

Yeah, that's just good software development practice, but it can really help during code reviews as well. A short variable name that doesn't describe what it does is much harder to figure out during a code review since most review tools (at least that I've used) don't give a huge amount of context around the change. So while someone going in to edit the code might quickly figure out what the variable is supposed to contain, a reviewer has to dig.

Exceptions: Obviously loop control variables should be short ($i, $j, $k) as well as variables that use a single letter commonly, like representing coordinates ($x, $y, $z).

Useless commit messages

"Fixed a bug" or "Made change suggested in review #1234" are nearly useless. While they may be factually correct, they don't really tell the review what and why you're changing something. In the first case, the reviewer has to figure out what the bug was before they can decide that you've fixed it (and fixed it in the best way). In the second case, they have to go back to the original review to figure out what the suggested change was (and whether it was a good idea in the first place) before they can determine whether you'd fix the original problem.

Exceptions: If you've got a code sniffer (PHPCS, for example) that complains about things, having a commit message of "PHPCS" is plenty clear that you're appeasing PHPCS.

Trailing commas

This one is a bit controversial, especially if you frequently switch between PHP and javascript. PHP allows trailing commas for arrays while certain paste-eating browsers don't allow it in their javascript parsers. Creating an array with the trailing comma makes later reviews easy to read. For example, if you have an array like:

$letters = array(
'a',
'b',
'c'
);

and you need to add a new letter:

$letters = array(
'a',
'b',
'c',
'd'
);

code review packages will show two changed lines:

$letters = array(
'a',
'b',
'c',
'd'
);

If you always include the trailing comma it makes it obvious during the review that you're only intending to add a new element. This is a trivial example, but it helps to show your change's intent better, which helps a reviewer better understand what you're doing.

Code reviews are meant to help you

Don't get your feelings hurt when someone points out mistakes that you've made. Everyone is trying to get better. If you send shorter review requests that are easy to read, it's much more likely that you'll get responses quickly and with less confusion.

Conference speakers, come out of your towers

2014-02-10T08:55:00.000-06:00

I'm not a great speaker. Heck, out of the hundred or so that I've seen since I started speaking at conferences I'm not sure I would even rate myself in the top 80. But I have noticed a few things that speakers could do to improve the conference experience for both attendees and speakers. After all, conferences are (well, they should be) about the attendees, not the speakers.

Most speakers do a pretty good job of interacting with attendees that come up and talk to the after their session, or in the hallway track later. But that's about all of the interaction the general public gets.

That's not enough.

Many speakers are friends. They may be friends that only hang out with each other at conferences, but they look forward to seeing each other. They may have not seen each other since the previous conference, so they understandably want to catch up. So they sit together at meals, they group together in other sessions, and disappear into the speakers' lounge to talk privately.

That robs attendees of the chance to get access to you. The speakers' dinner, which most conferences have, is your chance to catch up. The rest of the time, speakers should work to make themselves available to attendees.

I pick random tables at lunch to sit at. The conversations are almost always as interesting as the ones going on at the speakers' tables (if not more so), but with new people.

SkiPHP Wrap Up

2014-02-06T08:55:00.000-06:00

The last weekend was the first year for another regional PHP conference called SkiPHP. Similar in many ways to other regional conference that I've attended (Lone Star PHP and Midwest PHP), SkiPHP was a fantastic opportunity for people local to the Salt Lake City area to attend a conference without having to miss (much) time from work for travel.

The speakers were typical for such an event, with a few new speakers sprinkled in among a subset of the typical PHP speakers. People from the PHP community looking to make the jump from speaking at user groups have a very good opportunity to speak at conferences such as these, and I encourage all of them to submit proposals. See what conferences have open CFPs at callingallpapers.com/.

The Venue

The conference was held at a college. This came with both some good points and some bad points. First, the rooms were all equipped with AV equipment that worked just fine. I didn't hear about any problems with the equipment, with the lone exception of a static-prone wireless mic.

The three smaller rooms had plenty of seats and tables. They were classrooms after all. Depending on the time of day, one of the rooms did have a problem with the sun causing glare on the screen, but the speaker and attendees were able to soldier through that without too much problem. They also didn't have much in the way of power outlets. My fancy power outlet came in very useful several times throughout the day.

The larger room was a lecture hall. I'm really glad I didn't have to speak in that room. It was set up for a professor to stand behind a podium and lecture, which none of the speakers that I watched in that room had any interest in doing. All of them wanted to get out from behind that thing, which I applaud. There really wasn't anywhere else that speakers could put their laptops and still interact with them for speaker notes and advancing slides.

The Talks

All of the talks I saw were fantastic. I made it a point to see some speakers that I had never seen before, and checked out some talks that were on subjects that I was very unfamiliar with. The only exception was the keynote, which was an updated version of the talk that Laura gave at Lone Star PHP 2013.

Unfortunately, looking through the joind.in pages for the talks, some of the speakers, especially the new ones, haven't claimed their talks, which makes me think that they're missing out on some of the feedback that people gave them. That's really important!

The Atmosphere

Overall, it was a much more focused conference. Many of the conferences that I've been to in the past were about making connections with other geeks and feeding off the combined energy of a room full of geeks to recharge your developer batteries first, and learning new things was cool too. Very few of the people that I talked to in the halls or at lunch seemed at all interested in connecting outside or after the conference. Perhaps I was just to brash for the average SkiPHP attendee.

Overall Impression

SkiPHP was a very well-run conference that I would recommend to anyone from the area. If I can fit it into my company's new stricter conference attendance policies, I will definitely try to return next year and hopefully hit the slopes while I'm there.

Keezer build

2013-07-03T17:57:00.000-05:00

I like beer. I like brewing beer. But I don't like having to bottle my beer. I also like draft beer, but don't have any way of getting draft beer at home so that I never have to venture out into the outside world.

I could just keg my beer one five gallon batch at a time, but my philosophy is that if it's worth doing it's worth overdoing. So I'm building a five keg system.

The freezer came from Home Depot. I normally don't do business with them because of their shady credit practices, but the deal was too good to pass up. The temperature controller was ordered from Amazon.com. Most of the other hardware came from Midwest Supplies, I spend way more money with them than I probably should. The CO2 tank and the Sanke tap were purchased from Kegs & Barrels. Paint and wood were purchased from Lowes. My first commercial keg came from Choice Beverage in McKinney.

Parts list

Freezer - $168
5 5/16" Gas Line Assembly - Ball Lock - $49.95
5 Chrome Faucet with Brass Lever - $79.95
2 5-Gallon Reconditioned Ball Lock Keg - $119.98
10 Plastic Tubing Spacer - $8.90
5 Ball Lock Liquid Disconnect, 1/4" Barbed - $29.95
5 Long Faucet Tap Handle - $12.45
5 3" Economy Shank w/o Nipple - $84.95
Shank Securing Wrench - $4.99
5 1/4" Stainless Beer Tail Piece - $12.50
10 O-Ring Set - $29.90
5-Way CO2 Distributor, 5/16" - $75.99
5 Neoprene Washer - $6.95
50 ft 3/16" ID Beer Line - $37.50
Double CO2 Regulator - $149.99
Domestic Keg Coupler - $39.99
STC-1000 Temperature Controller - $21.99
5lb CO2 tank - $109.99
5 hex nuts - $7.45 (Homebrew Headquarters)
2 3/4x12x72 stain grade panels (ie wood) - $31.94
3/4" Poly Panel Insulation - $9.80
2 Weatherstripping - $12.53
Extension cord - $8.47
1" hole saw - $5.88
Screws - $5.58
8 angle brackets - $20.56

The Build

Here's the freezer before it gets completely repurposed:

Cutting the wood with Jason's help:

Attaching some 90 degree brackets and cutting the insulation:

Drilling the one inch holes for the shanks:

Installing the shanks:

Attaching the back to the side:

Altogether now:

Attaching the gas distributor:

Backside of the installed shanks:

Faucets installed (Midwest backordered one of the shanks):

Wiring up the temperature controller:

Semi-finished product, I thought it was meant for me, but Scriptlet thinks it made a good bed. I had to take off the hinges. I'll add them back with another set at some point:

Inside after adding kegs and stuff. That's a keg of Omni's Hardly Workin' Ale and Lakewood's Temptress. There's also a fermenter with a batch of Omni's Employment Anchor Away.

Future improvements:

Resizing the collar. I didn't cut it to the right size, so it's too deep. Apparently I suck at math. I blame imperial units and the American education system.
Painting the whole thing very dark brown to match my office's furniture.
Installing the last shank when it arrives.
Mounting the temperature controller and a thermometer so I can see what's going on in there better and control it.
Installing a drip pan.
Adding more gas line. I bought pre-built gas lines from Midwest, but had to take two of them apart. One goes from the CO2 tank to the distributor, and one goes to the commercial Sanke tap.
Installing hinges. The lid will be hinged as well as the collar.
Tracking system to show the beers on tap as well as how much of each is available.

MidwestPHP Review

2013-03-06T08:00:00.000-06:00

It seems like smaller regional PHP conferences are popping up all over the place these days. While they don't have the budgets of the bigger conferences like ZendCon and |Tek, they do provide something those other conferences just can't: an intimate setting. The newest conference on the block is MidwestPHP. I've never been to Minnesota, but submitted two talks to them anyway. Both somehow got accepted and I had a blast at the conference, even while speaking (I'm terrified of public speaking, but it is getting easier). Here's some thoughts on the conference:

The Good

Organization - Many attendees that I talked to had no idea it was a first time conference run by first time organizers. Things went relatively smoothly. Kudos to Mike and Jonathan for a great job.
Speaker gifts - As a fan of craft brews, I appreciated a four pack from a local brewery.
Newer speakers - Smaller conferences with four tracks have space to take a chance on some new speakers, injecting some new blood into the speaking circuit. The PHP community seems to have the same speakers at many of its conferences. Midwest did a good job of mixing "big name" speakers (like Chris Hartjes) with relative newcomers (like me) as well as some first timers. Giving new people experience is great for the future since the larger conferences might feel safer accepting a talk from someone that has spoken before.
Attendees - It's great seeing so many people so eager to soak up knowledge. I made note of a few people at the beginning of the conference and mentally stalked them throughout. Unlike many conferences I've been to, they weren't always with the same group. Being willing to talk to random people at a conference is a great way to amplify your benefit from going to a conference.
The venue - Some intimate rooms as well as larger rooms, all with tables. Lots of wide hallways for the important between session discussions.

The Less Good

Speaker gifts - While I appreciate good beer, some people don't drink. And based on the four 4-packs I ended up with, some speakers weren't interested in carrying them home.
The venue - The rooms were very spread out and difficult to find at first even with the map. More signs directing people where to find where they're going would be very helpful. Also, as with most conference rooms, more power would be awesome.
No organized social - There were a few attendees that I would have liked to socialize with after the conference finished for the day, but with no social event to go to they just went home. So it ended up being just a bunch of the speakers socializing with each other. While the other speakers are cool and all, I already knew several of them. I'm not implying that the social needs to be a huge party, but just reserving a large room at a nearby restaurant would be cool.

The Ugly

The cold - I hate it. My thin Texan blood still hasn't warmed back up to my normal body temperature.
The snow - Delayed some flights and froze me even more. I admit it, I'm a wimp when it comes to the cold.

The Sessions

As for the sessions, with four tracks I obviously missed more sessions than I attended. Some sessions were easy for me to pick, like the ones where I was speaking. Some were easy for me to decide not to go to, like Chris's testing talk which is awesome, but I've seen it. There was a good mix of basic, intermediate, and advanced talks as well as a good mix of front-end and back-end talks. The talks I personally really enjoyed:

Scaling PHP with HipHop by Sara Golemon - Since the first time I heard about the HipHop project I've been fascinated by it, even though I never really had a reason to use it. Her talk was interesting from a historical and architectural perspective. Again, I'm probably still not going to have an excuse to run HipHop in production, I do plan on playing around with it.
Caching and Tuning fun for high scalability by Wim Godden - Great pointers for when and how to use caching, with some real world examples. Much of this would be immediately useful to sites trying to scale up.
Embrace Your Inner Designer by Josh Broton - This was a stretch for me, since I'm about as far from a designer as they get (I don't "do" pretty). But I actually feel like I gained something from it to make me a slightly less shitty designer. And Josh probably had the best delivery of any speaker that I saw. Just don't tell him I said that.

Overall, great conference. I learned a lot, met some great new people, and had a great time. I will probably make the trip up next year as well, though I may need a heavier ski jacket to protect me from the sub-zero temperatures.

Unit testing code that uses static methods

2012-03-12T09:00:00.000-05:00

Static calls are death to testability. There are ways of mocking out static calls made inside a class, but if you have some code that makes static calls outside a class, it's much more difficult. The best way is to refactor the static class to an instance class so you can mock things out.

But if you're working in a legacy code base with large and ugly static classes, refactoring them may be overly difficult or hard to justify from a business perspective. But you still want to test the new code that you're writing that uses those static classes. A coworker showed me one way to do it. It's still hacky and not as good as fixing the static class properly.

Basically instead of refactoring the crufty static code, you do the refactoring in the class you're writing. Here's an example class that uses the static Calculator class from above:

You can't mock out the Calculator class in this case. But you can make changes to your Foo class that will let you control the output from the static class. You can add protected methods to your class that call the static methods, and then mock those methods for testing and test the mock of the class you're testing.

Obviously this example is very simplistic, but in a more complicated class you could have the static class throw exceptions or different output or whatever.

Now you have two problems

This technique is far from perfect. If you were to change the behavior of the protected methods of your class, the unit tests would still pass, but the code would no longer work the same in production.

Unit testing Google Closure applications from the command line

2012-02-06T09:00:00.000-06:00

I've been playing around with building an application using Google Closure. I tried searching for a good way to run the unit tests from the command line as part of an Ant build, but either there wasn't anything out there to do what I wanted to do or I just couldn't find it.

As an aside, naming a language after a programming construct is really dumb. If you try searching for blog posts on Google Closure, you get a bunch of stuff about javascript and closures since they're such an important language concept. I think Prototype might have been a more successful language if they hadn't named themselves after a language construct as well, though the framework itself has its issues.

I'm used to writing code using test driven development, which doesn't work particularly well writing some Javascript. DOM-related code in particular is difficult to write with TDD. But there are parts of Javascript applications that can and should be well unit tested. When coding in PHP or Python, I normally have two terminal windows open for my Vim sessions and one for my build and source code management activities. I'll typically save the file I'm working on and them immediately alt-tab to the build window and hit up then enter to run my unit test target. I really wanted to do that with Javascript.

At my job we use jQuery. This comes with Qunit which is easy to run automagically with PhantomJS. But Qunit didn't look like it would be easy to make work with Closure in that it wouldn't handle the dependencies for me. And I might as well use the unit test framework for the library that I'm working with. I had a few goals. I didn't want my Javascript tests to fire up a browser. That kind of thing should be handled by Selenium. I wanted to be able to add new tests without having to manually add the test name to any file. I wanted the output to be at least somewhat pretty and clean, particularly if there were no failures. As a PHP developer I'm used to the PHPUnit output:

I decided to try to code up my own test runner to make this work. Here's the first version:

First, the build target concatenates all of the test files. In my case, test files are in a directory called tests and each of them ends with Test.js.

Next, it fires up the Closure Compiler. In this example, we've got a Javascript file called foo.js. We compile that with the concatenated test file (tests-concat.js) and the test runner (we'll get to that soon). The compiler creates a file called tests.js. We run that with phantomjs. The build will look something like this:

Most of the magic happens in testRunner.js:

Basically how it works is to override some methods in goog.testing.TestCase to capture the results. We don't particularly care about successes, so they're replaced by dots. Failures show as an F and any errors are explained in more detail after all tests finish.

I've uploaded all of the example code to Github at https://github.com/omnicolor/Closure-CLI-test-runner.

One assertion per test

2011-12-19T09:00:00.000-06:00

There's a right way and a wrong way to write unit tests. I've seen lots of wrong ways (like unit tests with no assertions) and differing shades of rightness. One thing that isn't really "wrong" but is not as right is writing your test cases with multiple assertions per test case.

Here's a simple example of a test with multiple assertions:

function testSomethingThatReturnsAnArray() {
$value = somethingThatReturnsAnArray();
$this->assertEquals('Foo', $value[0]);
$this->assertEquals('Bar', $value[1]);
$this->assertEquals('Mitz', $value[2]);
}

This could easily be rewritten to multiple assertions:

function testSomethingThatReturnsAnArrayFirstElement() {
$value = somethingThatReturnsAnArray();
$this->assertEquals('Foo', $value[0]);
}

function testSomethingThatReturnsAnArraySecondElement() {
$value = somethingThatReturnsAnArray();
$this->assertEquals('Bar', $value[1]);
}

function testSomethingThatReturnsAnArrayThirdElement() {
$value = somethingThatReturnsAnArray();
$this->assertEquals('Mitz', $value[2]);
}

What does this gain? You can immediately see whether somethingThatReturnsAnArray() is broken for all of the tests or just the first. With the first example, if $value[0] is not 'Foo', the test will immediately fail and you won't even test whether the next two elements are correct or not.

But the method I'm testing is slow!

If somethingThatReturnsAnArray() is so slow that you don't want to run it three times, you've got two options:

Make the method faster.
Only run it once per test suite run.

Obviously making the method faster would benefit your code the most overall, but it isn't always possible. But you can always just run it once, either by saving its output as a member variable of the test suite or making the tests depend on each other.

Saving the output is easy:

$result = null;
public function testSomethingSlowThatReturnsComplexResult() {
$this->result = somethingThatReturnsComplexResult();
$this->assertEquals('Foo', $this->result[0]);
}

public function testSomethingSlowThatReturnsComplexResultSecond() {
$this->assertEquals('Bar', $this->result[1]);
}

But there is a problem. Tests shouldn't require a certain order unless it is explicitly set. If you move the second test method above the first it will start failing. You could have a helper method that only executes the function once:

$result = null;
private function runSomethingSlow() {
if (!$this->result) {
$this->result = somethingThatReturnsComplexResult();
}
return $this->result;
}

public function testSomethingSlowThatReturnsComplexResult() {
$result = runSomethingSlow();
$this->assertEquals('Foo', $result[0]);
}

public function testSomethingSlowThatReturnsComplexResultSecond() {
$result = runSomethingSlow();
$this->assertEquals('Bar', $result[1]);
}

Now the slow function only is executed a single time, and the test methods don't have an unnamed dependency on any other tests.

But my method is really complicated!

If you have a very complicated method that has lots of dependencies, you may be tempted to test actions on all of the dependencies at the same time as well as the return value so you don't have to have all of the boilerplate code repeated. I've heard some otherwise very talented coders make this argument, which always surprises me. Test code is not really different from production code in that if you find that you're repeating code several times, it should be factored out into a method.

Let's try testing everything about this method:

function compareAppleToOrange(Apple $apple, Orange $orange) {
return array(
'sizeDifference' => $apple->getSize()
- $orange->getSize(),
'peelDifference' => $apple->getPeelWidth()
- $orange->getPeelWidth(),
);
}

You could test it all in one big test:

function testCompareAppleToOrange() {
$apple = $this->getMock('Apple',
array('getSize', 'getPeelWidth'));
$apple->expects($this->once())
->method('getSize')
->will($this->returnValue(4));
$apple->expects($this->once())
->method('getPeelWidth')
->will($this->returnValue(2));

$orange = $this->getMock('Orange',
array('getSize', 'getPeelWidth'));
$orange->expects($this->once())
->method('getSize')
->will($this->returnValue(3));
$orange->expects($this->once())
->method('getPeelWidth')
->will($this->returnValue(3));

$expected = array(
'sizeDifference' => 1,
'peelDifference' => -1,
);
$result = compareAppleToOrange($apple, $orange);
$this->assertEquals($expected, $result);
}

Better yet, you can test each piece on its own:

function testCompareAppleToOrangeSize() {
$apple = $this->getMock('Apple',
array('getSize', 'getPeelWidth'));
$apple->expects($this->once())
->method('getSize')
->will($this->returnValue(4));
$apple->expects($this->any())
->method('getPeelWidth');

$orange = $this->getMock('Orange',
array('getSize', 'getPeelWidth'));
$orange->expects($this->once())
->method('getSize')
->will($this->returnValue(3));
$orange->expects($this->any())
->method('getPeelWidth');

$result = compareAppleToOrange($apple, $orange);
$this->assertEquals(1, $result['sizeDifference']);
}

function testCompareAppleToOrangePeel() {
$apple = $this->getMock('Apple',
array('getSize', 'getPeelWidth'));
$apple->expects($this->any())
->method('getSize');
$apple->expects($this->once())
->method('getPeelWidth')
->will($this->returnValue(2));

$orange = $this->getMock('Orange',
array('getSize', 'getPeelWidth'));
$orange->expects($this->once())
->method('getSize')
->will($this->returnValue(3));
$orange->expects($this->any())
->method('getPeelWidth');

$result = compareAppleToOrange($apple, $orange);
$this->assertEquals(-1, $result['peelDifference']);
}

This allows you to change the peel calculation without touching the test for size, or the size calculation without touching the peel calculation.

If you wanted to really split the test up, you can go even further since the mocks provide some assertions of their own with the expects() calls. We'll split up the sizeDifference tests:

/**
* @return array Array from apples to orange comparison.
*/
function testCompareAppleToOrangeSizeCalls() {
$apple = $this->getMock('Apple',
array('getSize', 'getPeelWidth'));
$apple->expects($this->once())
->method('getSize')
->will($this->returnValue(4));
$apple->expects($this->any())
->method('getPeelWidth');

$orange = $this->getMock('Orange',
array('getSize', 'getPeelWidth'));
$orange->expects($this->once())
->method('getSize')
->will($this->returnValue(3));
$orange->expects($this->any())
->method('getPeelWidth');

return compareAppleToOrange($apple, $orange);
}

/**
* @depends testCompareAppleToOrangeSizeCalls
* @param array $result Result of comparison.
*/
function testCompareAppleToOrangeSize($result) {
$this->assertEquals(1, $result['sizeDifference']);
}

Each split gives you more information on a failure and makes debugging test failure easier as well as reducing the changes required for refactoring.

What's in a (method) name?

2011-12-12T09:00:00.000-06:00

Through my coding career I've come with some signs that the method I'm writing or reviewing probably needs to be refactored. These aren't hard and fast rules, but in general these are sniffs that something may be amiss.

Methods with 'or' or 'and' in their names

It's a pretty good sign that you're doing too much in a single method if it has the word 'and' in its name. For example, addMessageAndNotifyUser() should probably be split into two methods: addMessage() and notifyUser().

Methods with 'or' in their name aren't as easy to classify. If the whole method is just a single conditional, the method name may make perfect sense. I would argue that it is just poorly named.

Methods with almost the same name

If you've got multiple methods that all have basically the same name except for a useless word, you're probably making the code harder to understand. For example if you wanted to add a message, which of these would you call?

addMessage
addMessageProper
addMessageActual

If the first addMessage calls one of the other ones, is adding a message its main task? Could it be renamed to something that makes more sense?

Methods that start with 'do'

Do is always a wasted word. I see this mostly from coders that got their start with Visual Basic. Just don't 'do' it.

Why does it matter?

Readability is the most important thing to strive for in code. Bug free, maintainable, and fast code come from code that is readable. Most of the code's life cycle is spent in maintenance. The longest part of a typical maintenance task is to figure out what a particular piece of code is trying to do. Good documentation goes a long way towards making code understandable, but if the methods are actually well named you won't even need to look at the documentation.

Update (2012-03-15): I felt the need to revisit this post. Poor naming in the code base I'm working on wasted several hours of my day. I was trying to find where a set of objects was getting loaded from our data store. Looking through other code that did the same type of thing was a deep rabbit hole of included files and static calls to other classes. Finally I asked a teammate where the objects get loaded. He pointed out that they were loaded in a method named 'handleSortingAndPagination'. The method name doesn't provide any hint that it loads the objects from the data store before sorting and paginating them. The documentation for the method didn't either. This adds another bad naming smell: names that do not reflect what the method does.

Consistency is the key

2011-11-22T09:00:00.000-06:00

http://www.flickr.com/photos/richard-g/3549285383/

In my last post, Keeping it simple, I wrote about a few things that can make you a better coder, or at least a more valuable member of a coding team. This is the next step down the path of coding nerdvana.

Style isn't just for the stylish

Every coder has their own preferred style. Left to our own devices, we tend to write code our own way. As long as you're the only one looking at the code, this isn't a problem, but consistency should still be valued.

If you're part of a team, you hopefully have a well documented style guide that everyone follows. Hopefully it covers the gritty details so that developers don't get into fist fights with each other about style differences. The last thing that a growing code base needs is for you to be able to tell who wrote a piece of code without checking your source control's blame log.

But what if it doesn't cover a style point?

Stay consistent!

Perhaps it's my upbringing as a military brat or my overly-logical thought process, but I just can't handle disorder in code. It seems so simple to me, but I see code like this entirely too often:

function foo($bar, $mitz) {
if ( 0 == $bar ) {
doSomething();
}
if($mitz == 0){
doSomethingElse();
}
}

There are some very valid reasons to write your if conditions one way or the other (0 == $bar instead of $bar == 0). I'm sure there are people that will make arguments about whether to put spaces outside of the if condition parenthesis, or extra spaces inside them. But doing it two different ways in a single method is just crazy.

Mixing styles in your code makes it an order of magnitude more difficult to read. Code that is hard to read is hard to maintain. Your code will spend more time in maintenance than in development, so why wouldn't you do everything you could to make it easier to maintain?

Keeping it simple

2011-11-21T09:00:00.000-06:00

http://www.flickr.com/photos/r_rose/102766969/

I make no claims at being really smart. I don't even claim to have above average intelligence. But I have worked at companies that have a higher than average bar for employment and consequently above average employees. And working with really smart people, I've noticed that they tend to make one common mistake:

They write really complicated code.

A lone wolf

If you're a single developer working on a project, complicated code might be okay for you to write. Assuming that you write good documentation and are as smart as you think you are, you can write some really clever code. If you are truly as smart as you think you are, you can then maintain that code when you come back to it later. My experience with my personal projects has led me to a few realizations:

I'm not as smart as I once thought I was
I'm not as good at writing documentation as I thought I was
My unit tests aren't as clear as I thought they were

Again, you may be smarter than me, but you're probably not as clever as you think you are.

Joining the pack

Now, join a team of developers. You've got a group of people with varying skills and experiences. None of them are as smart or clever as they think they are. If you can't even understand the complicated code that you wrote as a team of one, how likely is it for the rest of your team to understand your code?

You're no longer writing code in a vacuum. It almost immediately becomes impossible for any team member to understand how the whole system works as the system becomes more complicated. So each developer has little fiefdoms that they wrote, and since they're trying to impress other developers they make sure their intelligence shows through in the code.

Now, join your team with other teams in the workplace... You see where I'm going with this?

Your sanity went that way

The solution is to keep it simple. Assume that when your code breaks, you're going to be expected to fix it on a Friday night after drinking a dozen beers or at the darkest part of the morning when you've run out of coffee. The last thing you want is to have to figure out what your code is doing before you can fix the problem. That means write more documentation about how the code actually works and what it is actually doing. It means avoiding anything that makes it more complicated than it needs to be.

Things to avoid in your simple code:

Big methods - They're hard to write, hard to test, hard to debug, and most importantly hard to understand.
Magic numbers - If you don't immediately know what a number means by looking at it, it should be replaced by a constant. And even if you know what the number means, does everyone on your team know? Many coders know that there are 86,400 seconds in a day, but that doesn't mean it shouldn't be replaced by a constant.
Conditionals - Sure, you're going to need if statements to write a decent sized program, but each branch your method has increases its complexity. You can have a small method that is extremely hard to understand if there are many branches.
Planning ahead - Programmers tend to be lazy. We try to think of every possibility ahead of time and program for things that may never happen. We needlessly complicate simple code thinking we can see into the future. And if that future never happens (more likely then we would like to admit) the code is wasted. And worse then wasted, it's difficult to understand. Since the code is only supposed to do one thing but you've coded it to do three, maintainers will assume that the three things it does are all equally important.
Bad names - As part of the growing complexity, it's easy to throw an extra bit of functionality into an unrelated method. Suddenly your simple method sendMessage(), which should just send a message from point A to point B can send a message or log you out of an application or change a configuration option. But if you're not intimately familiar with the code, you naively assume that the method just sends a message.
Static functions - Static classes and methods look great. You can call them from anywhere, and you can consolidate the similar functionality into a class. You can even unit test the heck out of that static class. But they rapidly increase the complexity of your lower-level code. They easily allow you to include huge chunks of functionality all over your application just by making a static call. That sendMessage() function needs permission, so it's easy to add a SecurityHelper::hasPermission() call inside sendMessage(). Suddenly, sendMessage() doesn't just send a message. It really becomes sendMessageIfSecurityHelperHasPermissionSaysSo().

Writing lots of documentation, adhering to a style guide, and doing test driven development can help keep your code simpler. You'll thank yourself later, trust me.

Building rock solid software in the real world

2011-11-10T11:06:00.005-06:00

http://www.flickr.com/photos/preef/32995286/

Recently (2011-11-08) I gave a talk at the Dallas PHP meetup about building rock solid software as a team. For my first experience talking in front of a crowd since high school, I thought it went pretty well. Several people have asked for me to post my slides (which I did), but they were made in a way that doesn't really help people out if they didn't see the talk. The talk was recorded and is available on Ustream, but I thought it might be helpful to do a blog post on the topics I covered as well.

This post is mainly meant to aggregate links to the topics that I talked about.

Tools

I covered several tools. All of these should be available to the developers as build targets and run in your continuous build. Lint and your unit tests should be run as part of your submission process.

lint - The bare minimum, it just detects syntax errors in your scripts. Code that doesn't pass the lint test won't pass any other tests or manual QA.
PHPUnit - Standard unit testing framework. There is plenty of information about it elsewhere.
PHP Code Sniffer - Detects code smells that should be fixed. Many bad programming practices can be written as "sniffs" along with most rules from your smile guide.
PHP Mess Detector - Statically analyzes your code for possible bugs or coding practices that tends to hide bugs.
PHP Copy Paste Detector - Scans your code to find large similar blocks which can be factored out to a common method.
PHP Dead Code Detector - Scans your code to find code that can not be reached. For example, code after a return statement.
Code coverage - Adding the xdebug extension to your system allows PHPUnit to calculate how much of your code is run by unit tests.

Code reviews

I talked about two different code review packages:

Review Board - You install it on your server and host it yourself.
Codereview.appspot - Use Google's code review tool.

And I talked about three different ways of doing reviews:

Pre-review - Code doesn't get submitted until a peer reviews it. Keeps bad stuff out of your code base.
Post-review - Code gets submitted, then gets peer reviewed. Comments made about the code may never get resolved, but code reviews don't slow down getting code into production.
Public shaming - Put the code up on a projector and discuss as a team. Great way to destroy programmer morale.

I mentioned a few points about what to look for in a code review:

anything the tools couldn't catch

logic errors (like ifs that don't make sense)
loops with off-by-one errors
performance problems (SQL in a loop)
things to refactor (large methods)

or things they missed

Style problems (not really wrong, but you know, wrong)
Typos (variable names, documentation)
Tests that don't have assertions
Methods without tests

Style guides

There's two ways to choose a style guide:

Roll your own - Look at your existing code and build the style guide from what you're already doing.
Use existing - Such as Zend or Pear.

Using YUI compressor in an ant build process

2010-11-30T09:00:00.002-06:00

Style sheets can get really large, really quickly. To make things easier to find, I split my CSS files out into major pieces of functionality. Instead of having to search through one giant style sheet of doom to find the rule that changes how a form field appears, I can open the style sheet for that bit of functionality. Many of my forms are customized, so each might have its own style sheet.

So I may have a bunch of CSS files in my styles directory:

general.css
login.css
signup.css
profile.css

Each rule in each of those files is namespaced by adding an ID attribute to the page's body tag, a class attribute to the body tag, or both. Then to deploy, the files need to be joined. I used to just concatenate the files together, but the YUI compressor does a great job making the files smaller that I started using that as well.

Every page on my site requires /styles/c.css. To generate that file from the components, I use some ant rules.

First, I make sure that I've download the YUI compressor. Since I have more than one project that uses this same system, I download the YUI compressor to a common location. And since I'm too lazy to worry about setting up my build environment on any system that I use I've included the rules to actually download the library. This target will only download the library once. If you override the yuicompressor property you can move the jar to wherever you want. I stick mine in tmp.


<property name="yuicompressor"
    value="/tmp/yuicompressor.jar" />
<available file="${yuicompressor}"
    property="yuicompressor.exists" />
<target name="yui-compressor-download"
        unless="yuicompressor.exists"
        description="Download and unpack YUI compressor">
    <echo message="Downloading YUI compressor" />
    <exec executable="wget">
        <arg value="--no-clobber" />
        <arg value="--no-verbose" />
        <arg value="--output-document=/tmp/yuicompressor.zip" />
        <arg value="http://yui.zenfs.com/releases/yuicompressor/yuicompressor-2.4.6.zip" />

    </exec>
    <unzip src="/tmp/yuicompressor.zip" dest="/tmp">
        <patternset>
            <include name="**/build/yuicompressor-2.4.6.jar" />
        </patternset>
    </unzip>
    <move file="/tmp/yuicompressor-2.4.6/build/yuicompressor-2.4.6.jar"
          tofile="${yuicompressor}" overwrite="true" />
    <delete file="/tmp/yuicompressor.zip" />
    <delete dir="/tmp/yuicompressor-2.4.6" />
</target>

Then, to actually build the combined and shrunk CSS file, I use a rule like this:

<uptodate property="compile-css.notRequired" targetfile="c.css">
    <srcfiles dir="styles" includes="**/*css" />
</uptodate>
<target name="compile-css" depends="yui-compressor-download"
        unless="compile-css.notRequired">
    <echo message="Compressing CSS" />
    <concat append="no" destfile="style-combined.css" force="no">
        <file file="styles/general.css" />
        <file file="styles/login.css" />
        <file file="styles/signup.css" />
        <file file="styles/profile.css" />
    </concat>
    <java jar="${yuicompressor}" fork="true">
        <arg value="style-combined.css" />
        <arg value="--charset=UTF-8" />
        <arg value="--verbose" />
        <arg value="-o" />
        <arg value="c.css" />
    </java>
    <delete file="style-combined.css" />
</target>

If the YUI compressor has not been downloaded, it will call the download rule for it. Then it concatenates all of the styles together and compresses them. The uptodate rule makes sure that it only runs if one of the files has changes.

Update: Changed the YUI version number to the newest version and re-added the code that actually builds the CSS. Not sure where it went.

A few rants on JavaScript

2010-10-13T15:01:00.001-05:00

I've got a few things to get off my chest relating to JavaScript.

Google's Closure library and compiler kick ass. However, they need to be cock punched for naming it after a notable language feature. That means that if you want to do a search for something about the library or compiler you have to sift through a bunch of stuff relating to programming closures in a language to get to stuff about programming in Closure if you're searching for a particular topic.
W3schools needs to update their site or take it down. It hasn't been updated in a decade or so. The web has moved on and they seem to have top spots in search results for so many topics.
Technical recruiters need to understand that Java and JavaScript are not the same thing; proficiency in one does not mean proficiency in the other. I have JavaScript on my resume, but nothing about Java. Yet I always receive calls from recruiters for J2EE jobs and the like.

{water}Falling out of Agile

2010-10-06T13:27:00.000-05:00

The waterfall approach

My last two software development groups switched to Agile while I was part of them. In both cases, it was a relatively amazing experience for me. Instead of towards a long term goal and finding out just how far off the mark we had been from the start when we finished, we were able to change directions so quicker in the middle of development.

If I was to plot a big project's path before we started with Agile, it would look something like this:

Each line in that graph is at least a month. At the end of the first phase, we had a usable product, but we realized that it really wasn't what our customer actually wanted. We eventually built what our customer actually wanted but it took close to a year, and we radically changed the product's direction several times.

The agile approach

Compare that to our path under agile:

Each segment is two weeks. At the end of the first iteration we had a somewhat usable product, but we realized then that we were already headed in the wrong direction. So we changed the product's direction early and often. Note that at each step our goal is the same as a phase in the waterfall method, but we change direction way before we reach our goal. Instead of taking over a year, the project took fourteen weeks. The development team was happier since we did not have to throw out huge chunks of code that we had written, and the business owners were happier since they could see our progress towards a goal.

Back to the stone age with you!

My current project is using more of a waterfall approach to designing an API. Instead of biting off tiny chunks of the API for development and building the client to go along with it, we're building the API out fully first, then building the clients to consume the API.

So far this has already led to lots of wasted effort. If I think I understand the business case for something and build an API for it, the API will work awesome until I try to use it for a real-world test. Then I find out that the definition of a concept I was operating under is wrong. So then to get the client to successfully consume the API I have to write the client and change the API at the same time.

We had a contractor work for three months on a large segment of the API that we ended up completely not needing. While working in a more Agile way wouldn't have kept him from writing all of the few thousand lines of code that has been since deleted, it would have shown us much earlier that he was going down the wrong path and at least some of his work may have been saved.

Agile wants a usable piece at the end of each iteration. That requires building at least an example client along with the API.

Unit Testing cURL Code in PHP

2010-09-28T08:00:00.003-05:00

My team is writing an API that will be used from other parts of our infrastructure. We're using cURL to make connections from the other parts to the API. But sometimes our network and API server are a bit flaky, which makes code that calls the API brittle if we don't handle those transient errors.

Instead of using PHP's native curl_* functions, we've created a simple class to wrap them. This helps some of the more junior team members as well, hiding some of the nitty-gritty details of making HTTP connections:

/**
 * Class abstracting the cURL library for easier use.
 *
 * Usage:
 *     $curl = new Curl();
 *     $curl->setUrl('http://www.google.com/#')
 *         ->setData('&q=testing+curl')
 *         ->setType('GET');
 *     $curl->send();
 *     echo $curl->getStatusCode(), PHP_EOL;
 *     echo $curl->getResponse(), PHP_EOL;
 */
class Curl {
    /**
     * @var string Body returned by the last request.
     */
    protected $body;

    /**
     * @var resource Actual CURL connection handle.
     */
    protected $ch;

    /**
     * @var mixed Data to send to server.
     */
    protected  $data;

    /**
     * @var integer Response code from the last request.
     */
    protected $status;

    /**
     * @var string Request type.
     */
    protected $type;

    /**
     * @var string Url for the connection.
     */
    protected $url;


    /**
     * Constructor.
     */
    public function __construct() {
        $this->body = null;
        $this->ch = curl_init();
        $this->data = null;
        $this->status = null;
        $this->type = 'GET';
        $this->url = null;
        curl_setopt($this->ch, CURLOPT_RETURNTRANSFER,
            true);
        curl_setopt($this->ch, CURLOPT_USERAGENT,
            'Curl Client');
    }

    /**
     * Return the body returned by the last request.
     * @return string
     */
    public function getBody() {
        return $this->body;
    }

    /**
     * Return the current payload.
     * @return mixed
     */
    public function getData() {
        return $this->data;
    }

    /**
     * Set the payload for the request.
     *
     * This can either by a string, formatted like a query
     * string:
     *      foo=bar&mitz=fah
     * or a single-dimensional array:
     *      array('foo' => 'bar', 'mitz' => 'fah')
     * @param mixed $data
     * @return Curl
     */
    public function setData($data) {
        if (is_array($data)) {
            $data = http_build_query($data);
        }
        $this->data = $data;
        return $this;
    }

    /**
     * Return the status code for the last request.
     * @return integer
     */
    public function getStatusCode() {
        return $this->status;
    }

    /**
     * Return the current type of request.
     * @return string
     */
    public function getType() {
        return $this->type;
    }

    /**
     * Set the type of request to make (GET, POST, PUT,
     * DELETE, etc)
     * @param string $type Request type to send.
     * @return Curl
     */
    public function setType($type) {
        $this->type = $type;
        curl_setopt($this->ch, CURLOPT_CUSTOMREQUEST,
            $type);
        return $this;
    }

    /**
     * Return the connection's URL.
     * @return string
     */
    public function getUrl() {
        return $this->url;
    }

    /**
     * Set the URL to make an HTTP connection to.
     * @param string $url URL to connect to.
     * @return Curl
     */
    public function setUrl($url) {
        $this->url = $url;
        curl_setopt($this->ch, CURLOPT_URL, $url);
        return $this;
    }

    /**
     * Send the request.
     * @return Curl|null
     */
    public function send() {
        if (!$this->url) {
            return null;
        }
        if ('GET' == $this->type) {
            $this->url .= '?' . $this->data;
        } else {
            curl_setopt($this->ch, CURLOPT_POSTFIELDS,
                $this->data);
            if ('PUT' == $this->type) {
                $header = 'Content-Length: '
                    . strlen($this->data);
                curl_setopt($this->ch, CURLOPT_HTTPHEADER,
                    array($header));
            }
        }
        $this->body = curl_exec($this->ch);
        $this->status = curl_getinfo($this->ch,
            CURLINFO_HTTP_CODE);
        return $this;
    }
}

First, here's an example class that calls to the API to pull a customer record. Assume the API returns a JSON object when called with http://api/customer/42. We pass in a Curl object to actually make the connection, then parse the response to fill our customer object's members.

class Customer {
    /**
     * @var integer Database ID.
     */
    public $id;

    /**
     * @var string Customer's name.
     */
    public $name;

    /**
     * Load a customer from the API.
     * @param integer $id ID of the customer to load.
     * @param Curl $curl Curl object.
     */
    public function load($id, Curl $curl) {
        $curl->setUrl('http://api/customer/' . (int)$id)
            ->send();
        $customer = json_decode($curl->getResponse());
        $this->id = $customer->id;
        $this->name = $customer->name;
    }
}

In a perfect world, calling load() will always populate the id and name members of the customer. In the real world, the API server could be down, or the network could die, or random alpha particles could mess up the request, so the code should handle those error messages. But setting up a test network to create those conditions is expensive and probably a waste of time, so we'll create a stub for the Curl object that allows us to break the API calls in interesting ways.

/**
 * Stub for the Curl class.
 *
 * Allows testing code that uses cURL without actually
 * making any HTTP connections.
 */
class StubCurl
extends Curl {
    /**
     * Constructor.
     */
    public function __construct() {
        $this->body = null;
        $this->data = null;
        $this->status = null;
        $this->type = 'GET';
        $this->url = null;
    }

    /**
     * Set the response 'returned' by the server.
     * @param string $body
     * @return StubCurl
     */
    public function setBody($body) {
        $this->body = $body;
    }

    /**
     * Set the HTTP status 'returned' by the server.
     * @param integer $code
     * @return StubCurl
     */
    public function setStatusCode($status) {
        $this->status = $status;
    }

    /**
     * Set the request method (GET, POST, etc).
     * @param string $type
     * @return StubCurl
     */
    public function setType($type) {
        $this->type = $type;
        return $this;
    }

    /**
     * Set the URL to connect to.
     * @param string $url
     * @return StubCurl
     */
    public function setUrl($url) {
        $this->url = $url;
        return $this;
    }

    /**
     * 'Send' the cURL request.
     *
     * Obviously doesn't actually send any requests.
     * @return StubCurl
     */
    public function send() {
        if (!$this->url) {
            return null;
        }
        if ('GET' == $this->type) {
            $this->url .= '?' . $this->data;
        }
        return $this;
    }
}

By passing a StubCurl object in to Customer::Load(), we can make the server return any status (or no status at all):

require_once 'Curl.php';
require_once 'Customer.php';
require_once 'StubCurl.php';

class CustomerTest
extends PHPUnit_Framework_TestCase {
    private $customer;

    protected function setUp() {
        $this->customer = new Customer();
    }

    /**
     * Test loading with a good API connection.
     * @covers Customer::load
     * @test
     */
    public function testLoadFound() {
        $curl = new StubCurl();
        $curl->setStatusCode(200)
            ->setBody('{"id":42,"name":"Bob King"}');
        $this->customer->load(42, $curl);
        $this->assertEquals('Bob King',
            $this->customer->name);
    }

    /**
     * Test loading a customer that isn't found.
     * Add a test for whatever behavior you want the
     * customer object to take if the API returns a 404
     * Not Found error. In this case, we're going to want
     * the customer object to throw an exception.
     * @covers Customer::load
     * @expectedException NotFoundException
     * @test
     */
    public function testLoadNotFound() {
        $curl = new StubCurl();
        $curl->setStatusCode(404);
        $this->customer->load(42, $curl);
    }

    /**
     * Test loading a customer from bad JSON.
     * The API returns a garbled response body.
     * @covers Customer::load
     * @expectedException BadResponseException
     * @test
     */
    public function testBadResponse() {
        $curl = new StubCurl();
        $curl->setStatusCode(200)
            ->setBody('{"id":_*()*(*$#@#$');
        $this->customer->load(42, $curl);
    }
}

Then the Customer class needs to have its load() method beefed up to handle the errors:

/**
 * Load a customer from the API.
 * @param integer $id ID of the customer to load.
 * @param Curl $curl Curl object.
 * @throws BadResponseException
 * @throws NotFoundException
 */
public function load($id, Curl $curl) {
    $curl->setUrl('http://api/customer/' . (int)$id)
        ->send();
    if (404 == $curl->getStatusCode()) {
        throw new NotFoundException();
    }
    $customer = json_decode($curl->getResponse());
    if (null === $customer) {
        throw new BadResponseException();
    }
    $this->id = $customer->id;
    $this->name = $customer->name;
}

Obviously you'll want to handle more errors in a production environment, maybe logging bad responses and server errors for later analysis.

Catching Subversion conflicts on commit

2010-09-21T08:00:00.008-05:00

If two people work on the same file in the same place in the file, Subversion can get a bit confused about how to merge the two different pieces, and will prompt the user to help it sort things out. However, it is up to the user to actually do so, and they're perfectly able to try to submit that file with the conflict markers still in the file. This is a pre-submit hook to not let people shoot themselves (and your codebase) in the foot.

Avoiding PHP syntax errors with Subversion pre-commit hooks

2010-09-14T08:00:00.004-05:00

Since my last few posts have all been about Subversion, I figured I'd do another. Our new team member is an experienced programmer, but has not had any experience with PHP. And he's not real good about actually running his code before submitting it.

PHP allows you to run its command line executable with a -l flag to catch any syntax errors in your code. Very simple, but can really help catch some stupid errors. Yes, they should definitely be caught by a code review, but code reviewers should also be able to assume that the code actually runs.

So here's a Subversion pre-commit hook that will run PHP lint on all PHP files and reject the commit if any of them fail.

Integrating Subversion and Review Board

2010-09-07T09:05:00.002-05:00

At Google, all production code must be peer reviewed before it is allowed to be submitted to their source control system. Since I'm no longer a Googler, I don't have access to their awesome infrastructure so I had to roll my own. Review Board is a pretty good code review system, and unlike the open source implementation of Google's internal one, you can host Review Board on your own hardware.

We use Subversion as our SCM. Out of the box, Subversion doesn't force code to be reviewed before submission, and I couldn't find any documentation about forcing code reviews through pre-submit hooks. Subversion's hooks are pretty powerful, and Review Board has a decent API, so I wrote my own. Hopefully this is useful to someone out there. It's written in PHP5. Put this in your subversion hooks directory, call it pre-submit, and make it executable.

Forcing PHPUnit tests on Subversion commit

2010-08-23T11:06:00.001-05:00

All of my PHP projects use PHPUnit for unit testing. One of my coworkers just refuses to understand the point of testing. He doesn't get Test Driven Development (TDD), and rarely runs the unit tests for his classes. This means that he frequently breaks my build. I can't force him to change his behavior since he doesn't work for me, but I can change the way my systems work. And I control the Subversion server.
I wanted to force unit tests to pass before allowing submission, but couldn't find anything about running PHPUnit tests in a Subversion pre-commit hook. So I wrote my own. Hopefully this will help someone out there:
To use this, copy it to the hooks directory in your Subversion repository and name it 'pre-commit'. Make sure the paths defined in the script are correct for your system. Make it executable (chmod +x pre-commit).

Setting up bug tracker regexes in WebSVN

2010-07-22T10:49:00.000-05:00

A while ago I set up WebSvn (http://www.websvn.info/) to allow viewing my Subversion repository at work. Today I decided to make it hack the commit messages in order to change bug links into hyperlinks to my bug tracker. After looking at the code a bit, there was a configuration option to turn on 'bugtraq' which claims to do what I want, but the documentation on how to set it all up was a bit non-existent. This post is mainly for me to remember how to set this up at any future employer that I might need it at.

To enable the log message hacking, edit include/config.php and set "$config->setBugtraqEnabled(true);". This will turn on the code that tries to parse log messages for all repositories that you've got set up. If you want to turn it on for a subset of your repositories you can add lines like "$config->setBugtraqEnabled(true, 'repository-name');" or turn them off the same way.

However, there doesn't appear to be documentation there about actually configuring where the links should go, or how you format the bug labels in your commit messages. My commit messages for the current project have used many different bug labels throughout its history:

bug: 12
bugs: 12, 34
Fixed lots of bugs (bugs: 12, 34)
Issue #12

It would be nice to catch them all.

After Googling for some information about how to set all this up, I realized that WebSVN uses Subversion properties for configuring the regexes needed instead of putting them in the config file with the rest of the repository configuration. Here's the subversion commands I used to set up the log munging to link to my bug tracking system:

$ svn propset bugtraq:logregex '(([Bb]ug[s]?)|([Ii]ssue))+[:]? [#]?(\d+)(?:,? ?#?(\d+))*

(\d+)' file:///opt/svn/my_repo

$ svn propset bugtraq:url http://tracker.domain.com/show_bug.cgi?id=%BUGID% file:///opt/svn/my_repo

Note that the first one spans a line. WebSVN uses the first line to find the bugs list, and the second one to find individual bug numbers from within the larger list. %BUGID% will be replaced in the URL with the bug id.

Also note that if you use the typical trunk, branches, tags setup, you can not just set the properties in the root of your source tree if you have trunk checked out. It needs to be set at the root of the repository or it will not work.

Hopefully this will save someone some time trying to set up the log munging without losing too much hair.

Thoughts on Frameworks

2010-02-22T14:35:00.000-06:00

Every developer thinks that their way of coding is better than every other programmer out there. They think their APIs are more elegant, their style is more succinct, and their loops are more optimized.

They are wrong.

I've had the misfortune to work with several custom-built frameworks. They were all terrible in their own way. Some had a slight excuse in that they were built in aging versions of PHP, but the otherall crappiness of the framework still stands on its own. And I can't claim that I think they frameworks were utter shit because I didn't write them, since I did write one of them.

But in writing my own framework and realizing just how crappy it ended up gave me the perspective to realize that I should use one of the big frameworks. I should use a Zend Framework, or Cake, or Symfony, or whatever. The programmers that wrote those frameworks may not individually be a much better developer than me, in aggregate they tower head and shoulders above. They get the benefit of having security experts picking at the seams of their interfaces, optimization guys fine tuning little used paths, and usability experts chiming in on workflow. They get the benefit of people trying to run the frameworks on operating systems you've never heard of, trying things with them you've never thought of, and using browsers you're too good to use.

Every developer should write their own framework, throw it away, and use one of the established ones.

It's so tempting to have the control over every aspect of the framework and the complete understanding of how each moving piece fits together. It's nice being able to custom build functionality for each small piece of your application into the framework-level code. But what always happens is that you start a new project and reuse your framework since you've put so much work into it. Then you find yourself having to code around all of the special cases that you put into the original. You're better off just using a more general framework from the start and putting your business logic where it belongs.