Maybe returning errors in PHP

A common pattern I see in WordPress PHP code (and probably other PHP code) is a function which does some operation on data and returns a value. For example, a function which makes a database query and then returns the resulting row.

In order to make more robust code and prevent bugs, I’ve been systematically trying to use more return type declarations in my functions. This is a problem for things like the database function described above because a database query (and therefore the function itself) can sometimes fail. In those cases, the function might return the intended data, or it might return an instance of WP_Error instead. PHP does not currently (as of 7.1) support the idea of declaring return types when multiple types are possible.

Of course, such a function could simply throw an Exception if it fails, but this might be not as safe for critical code. An unhandled Exception, even a trivial one, could kill the whole program. Returning an error object instead could keep the program running (depending on how it is used). Even if we do throw an Exception, it’s not always clear when reading the function that it can throw.

So there are two problems now. First, since the function can return multiple things, we cannot specify any return type at all.

What I would need to solve that is the ability to specify multiple return types like phpdoc, but even if I could, it doesn’t guarantee that the user of this function will notice and handle potential errors.

This leaves us with the second problem, which is the same as if the function could throw an Exception; it can be easy for someone using it to overlook that the function can fail.

Is there a solution to both these problems? Maybe. (That’s a poor joke, as you’ll soon see.)

Let’s take the following function as an example. This function accepts an array of user data and returns the color property.

function getColorFromUser(array $user): string {
  return $user['color'];
}

It’s contrived, but it’s a reasonable simplification of the database query problem, since the array property might not exist, and therefore it can fail.

So now let’s modify the function to return an error if it fails.

function getColorFromUser(array $user) {
  if (! isset($user['color']) {
    return new WP_Error('NO_COLOR', 'Color does not exist');
  }
  return $user['color'];
}

As you can see, we’ve lost both the return type and also made it possible to introduce bugs in code that calls this function if they expect a string and instead get an object.

$myColor = getColorFromUser($user);
echo 'My favorite color is ' . $myColor; // This could cause a problem if $myColor is not a string

The standard way to handle this situation is similar to using a try/catch for an Exception; if we are aware that the function can return an error, we can check for one before continuing.

$myColor = getColorFromUser($user);
if (! is_wp_error($myColor)) {
  echo 'My favorite color is ' . $myColor;
}

It’s just that in my experience it’s common to miss the fact that a function can return an error. It’s even worse if a function once returned only a value but is subsequently changed to be able to return errors. Since the normal (successful) flow of the code will not change, no change is actually required anywhere the function is used. This makes type errors not only possible, but likely.

But what if we instead returned a wrapper object around the data? Let’s call it a Maybe. (See? There’s the joke.)

function getColorFromUser(array $user): Maybe {
  if (! isset($user['color']) {
    return Maybe::fromError(new WP_Error('NO_COLOR', 'Color does not exist'));
  }
  return Maybe::fromValue($user['color']);
}

Now we can have a return type, which can help prevent bugs inside the function. It’s not perfect as it doesn’t explain what types of values the object can contain, but it’s better than nothing. (To be fair, if we wished, we could create specific versions of Maybe for different values, like MaybeString, but I’m just going to keep it simple for now.)

Your first reaction might be that it also creates an inconvenience for the user of this function, because in order to extract the value of this data, someone has to do it explicitly.

But that small inconvenience means the developer must know about the possible error.

The example might then look something like the following. The condition required is similar to using is_wp_error(), but it’s more probable that the developer will remember to add the condition because they are forced to use getValue() on success.

$myColor = getColorFromUser($user);
if (! $myColor->isError()) {
  echo 'My favorite color is ' . $myColor->getValue();
}

This is not a perfect solution, and I’m certain that many developers will balk at having to add a pattern like this to their workflows when it’s not a standard part of the language. Personally I think it would be worth the discomfort to adopt this sort of construct when the benefit would be code that’s significantly less likely to have type errors. It probably depends on how careful you need your code to be. What do you think?

PS: It’s perhaps relevant to mention that there are functional programming concepts that are similar to this implementation, but which take it much further. My suggestion here is a very minimal interpretation that might be easier for some developers to grok. A more accurate name for this concept, matching existing patterns, is a Result.

Here’s how the Maybe/Result could be written:

(Photo by Caleb Jones on Unsplash)

Functional Dependency Injection in PHP

Having become used to the convenience of passing first-class functions around in JavaScript to make other functions decoupled and easily testable, I was wondering if we could do the same thing in PHP.

Of course, PHP technically has first-class functions as well, but the syntax is a little awkward, since the functions must be referenced as a string (and sometimes as an array).

Often I have some logic that can easily be contained in a pure function, and while I could put it in a class method, it’s not uncommon that the function doesn’t feel like it belongs to any particular class.

In these cases I tend to create “helper” classes. Essentially, I create a god class which is really just there to namespace its functions. If there’s a group of functions I want to inject, I might use regular class methods for this purpose, injecting an instance of the class. Otherwise, I use static methods. It occurred to me that maybe I could do the same thing with plain functions and actual namespaces.

JavaScript

In JavaScript one could do the following (this example is a bit contrived, but bear with me).

export function getGreenTea() {
    return 'green tea';
}

export function getOolongTea() {
    return 'oolong tea';
}
import {getGreenTea, getOolongTea} from 'tea-types';

function makeTea(getTea) {
    console.log(getTea());
}

makeTea(getGreenTea);
makeTea(getOolongTea);

PHP instance methods

Here’s how it could be done in PHP with classes and instance methods.

class GreenTea {
    public function getTea() {
        return 'green tea';
    }
}

class OolongTea {
    public function getTea() {
        return 'oolong tea';
    }
}

public function makeTea($teaType) {
    echo $teaType->getTea() . "\n";
}

makeTea(new GreenTea());
makeTea(new OolongTea());

PHP static methods

Here’s how it could be done with classes and static functions.

class TeaTypes {
    public static function getGreenTea() {
        return 'green tea';
    }

    public static function getOolongTea() {
        return 'oolong tea';
    }
}

function makeTea($getTea) {
    echo $getTea() . "\n";
}

makeTea([TeaTypes::class, 'getGreenTea']);
makeTea([TeaTypes::class, 'getOolongTea']);

PHP namespace functions

Lastly, here’s how it could be done with just namespaces. I think this is the closest to the JavaScript version, and doesn’t require creating unnecessary classes.

namespace TeaTypes;

function getGreenTea() {
    return 'green tea';
}

function getOolongTea() {
    return 'oolong tea';
}
namespace TeaMaker;

require('./TeaTypes.php');

function makeTea($getTea) {
    echo $getTea() . "\n";
}

makeTea('\TeaTypes\getGreenTea');
makeTea('\TeaTypes\getOolongTea');

Of course, this technique might not be the best choice for some situations. If there is any shared state or expensive repeated operations between functions, then they should be in a class and the methods should not be static.

Also, passing lots of dependencies to functions can sometimes be verbose and hard to read. In these cases it can be easier to pass the dependencies as a single object instance instead.

Finally, if there are several unrelated helper functions which are used in multiple places within the methods of a class, it can be more readable to pass all the helpers to the class constructor at once as an object (as though they were related).

Still, I think that passing functions as dependency injection is an under-used technique in PHP. I know it’s not the least bit Object-Oriented, and PHP is much more of an OOP language than JavaScript. In my opinion, however, the power of OOP is shared state and polymorphism and pure functions need neither.

(The image for this post is by 童 彤 on Unsplash.)

Declarative vs. Imperative: asking for soup vs. making soup

A little while ago I wrote a post about my concepts of declarative vs. imperative programming. I ended that article by saying, “I can’t wait to see what I’ll learn next.” Well, I’ve found another definition which has been very helpful to me lately. Also, I’m a little worried that it might actually be the opposite of my previous example. I guess that’s learning?

Declarative language describes what you want to happen, without necessarily explaining every step of the process to get there. “I want butternut squash soup.”

Imperative language describes every step toward making something happen. “I want a butternut squash that’s been cut in two, seeds removed, roasted, peeled, and blended with broth and spices.”

Of course, there’s quite a spectrum implied by those two words. How specific can we get in imperative language? “I want a butternut squash” already makes certain assumptions. How about, “I want an orange, long, vine grown winter squash”? This could go on all day. It really depends on the domain or the context in which your language will be used.

So back to programming. Most programming languages (at least the ones I’m familiar with) are decently imperative. With such a tool, you can use statements and conditions to tell the computer exactly what you want to happen and when.

On the other hand we have artifacts like HTML, the building-block of the World Wide Web. I know plenty of people who consider writing HTML to be using a programing language, and yet it actually falls much more on the declarative side of the spectrum. With HTML you describe what you want to happen to some content and each browser that reads that HTML must figure out how to do what you’ve asked. For example it may need to switch font weights if you’ve used a strong tag to wrap some text.

That said, declarative language relies on imperative language. Every declarative tool, like HTML, has been generated by humans wanting to simplify their work. They got tired of doing something repetitive and so they wrote a tool to convert it from a simpler form. Asking for soup is not very useful if no one in the room knows how to cook.

One more thought: writing HTML is declarative compared to, say, using JavaScript to edit the DOM. Yet there are other layers, like Markdown, which are in some ways even more declarative than HTML. It’s only in comparison that we can say that one thing is declarative and another is imperative, so always be on the lookout for other perspectives. And hey, that goes for the real world too.

Lightweight rendering of React to strings

For a recent project I needed to be able to render React components (or really, just React-like components) into plain HTML strings. Of course, React provides a mechanism to do this: renderToStaticMarkup in its ReactDOM library. But wow, that library is a really big dependency to import if I don’t want any of the DOM reconciliation stuff.

Also, it turns out I don’t even need React lifecycle events for my project. I don’t need component state either. I just want to render a bunch of stateless components with props and children. Something like this:

Well, maybe there’s a way to just import part of the rendering engine… but then I realized I had yet another requirement: I need to be able to modify the string version of every component as it is created. I can’t do that with React. I need a custom renderer.

Happily, with some experimentation I learned that it’s not that hard to create one! Below you can see my version of renderToString(). It accepts both stateless functional components and component classes.

Of course, the version below is a bit naive. I’m certain there’s many edge cases of rendering which it does not cover, and like I said above, it does not support state or lifecycle events at all. That said, it works very well for my own purposes and I learned a lot about how React components are put together in the doing!

The following also includes a full test suite to show how it works.

PHP Unit Testing and Pad Thai

As a follow-up to my last post about PHP unit testing, I recently gave a talk at WordCamp Boston about how to write testable WordPress plugins. You can see the talk slides here:

https://payton.codes/testable-wordpress-plugins/

You can also watch the talk here, although the audio quality isn’t great.

The premise of my talk was mainly that having testable code is a really great idea, even (and perhaps this is surprising) if there are no actual tests. Of course, without writing tests it’s hard to know for sure, but some experience will go a long way for future projects.

Even though this was at a WordCamp, my talk is not really WordPress specific. It really applies to any unit testing in PHP. In it, I gave an analogy to help my audience understand some of the concepts. Here’s that analogy:

Why have tests?

If you asked a friend to make you Pad Thai, you’ll probably get something edible, but maybe your friend isn’t such a good cook. If you don’t like the food, how can you tell what went wrong?

Dependencies

Defining your dependencies is important. “I want Pad Thai” vs. “I want Pad Thai, made with the following ingredients” will help. Even better, “I want Pad Thai, made with the following ingredients, ordered from this store, using this recipe”.

Mocks (AKA Stubs)

Using mocks is like asking the store to only sell your friend a particular brand of noodles when he calls. If the dish still tastes bad, you know it wasn’t because he got the wrong noodles.

What is a Spy?

Using spies is like giving your friend your phone number instead of the store’s phone number so that when he calls the store to order noodles, he calls you instead. That way you can verify that he’s ordering the right thing. If he calls and orders wheat noodles instead of rice noodles, you’ve found a bug with your friend’s recipe.

I also wrote Payton’s Testable Precepts: 10 guidelines I use when writing code that help make my code testable (as well as more clean, more flexible, and more readable). Here’s a list of those Precepts. See the slides for reasons and examples.

  1. Always use classes, never global functions.
  2. Don’t use static functions except as factories.
  3. Use instance variables as constants.
  4. Use filters to pass data indirectly.
  5. Use verbs in all function names.
  6. Keep functions below eight lines and indentation below four levels.
  7. Consider all possible inputs and outputs.
  8. Whenever possible, write tests first.
  9. Don’t test the code from other libraries, but test the inputs and outputs.
  10. Write only one assertion per test.

 

 

Higher Order Components and Pie Recipes

Higher Order Components (“HOCs”) are the latest hotness to come out of the JavaScript idea world and land in our apps. React apps, anyway.

I really want to write: Higher Order Components are just wrappers, but that would be simplifying the concept too much. Wouldn’t it? Maybe.

Anyway, they’re wrappers. Keep your actual Component simple as pie – it takes ingredients as props and turns them into rendered flaky crust – and have the wrapper handle getting the data from wherever, massaging it, and jamming it in.

This makes the underlying Component simpler to understand, debug, and ultimately reuse elsewhere if needed. Also testing! It’s way easier to test when the data piece is separate.

After thinking about it for a while you may realize that this concept is not new. Keep a pie-making machine abstract and separate from the ingredient machine? Where have we seen this before? Functions! (Ok, other places too.) And lo, this seems to be where React is heading (has already arrived?): Components as functions.

A Component, ideally, should take its props, nothing else (except maybe more Components) and turn those props into output. The output should be the same no matter what as long as the props are the same. It can use libraries to process the data it already has, but not get new data. I mean, that was an idea that React was built upon. But hey, I’d say that’s also the definition of a good function.

So if we think about our Components as functions, then we can apply function strategies to them. Mine basically boil down to: can this be done in fewer lines by extracting logic into a sub-function? Repeat as necessary until my functions are thin little beautiful pancakes. Maybe you have different strategies. Try them on Components!

Usually I see HOCs being talked about in reference to Redux and the global state tree, but my favorite thing is: who cares where the data comes from? Nest those Components and let them remain simple. The HOC could pull data from many sources, even just from a JSON file.

My new rule of thumb is: whenever my Component starts getting too many props (that are not directly related to its concept), when I am pulling data into my Component from a library, or when I find myself caching data in a Component’s state, there’s a strong chance I could use an HOC to smooth things out.

Give it a try! You may be surprised at how fun it can be.

Test spies in PHP

I think that I wrote my first unit tests in Ruby with RSpec, back in the day. But I learned most of my testing knowledge from working with mocha and chai in JavaScript. One of the things that I learned from these tools is that being able to express your test logic in clear, nearly-natural language brings a real comfort to the often complicated life of the test-writer.

For example, here’s a line straight from the chai home page:

expect(tea).to.have.property('flavors').with.length(3);

It’s so lovely.

When writing tests to follow the flow of code from one module to the next, it’s often useful to have Test Spies around to “spy” on the code and tell you what’s happening when. To borrow the definition from my favorite test spy library, sinon:

A test spy is a function that records arguments, return value, the value of this and exception thrown (if any) for all its calls. A test spy can be an anonymous function or it can wrap an existing function.

When brought together with sinon-chai, this allows for very expressive syntax:

expect(mySpy).to.have.been.calledWith("foo");

Because I work a lot with WordPress, I also write a lot of unit tests in PHP. There, the defacto standard is PHPUnit, which has… less natural language. That’s fine, though, its assertions are usually perfectly readable. What it seems to be lacking, for me anyway, is Spies.

Certainly there are some great ways to use PHPUnit’s built-in mocking tools, like this (hidden) behavior, but Spies are hardly a first-class citizen. And besides, even writing this feels confusing to me:

$target = $this->getMock('TargetClass');
$target->expects($spy = $this->any())->method('doSomething');

$target->doSomething("foo");
$target->doSomething("bar");

$invocations = $spy->getInvocations();

$this->assertEquals(2, count($invocations));

I would much rather write:

$target = mock_object_for('TargetClass');
$spy = $target->spy_on_method('doSomething');

$target->doSomething("foo");
$target->doSomething("bar");

expect_spy($spy)->to_have_been_called->twice();

So I ended up writing a Test Spy library for PHP. I call it Spies. My intent was to have an easy and readable way to create Test Spies, Stubs, and Mocks, and also a clear way to write expectations for them.

Creating a Spy is as simple as calling \Spies\make_spy(); (although there’s many other ways to create them). You can then call the spy and ask it questions, like this:

$spy = \Spies\make_spy();
$spy( 'hello', 'world' );

$spy->was_called(); // Returns true
$spy->was_called_times( 1 ); // Returns true
$spy->was_called_times( 2 ); // Returns false
$spy->get_times_called(); // Returns 1
$spy->was_called_with( 'hello', 'world' ); // Returns true
$spy->was_called_with( 'goodbye', 'world' ); // Returns false
$spy->get_call( 0 )->get_args(); // Returns ['hello', 'world']

Here’s a more complete example of using Spies to mock an object and test its behavior:

You can install Spies using Composer by typing composer require sirbrillig/spies in your project.

I owe quite a lot to the great library WP_Mock by 10up. Many of the concepts in Spies were inspired directly by the way that WP_Mock works, like creating global functions. WP_Mock serves a slightly different purpose, though. It’s a layer on top of Mockery, which in turn is a layer on top of PHP’s own testing tools. Also, it mocks a few things by default, like filters and actions.

Spies is intended to be more generally useful, and also to make the distinction between mocking and setting expectations more clear by breaking away from PHP’s built-in mocking concepts.

I welcome comments and suggestions at the Github page! As always, I hope it ends up being useful to other people.