When The Customizer (once called The Theme Customizer) became part of WordPress, we saw a resurgence in the Theme Modification API.

The Theme Customizer

At one point in WordPress history, the get_theme_mod and set_theme_mod was how we handled theme modifications (hence the function names). Then, we began to use the options table as a way to manage the various settings for our plugins.

And then we began to use the options table as an easy to way to store settings for our themes. It was like we moved the Theme Modification API to the backseat and pushed forward with options.

Should we have done that (or does it even matter)? And what’s the difference in these APIs, anyway? Why do we still have both of them, which is best to use and when?

Using WordPress Options (Or Theme Modifications)

When it comes to the WordPress Theme Modification API, I don’t know much of its history. That is to say I know it exists and its purpose is a way to store settings for themes, but not much beyond that.

The Codex says:

Introduced in WordPress 2.1.0, Theme Modification API consists of all functions and hooks that are part of the WordPress API related to the use of Theme modification values. These functions can be used by theme authors to save (and retrieve) modifications to their themes as WordPress options.

But I also know that developers have been using the Options API for years to save plugin and theme settings.

Moving From Modifications To Options

I don’t know when or why we moved to the Options API, but I know that we shouldn’t ignore the Theme Modification API. Anyone who has done extensive work with The Customizer would likely agree.

Sometimes, though, I’m asked if we should have moved from one API to the other. At one time, I would’ve said “just stick with one since that’s simpler,” but I don’t feel that way anymore.

Instead, just as themes are for presentation and plugins are for functionality, we should be using the proper APIs for our themes and our plugins.

And this implies a difference in the APIs, doesn’t it?

An API For Each Purpose

But what’s the difference? To try to keep this simple:

  • Theme Modifications represent what’s available for a specific theme. WordPress saves all options managed by The Customizer as a single array in the database.
  • Options are available to any theme and/or any plugin. In contrast to the The Customizer, WordPress saves each value as a single record in the database.

Pretty easy to keep straight, right? I’d go as far as making this case:

If you’re working on a theme, use Theme Modification API (and add support for The Customizer). If you’re building a plugin, use the Options API.

And that’s my general rule of thumb. There are always exceptions, but this is the gist of it.

Why We Have Two APIs

And this is why we continue to have both APIs: One supports themes, one supports plugins.

Unfortunately, we’ve gotten so far remove from the difference in themes and plugins and the intent of the APIs, and we have so much misinformation floating around, there’s no clear between the delineation between the two APIs.

I’m not making the case for going back and refactoring how all your themes work. I do think as professional WordPress developers, we should properly incorporate these two APIs.

Though our old code may not do this (I know some of mine doesn’t), our future code doesn’t have to be that way.