WordPress.vim gets WordPress Hooks Integration

WordPress.vim has been missing a very important feature so far, WordPress hooks integration. That’s like eating a Chicken Biryani minus the Chicken! It’s delicious but not quite the real thing.

That’s no more the case! The 0.1.7 release adds some very cool new features to support WordPress Hooks.

The demo below shows the new ex commands like :Waction and :Wfilter. And if you have CtrlP installed you are going to enjoy, :CtrlPaction and :CtrlPfilter.

WordPress Hooks Integration

The Backstory

Initially this was the first thing I wanted to tackle in this plugin. But I was not quite sure how to go about with the implementation.

My initial plans were to use phpdocumentor to generate a list of actions & filters. Given the dynamo code already in place this didn’t seem too difficult.

But then you don’t just want to go the invocation of the actions or filter. It’s far more useful to go to the callback listeners of these hooks. Especially for filters where the input may be altered before it hits your function.

And then there was the whole problem of actually doing something with these generated list of hooks. At the least they needed to be converted to Vimscript and linked in some way to their origin lines.

Finally code generation is fine for syntax highlighting, but for jumping to source code would be asking for trouble. The lists would need to be rebuilt every time and would also require phpdocumentor.

All in all it seemed too tricky, so I had put it on the back burner until today.

An Unexpected Breakthrough

While implementing the WpSeek integration for the :Wsimilar ex command I had refactored out some code to make jumps to definitions easier.

The :Wdef command takes a definition that corresponds to a tag jump. The :Wsimilar command works by finding a list of similar functions and giving :Wdef the corresponding user selected match.

In the midst of this I discovered this excellent article by Eric Ritz on teaching exhuberant ctags to understand a new language.

We don’t need to teach ctags a brand new language, just some new tricks! :)

This was the missing piece I was looking for. It provides an elegant solution to our problem. Just add custom regex patterns to match WordPress actions and hooks.

Final Hurdle

By adding a custom regex pattern for add_filter, add_action and friends we get new ctags kinds that correspond to filters and actions.

But how to get the list of all filters and actions so that tab completion would also work?

We can get a list of all the template_redirect actions with taglist('template_redirect'). But taglist needs an expression for the matched tag name.

The easiest solution is to add a prefix to the kinds field. For eg:- for actions if we prefix the kind as FOO_action. Then taglist('FOO') gives us a list of tags matching the FOO pattern, ie:- all the actions.

To avoid accidentally matching kinds with similar named methods, a UID like 4c710n for action keeps it somewhat readable without mismatching with WordPress functions. At least until WordPress starts accepting patches in leetspeak!!!

Conclusion

To round it up the kinds implementation adds custom regex patterns for actions(do_action), and their callback listeners(add_action). And the same for filters and their callbacks.

Note: When upgrading from earlier version to 0.1.7 you need to regenerate the ctags for these custom patterns. You can use :Wctags! to do this automatically or delete the old tags file and the plugin will generate a new tags file on the first run.