Remove Settings API Wrapper from My Plugins

In the last few days I updated 2 of my plugins – Completely Delete and Unsortable Meta Box, there is nothing huge, I just removed the WordPress Settings API wrapper from them, and created the settings pages based on Tom McFarlin’s WordPress Settings Sandbox.

When developed these 2 plugins, to use or not to use any WordPress Settings API wrapper, that is the question kinda bothered me. I was hoping Tom could integrate the settings page to his Plugin Boilerplate, but got no luck. The barrier kept me from using the Settings API was, even though the Codex looked simple – with only 10 functions I could create a settings page, I had no idea when to use which function.

To speed up my development process, I decided to use one of the Settings API wrappers I found at Github. It’s a very good one, with clear documentation that I can see how to code and what I’ll get. So I integrated it into Completely Delete and later I also used it in Unsortable Meta Box.

Say no to Settings API Wrappers?

I thought the problem was solved and I could stick to it whenever my future plugins need a settings page. But then Tom wrote a post – “WordPress Settings API Wrapper? No Thanks.” which made me think again. In that post, Tom made his points clear (as always), there are 3 reasons we’d better not to use wrappers for Settings API:

  1. If we introduce a wrapper around the Settings API, we create a yet-another-level of abstraction that basically places a band-aid over the problem. And it will introduce another issue – a dangerous dependency, see reason 2.
  2. Every time you introduce a dependency – in this case, a wrapper – around an existing API, your 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.
  3. The wrappers just treat the symptom, not the illness.

And also he mentioned that there’s an exception that it’s okay if you’d like to build a Settings API wrapper and just use it for your own projects.

Tom’s post reminded me that in the first version of Completely Delete, I included the whole directory of the wrapper plugin as a submodule. When I submitted it to the for plugin review, the review team told me that:

“Your plugin is totally including another one:  WordPress Settings API. Since this is a plugin hosted on – – you can make it a required plugin, but you should not include it in yours. By including it, you make yourself responsible for all updates of that plugin, which is not needed.”

I removed other files and kept only the wrapper class file in my plugin, so Completely Delete could be accepted and listed on the There’s a lesson and I think it’s related to the question that to use or not to use a Settings API wrapper.

It’s all about responsibility

When developing a plugin and releasing it to the public, no matter it’s hosted on the or Github, it’s the developer’s responsibility to keep the plugin compatible with the latest WordPress. Maybe you’ll think: why so serious? I just want to have some fun with side projects in my leisure time. Of course you can have fun! And I suppose most free plugin developers think that way too.

When people talk about why they hate WordPress (or any other open source CMS), one of the top reasons is like: “I can’t upgrade my WordPress website because the plugin X / theme Y is not compatible with the latest version. The upgrade will break the site, but not to upgrade will make it vulnerable to hacker attack. That’s really a pain in the ass.”

In such a scenario, we can see the love and hate about WordPress, both caused by plugins. People love to extend the power of WordPress by installing these powerful plugins, also hate about WordPress for the instability caused by the plugins (or themes in some cases).

If we take it serious about being part of the WordPress community, our work should bring more people to join us, not keep them away. As a plugin developer, I would love to update my plugin to keep up with WordPress. But by including another plugin or framework into my plugin, that means I need to be responsible for them too, which makes it harder to maintain my own work.

As Long As You Can Handle It

So my conclusion about to use the Settings API wrappers or not is, use any wrapper class as long as you’re capable of updating it, when some day you have no choice but do it yourself.

When take a closer look into the wrapper class I adopted, it is well-written and easy to understand, so I definitely can handle it if some day I have to. I just realized I don’t need it since the setting options for my plugins are just 2 or 3 simple checkboxes.

I took some time to force myself learning the Settings API and start working with it. It’s actually simpler than I thought (with the right mindset, learning everything could be easy). By following the best practice, I don’t have to worry about the dependency issue and can focus on the plugin itself.

In the end of this post, I want to emphasize that I’m definitely not opposed to use any wrappers or frameworks in the plugins or themes. The two things I’d like to remind developers are:

  1. Sharing is the most important spirit in the open source community. Don’t be afraid to share anything you’ve learned about WordPress. If anyone adopts your work and bumps into some trouble later, you should be happy to work out a solution with him / her, it’s a great opportunity that someone would love to pay for, but you get it for free. So you should be thankful for that.
  2. Be responsible by declaring clearly that who or what your work (wrapper class, snippets etc.) is for. Inform the users what limitation or problems might exist. If it is for your own good and you haven’t done many tests, say it out loud; if it’s for a weird purpose and only works on PHP 5.4 and above, say it out loud. Say it like any “USE WITH CAUTION” alert on the medicine bottles.

I hope you get the idea of what I’m saying. And don’t forget to check out the latest version of Completely Delete and Unsortable Meta Box. Any feedback is much appreciated.

2 responses

  1. Great post, one of the main issues I have with the settings API wrappers is that it introduces another set of things to learn and typically it’s written differently from how the official API accomplishes things. You’ve said it here too, you had to learn this new api and well, personally, I prefer learning the way things core does, or learning things that core can’t do. An api on top of an api just gets in the way.

    Like Tom said, fine for personal projects, but when it’s put out there as something that wants to get adopted by a bunch of other developers, it introduces the problems Tom talks about.

    The other thing is the issue with settings wrappers is that they tend to become stale even after a strong start/adoption. Just look at all the theme options frameworks that have started to gather dust. It’s a pain in the butt to maintain these things and the payoff is not there to make it sustainable typically speaking.

  2. Yoren Chang Avatar
    Yoren Chang

    Peter, thanks for stopping by. You’ve made a great point: developers should learn the way things core does, or learn things that core can’t do. So true.

Leave a Reply

Your email address will not be published. Required fields are marked *