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.)

Thoughts on Privilege

Today in my Sangha we explored the concept of Engaged Buddhism, particularly as it applies to race, gender, and class. We explored the most insidious aspect of privilege in our society: that those with privilege do not see it; we are blind to it. White people do not consider race to be a primary factor in their day-to-day affairs. Many people of color do. In fact, even the existence of the term “people of color” implies that the default race is White. Even if we “ignore race” (or any other characteristic), we are making a decision to perpetuate the discrimination that other people face constantly.

When I was young, I was bullied and insulted because I was considered a nerd. I couldn’t do a pull-up. I wasn’t interested in organized sports. I loved reading books and learning about computers. Because of these things I was considered an outcast among my peers and even many adults. My dream was always to fit in, and to that end I’ve worked my entire life to try and be one with the group, to gain the power that I felt I lacked. Of course, I didn’t see the privilege and power that I already held by the nature of my skin color, family wealth, and gender.

Since that time, nerds have become powerful. Computers and the Internet are no longer a niche in society. Their use is no longer optional. Most people in the West even carry a supercomputer in their pocket. We have achieved what might be considered an outcast’s dream: we have made ourselves indispensable to everyone. And we probably all think of ourselves as having won some great battle in the manner of the Great American Dream: with skill and talent and persistence, we were able to rise above our station and achieve that we which had been denied to us but which we richly deserved.

This, of course, is a fiction, because in most cases the only reason one is able to rise up and achieve something is when the culture allows that to happen. In my case, my whiteness and my other privileges made it possible for me to utilize the resources around me to get the things I wanted. I think the same is true for all of the technical elite of our current era. The danger is that we don’t realize what enabled us to achieve our status, instead believing it was our innate ability alone.

This incorrect view leads us to conclude that everyone has the same chance that we had. It leads us to blame those who are suffering for their own suffering. It leads to the idea that the poor are poor because they are lazy, that those convicted as criminals are evil, and that those who are in power deserve to be there.

Even within the open-source software world, the myth of the meritocracy is one example of this pervasive idea. It goes something like, “if we don’t see a person’s appearance, gender, real name, or class, and if contributions can be made by anyone freely without position or power, then surely the best ideas will rise to the top and everyone will be evaluated and judged only by their skill.”

What this concept fails to take into account is that an open-source project is a community of people, and all communities are bound by the same rules of privilege that exist in the “real world”. Contributing to a “free” project still means spending time, and it likely means spending money for a computer, special tools, and most importantly access to information. Does everyone have these resources available? Is everyone encouraged in their pursuits, supported by their families and communities?

If we treat “tech” as a meritocracy, then we might as well say that landscape painting is a meritocracy. After all, it’s just paint on canvas, and one need never see or know the identity of the person who painted a picture. But of course, amazing painters are not born, they are made through training and practice. This is not to say that different people don’t have different innate abilities, but that those abilities are only a small part of what brings about success. The rest is the often-invisible support of thousands of other people who open the doors to the skill which we think we earn.

So how do we work to change these things? How can we make a difference? If there was an easy answer to those questions, we’d all know about it already. But I believe the first step is to examine our experiences and always look for the support from others, the little forgiveness, the gifts of time and money and information; in short, to look for our privilege as it manifests. Only then, I think, can we work to dismantle the invisible architecture that separates Us from Them.

(Photo by Nicholas Green on Unsplash)

Search for the Sage

My fourth D&D adventure crafted for the Automattic Grand Meetup, Search for the Sage is a one-shot game perfect for new and experienced players alike. It runs in about 3-4 hours. I had a lot of fun creating and running this one! Huge thanks to the many friends who played through this adventure and extra huge thanks to those who DMed it.

Here’s the teaser:

A town sinks slowly into the sea and only the power of an ancient sage can save it. But can the sage be found in time? There’s only one way to find out.

Would you like to try to find the sage yourself? Download the adventure here.

(Incredible formatting courtesy of The Homebrewery. Check them out!)

Photo by Jason Wong.

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.

 

 

Temple of the Ruby Sands

A year ago I published a Dungeons & Dragons adventure titled The Stonecutter Samurai which was written to share with my friends and co-workers at Automattic. This year I wrote another adventure, Temple of the Ruby Sands!  As it has now been played a total of seven times and I’ve cleaned up the stats and wording, I’d like to share it with you.

The game is a one-shot adventure for a group of 2nd-level characters and runs in about 3-4 hours (I’m getting better at making them short!). It was designed to be fun for brand new players and experienced die rollers alike. It should even have enough info be run by new DMs (although you may want to get to know the D&D 5e rules a bit first)!

Here is the teaser text:

An ancient temple, buried deep in the desert, has recently been excavated by an eccentric Dwarven archeologist. Unfortunately, the excavation site is surrounded by blood-red sand that many locals claim to be cursed, and the archaeologist’s last team was killed when they discovered a series of deadly traps within. Now he desperately wants to hire a new team to return and claim the temple’s treasure, but is there something more to this ancient ruin than meets the eye?

If you feel like braving the Temple of the Ruby Sands, you can download the adventure here.

(Awesome formatting courtesy of The Homebrewery.)