Pre-Thought Listen

Konstantin Kovshenin recently posted on his blog about creating a WP_Plugin class. He posted an example of a class to fit his thoughts around it on Gist, and from there, discussion has taken place on how such a class would be implemented.

There has been a fair bit of discussion on my fork of Konstantin’s code about this, and I’ve been updating the class with new ideas as we come across them.

However, as is usual with discussion regarding any semi-complicated piece of code, there has been some disagreement on how best to hook methods in. Mike Schinkel is a fan of mapping method names directly to hooks, whereas I much prefer prefixing methods that I want hooked with either action_ or filter_. (We both agree that PHPDoc tags are a good idea though, although Mike also adds a @wp-nohook to ignore any methods.)¹ I thought I’d further flesh out why I’m not a fan of mapping the methods directly.

Personally, while I see the merit in naming methods for hooks directly, I hate magic. I hate not knowing when my code is used, and I think one of the biggest strengths of WordPress is that this hardly ever happens. If I want something used, I explicitly declare that through add_action/add_filter.

Don’t get me wrong: I love making things easier for myself. One of my favourite pieces of code ever is one written by Morten Fangel that I use in almost everything I do: _sortArgs(). This piece of code will take an associative array, like array('a' => 'b') and map the variables to parameters to my function. Combined with $_GET and $_POST, it’s an extremely powerful tool. However, _sortArgs isn’t really that magical when it comes down to it. I’m specifying which parameters I want, and everything is explicitly written by me.

I can see the same thing with this plugin class. If I prefix a method with action_ or filter_ (or using PHPDoc tags), I’m explicitly stating that I want this hooked. On the other hand, a method like init is completely implicit. It happens to match a WordPress action, but that could be a coincidence.

As an example of where this would be a problem for me: I often write a method like admin_page for whatever page I’m adding to the admin. If I have things spread across several pages, I’ll factorise the common header bits and footer bits into admin_header and admin_footer. Except with implicit hooking, I’ve accidentally just hooked my footer method into the administration footer. Now, I have to undo that by specifying that I don’t want it hooked.

To hook implicitly requires that I know every action/filter in WordPress to avoid conflicting with them.

Even worse than this is that hooking implicitly breaks forward as well as backward compatibility. Let’s say I add a method called after_post which I call from another class in my plugin, so I need it to be a public method. Everything is going well, until WordPress adds a hook into templates for adding content after a post. Oops, suddenly, my plugin breaks through no fault of my own, and through something that core developers shouldn’t (and wouldn’t) have to worry about.

Hooking implicitly breaks compatibility in every direction, and is too magical. It is absolutely not the way to consume a public API.

Sidenote: A discussion also emerged on how to use priorities. Mike and I both agree (I think) on using PHPDoc, while Thomas Scholz prefers preferred suffixing the method (i.e. action_init_2). My problem with this is that distinguishing between an named init with priority 2 and an action named init_2 is impossible.

Edit: Thomas dropped support for priorities in the method name, which I initially missed. Thanks for the correction.

Edit 2: Updated with a footnote about Mike’s position regarding implicit/explicit hooking.

1. Mike has informed me that he does support explicit hooking for published code, but implicit hooking for prototyping. I’m not a fan of this either, since I can forsee people forgetting to do so. [↩]