WordPress Settings API Wrapper? No Thanks.

From time to time, I end up having conversations with other developers about the state of the WordPress Settings API, whether or not there should be wrappers for it, and/or how the current API can be improved.

Each time the conversation begins, it generally stems from the fact that the Settings API is confusing, can be very intimidating to work with the first time, and it’s not as intuitive as some of the other WordPress APIs.

As with anyone who’s worked with WordPress long enough, I have my own opinions about this – and this is certainly not a “patches welcome” post – because this has been already been discussed at great length on Trac.

Instead, this is nothing more than my general stance on the WordPress Settings API, and how I see wrappers fitting into the scope of overall WordPress Development.

A WordPress Settings API Wrapper?

First, I’ve written an entire series aimed at beginners who want to familiarize themselves with the WordPress Settings API.

Secondly, I’ve also released a simple project on GitHub that’s meant to accompany the above series to show a practical application of the Settings API.

I mention this not to showcase various past projects about the Settings API, but to give some background that I have some experience in working with the API both in actual projects – be it themes, plugins, and applications – as well as in an educational sense.

To that end, I’m familiar with the pain that the majority of people feel when working with the Settings API. Trust me. It’s why I ‘ve talked so much about it.

Simply put, I believe that the nomenclature makes it hard to understand, and the API feels counterintuitive.

Even so, I don’t think creating wrappers, or writing frameworks on top of it are necessarily the best way to go about solving the problem, either.

1. A Layer of Abstraction

Everything that we do in software development is an abstraction at some level.

When it comes to the Settings API, the API its as an abstraction for a set of functions and modules responsible for rendering elements to the page, sanitizing input, validating output, and making it possible for us to expose options to our users.

If we introduce a wrapper around this, we’re created yet-another-level of abstraction that basically places a band-aid over the problem. But that’s not all – it creates a dangerous dependency.

2. A Dangerous Dependency

A couple of years ago, the guys at 8BIT and I were working on a set of APIs that sat in between themes and WordPress core in order to make creating options much easier.

It was meant to be a framework of sorts, but never grew beyond the state of being a high-end wrapper.

But here’s the thing: We scrapped it after we were had already begun a significant amount of development primarily because we were not only going to be responsible maintaining the theme with updates to WordPress, but maintaining updates to the wrapper, as well.

In short, every time you introduce a dependency – in this case, a wrapper – around an existing API, you’re project is at the mercy of the core application such that you’re going to have to update it every time that the core application updates.

And this gets really dangerous, because if you’re not paying attention to nightly releases, then your project, and everyone who has built stuff on top of your work is at the mercy of you and your ability to maintain the wrapper.

3. Treat The Illness, Not The Symptom

Generally speaking, whenever I hear someone say that they want to write a wrapper for the WordPress Settings API and make it publicly available, I die a little inside for all of the aforementioned reasons.

If nothing else, it’s simply wrapping up the problem with a bandage and saying “Look, we’ve got it taken care of!”

But we haven’t – the problem still exists under the bandage just as the problem still exists under the wrapper.

To truly fix the pain points that developers feel, then the entire workflow needs to be reimagined and reworked; however, this won’t come lightly. At this point, the Settings API is years old and who knows how many projects have taken advantage of it for their work especially when its the way to write options pages for WordPress projects?

The solution is clear, but the path to it is littered with danger.

On top of that, even if a new workflow or new API was to be introduced, the existing API would need to remain around for a significant amount of time so others can update their code.

There’s a period of deprecation that must happen before the API is fully retired.

Yes, There’s An Exception

I know a number of developers who have written their own wrapper, but who have opted not to publicly release it, and they only use it for their own projects.

Generally speaking, I think this is okay because if they are someone who is willing to do that, then I trust that they are willing to keep it updated with versions of WordPress as it rolls out.

At least, this seems to be my experience.

Tough Love

So what are we to do?

Honestly, we ought to take the time to learn the Settings API however the steep the learning curve, and start working with it. It is the definitive way to go about creating options pages, and it is the current version of the API that we have available.

So stop being afraid of it. Read the documentation, read the tutorials, read source code, write code, break stuff, and make things happen.