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.

The theme is dependent on a wrapper, the wrapper dependent on the API.
The theme is dependent on a wrapper, the wrapper dependent on the API.

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.

Don't use wrappers. Build your stuff above the read line and avoid dependencies.
Don’t use wrappers. Build your stuff above the read line and avoid dependencies.

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.

37 Replies to “WordPress Settings API Wrapper? No Thanks.”

    1. Sure, sure.

      And it’s not that I don’t think it won’t happen, but it’s going to take a significant amount of time, focus, and planning to pull it off.

      I think we’ll see it eventually as people do talk about this stuff from time-to-time such that it’s on enough people’s radar.

      But until then, we can work with that we’ve got :). Sure, the learning curve is a little steep, but once you’ve got it, it’s pretty standard the way you go about it.

  1. I am one of those who has written a (very) small wrapper for the Settings API and considered releasing it (but so far have decided against releasing). I didn’t write it because the Settings API is difficult to work with, but just to create a simple, OO-based method to reduce code duplication in my own work. With the wrapper, I can quickly create a settings page, add a setting to it and be confident that I’ve handled the display, saving and sanitization safely. The library is light enough that I don’t expect a lot of maintenance work.

    Now that I’ve started using it, other potential benefits have arisen. Because my wrapper internalizes all settings into a library object which then registers them all at once, it’s extremely easy for me to filter the settings before they’re registered — eg, creating a base add-on settings page that can be extended by other add-ons. And although most of my settings are fairly straightforward, real third-party value could be created if more complex data types are handled.

    But I’ve hesitated to release it so far for precisely the reasons you mention. It’s great for me — to do what I need to do I’d need to abstract a bit from the Settings API anyway. But others take a risk by creating a dependency on third-party software that may not be well maintained. I think the real problem with a wrapper/framework for the Settings API is that (to my knowledge) none of them have reached the kind of critical mass that makes an open-source project viable. Before I use an open-source project I like to know that there are enough people using it that if the original creators falter someone will step in and help find a way forward for the code. For that to happen, I think a respected member of the community would have to take it upon themselves to do this. Devin’s Options Framework is one candidate, but when I last checked it was pretty specifically geared towards theme options.

    1. Spot on with this:

      It’s great for me — to do what I need to do I’d need to abstract a bit from the Settings API anyway. But others take a risk by creating a dependency on third-party software that may not be well maintained.

      It really is great to do something for yourself and to keep it maintained for your own projects, but as soon as it becomes a dependency for someone else, you’ve got yourself a wider range of issues.

      I mean, I look at plugin and/or basic theme compatibility issues and they don’t even use frameworks – they are just things built on top of WordPress that people (myself included) have to really work to keep updated.

      If it’s that tedious for developers – and this is purely on our part, not the core application – to take the time to maintain our own stuff built on WordPress, what happens when we’re inserting a major layer of abstraction?

  2. Let’s take another stance for a moment.

    One of the primary reasons for wrappers, such as OptionTree, Redux, etc, is to make the plugin or theme developers job of building the main theme / plugin easier and faster.

    Depending on a settings API wrapper is about the same as depending on any 3rd party library within your plugin or theme, at least to some degree. You have to decide if the advantages it provided outweighs the cost of maintaining it.

    In many cases I can see the benefit of saved time from using a wrapper highly outweighing the “cost” of using one. It allows the developer of the theme or plugin to focus more on their core tasks than trying to get their darn fields to show up and save.

    Note, I personally do not like wrappers for many of the same reasons you gave, Tom, but I do think they have a place and serve a definite (good?) purpose for many, many developers.

    1. I do think they have a place and serve a definite (good?) purpose for many, many developers.

      Certainly – they wouldn’t exist if they didn’t, you know?

      But here’s the thing: It’s the tying oneself to a particular framework that may have negative impact on your work.

      And you hit on this:

      In many cases I can see the benefit of saved time from using a wrapper highly outweighing the “cost” of using one.

      and;

      You have to decide if the advantages it provided outweighs the cost of maintaining it.

      Both of these I whole-heartedly agree.

      In my opinion, using a framework comes with two major benefits (though there are definitely more):

      • Saving time (and thus money, in some cases)
      • Abstracting details that are tedious and redundant

      If a person is willing to tie their work to one of the publicly available frameworks, I think it’s safe, then, to expect that they should be willing to retrofit their code to the core APIs should the project stop being maintained.

      And – I’m pretty sure we’re on the same page with this – a framework is far more likely to fall behind in development rather than WordPress itself.

      To that end, that’s my main concern with mass adoption of a framework.

  3. Hi Tom,

    Thanks for the thoughts.

    I see this more abstractly. The Settings API is a middle man that helps you present forms and save / update the data in those forms in the WordPress DB in a predictable manner.

    The idea is that you don’t have to write your own save handlers that manually stuff values into options, or constantly reinvent the wheel and introduce security vulnerabilities by writing a new save handler for every plugin.

    However, since almost no one loves the provided middle man, and even experts confess they have to triple check their work when using it, what is the harm in creating and sharing alternative methods until something else comes along?

    As long as these methods are not packaged up and sold as the Last Settings Framework You’ll Ever Need (TM) in the form of a plugin you have to install to use certain plugins or themes (which some have, admittedly), I don’t see a problem with it.

    Developers like myself are developers because we love simplicity and look for ways to create it in our projects. One of my mantras is that if I find myself saying “There has to be an easier way…”, I’m probably doing it wrong and haven’t found the correct way. (probably)

    Anyway, this is my philosophical stance. I don’t take this stance because I have written / released a class for this kind of stuff, but because I think the natural response to an API that impedes speedy development is to be the solution until an official solution comes along. I hardly even use my own framework, so I don’t have a dog in the fight in that sense :)

    Clif

    1. I see this more abstractly. The Settings API is a middle man that helps you present forms and save / update the data in those forms in the WordPress DB in a predictable manner.

      The only reason I don’t consider it a middle-man is because it’s part of core with a native API.

      From a behavioral standpoint, you’re exactly right. And although it’s possible to create full on settings options, inputs, pages, and so on by bypassing the API, I don’t think that’s enough to categorize it as a middle man because you can do this with pretty much any core application that’s out there right now.

      In short (which I probably should’ve just said rather than my long statement above :)), I’d consider the Settings API a middle-man if it were not to be part of core.

      what is the harm in creating and sharing alternative methods until something else comes along?

      I don’t think there’s any harm in it; however, people are then at the mercy of your work and ability to keep it maintained against WordPress rather than simply being set against WordPress.

      I’m not saying there’s anything inherently wrong with this either, but there is a large risk factor for someone who wants to maintain a widely-adopted, publicly available middle-man, and for someone who wants to base their work on said middle-man especially if the usage/adoption/whatever rate of the project depending on the middle man is significantly wider than the middle-man itself.

      As long as these methods are not packaged up and sold as the Last Settings Framework You’ll Ever Need (TM) in the form of a plugin you have to install to use certain plugins or themes (which some have, admittedly), I don’t see a problem with it.

      Totally agree with you on all fronts here. It’s not so much a problem as it is a proposition of risk.

      For me, I find it more risky, thus, I tend to avoid it; however, if I was writing one on my own and was using it primarily for my own work, then I wouldn’t sweat it because, y’know, I’m the one who has to maintain the thing to keep my projects working :).

      I’ve got a much larger ‘dog in the fight,’ as they say than a third-party.

      One of my mantras is that if I find myself saying “There has to be an easier way…”, I’m probably doing it wrong and haven’t found the correct way. (probably)

      We’re of the same mind here. It’s unfortunate that there are times where there isn’t an easier way, for sure.

      1. I personally am using a self made Settings API wrapper which saves me a lot of time

        For sure – and if you’re maintaining it for your own work, then all’s good, of course :).

        ‘A wise man changes his mind, a fool never will.’

        What happens if a man never makes up his mind? Kidding!

        Thanks for that, though. I’d much rather be considered wise – or something in that general vicinity – than the alternative ;).

    1. using the Settings API, when writing plugins, take too much time

      It certainly does take a lot of time. No argument there.

      And I think your project is fine! It’s just a matter of if you’re up for constantly maintaining it as WordPress evolves over time :).

      I’d never mean to discourage anyone from writing something like this – just to be prepared for the work that comes with it.

  4. I think what Tom is pointing out is if you create a wrapper around the Settings API then *releasing* said wrapper for *public use* then having other developers *depend* on your wrapper to be updated.

    As Tom said

    …everyone who has built stuff on top of your work is at the mercy of you and your ability to maintain the wrapper.

    Then the question becomes, if you release a wrapper for public use, are you prepared to maintain it?

    IMHO, we shouldn’t even have to create wrappers in the first place. But since the Settings API isn’t very nice to use I guess we do need a wrapper of sorts until we can have another Settings API we all want to use.

    1. Then the question becomes, if you release a wrapper for public use, are you prepared to maintain it?

      Bingo.

      IMHO, we shouldn’t even have to create wrappers in the first place. But since the Settings API isn’t very nice to use I guess we do need a wrapper of sorts until we can have another Settings API we all want to use.

      It’s not so much that we “need a wrapper,” but more than it simplifies development which, in turn, makes development faster after the core wrapper is in place.

      Regardless, I’m being nitpicky about your phrasing :). All that to say, yeah, until people are completely satisfied with the API, wrappers are going to be developed.

  5. Anyone who depends on a framework that depends on the Settings API would have to maintain their own code when the Settings API changes anyway. By depending on a framework, then the dependency is concentrated into one place – the framework.

    So I don’t really see there’s much difference between the two. Especially if one is using a framework because there’s some benefit to it over and above what it’s wrapping.

    What breaks my heart *much* more is the soo many developers all writing their *own* wrappers for an API which is hence demonstrably unfit for purpose. There is such an obvious need for a better API and everyone doing their own is a sad waste of time.

    I’d encourage MORE people to publicise their wrappers. Let’s get everyone playing with them all – see which one comes out on top.

    At that point it will be easier for each individual to pitch in and fix the popular wrapper than to write and maintain their own wrapper.

    That can’t happen until everyone puts theirs out for criticism and the ‘market’ selects the one it likes best.

    1. So I don’t really see there’s much difference between the two.

      The difference is that with a framework, you have to maintain the code that’s built on top of it, and hoping that the vendor for the framework will also keep their code updated.

      If you’re just depending on WordPress, then that’s all you have to worry about (and it’s not likely to significantly change over time).

      I’d encourage MORE people to publicise their wrappers. Let’s get everyone playing with them all – see which one comes out on top.

      Now this isn’t actually a bad idea, but we shouldn’t underestimate just how many people would need to be evaluating and hopping on board before additional dialog and patches began to trickle into Trac.

      That can’t happen until everyone puts theirs out for criticism and the ‘market’ selects the one it likes best.

      Indeed – and that’s an uphill battle, but I am absolutely for the market deciding what it wants.

      Right now, we just know we want something different – what that different this is is what we don’t know.

  6. This article hits a few points that are spot on.

    Back in the way early days I wrote WP Framework, one of the early WordPress “starter” theme frameworks, with the intent that any wrappers that I develop for WordPress APIs are temporally and best served by actually fixing WordPress core and not just an isolated user base.

    Each wrapper introduces a potential increase in productivity which is great, but they add to the learning curve, and they add yet another vendor lock even if it’s coded in “the WordPress way” (not that it’s bad, but it’s something to consider). This isn’t to say not to be practical and wait until a core rewrite, but it all depends on your specific use case/requirements. We have to remember that as a community (theme, plugin authors), we can contribute to innovations before it’s introduced to core and not just lag behind APIs already in trunk.

    Now back to the Settings API: It’s a prime example of developing the old WordPress way, but to an extreme. It could definitely benefit from some OOD, but imo, it’s hiding the underlying issue of wp-admin needing an admin theme. That’s an entire article or two in and of itself, but yeah it’s something to think about.

    1. Back in the way early days I wrote WP Framework, one of the early WordPress “starter” theme frameworks, with the intent that any wrappers that I develop for WordPress APIs are temporally and best served by actually fixing WordPress core and not just an isolated user base.

      It’s interesting reading this now especially given that the new model is to build a plugin, fold it into core if it’s solid, leave if out if it’s not.

      Cool piece of WordPress history here, IMHO.

      We have to remember that as a community (theme, plugin authors), we can contribute to innovations before it’s introduced to core and not just lag behind APIs already in trunk.

      Definitely! And if I ever came off in the original article as if I was totally against writing wrappers – innovation does come from things like this and it does help bring attention to pain points.

      If enough people adopt it, then it’s something that could come available.

      I’m just saying that things such as vendor lock in (though, as others have mentioned later in this article don’t truly exist) are things that we must consider should the Settings API evolve.

      t’s hiding the underlying issue of wp-admin needing an admin theme. That’s an entire article or two in and of itself, but yeah it’s something to think about.

      Yes – exactly! Though, as you said, this is something that warrants more discussion in another post.

  7. Another option is to just forgo using the wp settings api altogether and create your own method of saving options etc to the wp database. The likelihood of wp significantly changing the options table is very slim for the very reasons the existing Settings API won’t change.

    Personally I LIKE the WP Settings API for quick projects where you need simple admin settings. But it really begins to break down in usage when you are building more complex apps that might have multiple settings pages and more complex methods of saving data (i.e. custom tables etc). In those cases the API becomes cumbersome.

    1. The likelihood of wp significantly changing the options table is very slim for the very reasons the existing Settings API won’t change.

      True; however, I’m not sold that something won’t eventually come sooner rather than later with the upcoming changes in how WordPress is going to be maintained moving forward.

      Regardless, even if it’s not changed, writing your own API is fine, but I do like the Settings API for what it offers (even if it doesn’t offer it as elegantly as many would like) because it provides so much – such as serialization, validation, sanitization, etc. – that can take a significant amount of time to rewrite, and really miss out on edge cases more than not.

      But don’t read me as saying that I’m saying to avoid writing your own API – certainly not! I happen to be of the mindset that if an API exists for something like this, use it, and improve it if possible – but don’t kick the proverbial can down the road.

      That’s all :).

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

    And based on official backwards compat policies, it’s not supposed to *ever* be retired, even if it is replaced. Not that those rules are actually respected in practice, but there is something you’re ignoring here.

    As ubiquitous as the current API is, even if the rules aren’t respected, there’s not any chance it would ever be changed in a backwards incompatible way that would break such a wrapper if it was written. Not within a good six or seven years, at the least. The current settings API isn’t in some state of flux, it’s solid. When was the last time it was changed in a backwards incompatible manner? If someone had written up a wrapper five years ago when the API was introduced, it would still work today.

    Writing little 3rd party wrappers like this is exactly how new features and changes actually happen in WordPress. If we never explore new approaches to such an API, it’s never going to see improvements. If someone were to write up such a wrapper, and it started making it’s rounds in numerous plugins, that’s the exact sign WordPress is looking for in order to determine that a new API is actually useful and solid enough to become the core replacement everyone is looking for. If and when that happens, that wrapper is in the same situation is all other plugins currently using the official settings API – WordPress will still continue to support it in a backwards compatible manner for likely a decade to come.

    I can guarantee that this job of “maintain the wrapper” that you’re making out to be this huge ordeal doesn’t actually exist. You might still find bugs in your wrapper caused by poor design of the wrapper itself, but you’re not going to end up needing to update the wrapper because of changes in WordPress core API.

    1. And based on official backwards compat policies, it’s not supposed to *ever* be retired, even if it is replaced. Not that those rules are actually respected in practice, but there is something you’re ignoring here.

      It’s not something that I’m necessarily trying to ignore, but with the roadmap that’s been outlined for WordPress coming – with the fork, for example – there’s no telling what will be dropped and what won’t.

      At least not now.

      And like you mentioned, it’s something that’s a rule, even if it’s not actually practiced.

      The current settings API isn’t in some state of flux, it’s solid. When was the last time it was changed in a backwards incompatible manner? If someone had written up a wrapper five years ago when the API was introduced, it would still work today.

      Point taken – well said!

      For me, it’s a matter of placing my self in the vendors position and recognizing that if it were to ever change and I’d built a significant client base around it, would that be something I’d want to deal with?

      Personally, no. But there are shops that do that all the time, so who am I to judge?

      But even still, I think that one of the inherent problems with the Settings API – despite the fact that it hasn’t changed – is that there’s this felt pain that many developers feel (especially new ones).

      And although you can adapt, learn, and put into the practice the standard API, I’m simply suggesting we need to know what we’re getting into should be begin writing more and more wrappers, or using more and more wrappers, and so on.

      I can guarantee that this job of “maintain the wrapper” that you’re making out to be this huge ordeal doesn’t actually exist. You might still find bugs in your wrapper caused by poor design of the wrapper itself, but you’re not going to end up needing to update the wrapper because of changes in WordPress core API.

      This is a fair point, but I’m not convinced that it won’t ever change.

      There’s been significant discussion about it on Trac, and it’s one of those topics that gets people talking (productively, in my opinion) about the state of it, but it’s not an easy thing to turn around.

      I think we all recognize that.

      Regardless, you’ve got some good points here – definitely respect ’em all, and I appreciate you taking the time to write ’em up!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.