WordPress Simple Settings: A Settings API Alternative

If you’re the type of person who learns best by seeing code in action, you should look at my sample plugin on GitHub.

Call me strange, but I’ve never been a huge fan of the WordPress Settings API.   The sheer fact that a diagram like this might be necessary to explain it is indicative to me that it’s too complicated!

After fighting with conventional approaches, I decided to write my own framework as a Settings API alternative.

Requirements

Here are the requirements I started with for my settings API:

• Similar syntax to the WordPress Options API (add_option, get_option, update_option, etc)
• Single settings object for direct access (when required)
• Automatic handling of arrays, using delimited strings for user facing fields
• Automatic HTML field naming and saving

Basically, the API should be as easy to use as the options API and automate the annoying, inefficient tasks developers face when they are building options pages.

Additionally, the data should be stored in a single WordPress option for three main reasons:

1. Allows for programmatic direct access to a single, local settings object. (if you even need it)
2. Doesn’t pollute the options table with lots of new options.
3. Gives you the freedom to name your options however you like, without worrying about collisions with other plugins.

Solution

I developed my initial approach while rewriting Simple LDAP Login.  After showing my approach to a few other devs, I decided to spend some time refining it to be a formal, reusable framework for future plugins.

I’ve named the framework WordPress Simple Settings and released it under the GPL on GitHub (fork away!).

I designed it to be as minimalist as possible.  You should be able to implement it in minutes, and I’ve included a sample plugin to demonstrate exactly how it works! Woo hoo!

[repo name=”wordpress-simple-settings” author=”clifgriffin”]

What Is It Exactly?

WordPress Simple Settings is an abstract class which you use as your base class in your own plugins, themes, etc.

You set a unique prefix in your implementation, and the framework builds a settings object which is stored in a single option in the database. (Using the WordPress Options API)

The framework gives you getters, setters, and handles HTML field naming and data saving…all automatically, and with as little involvement from you as possible!

To demonstrate the brevity, this is the entire class:

Usage

Here are the basic functions available to you.

add_setting($option_name, $value)

This is essentially a wrapper for update_setting that respectfully does not make any changes if the option in question is already set.

You’ll most frequently use this in your activation hook.

get_setting($option_name, $type)

Retrieves a specific option. Returns string by default. If you specify array as $type, it will treat the value as a semi-colon delimited string and return an array.

update_setting($option_name, $new_value)

Updates a specific option.

get_field_name($option_name, $type)

Gets an HTML field name. If you set $type to array, the field value will be treated as a semi-colon delimited string and stored as an array.

the_nonce()

Call $YourPluginInstance->the_nonce() somewhere in your admin form to generate the nonce used to validate / save settings.

save_settings()

There is no need to call this unless you want to override the default functionality. This function will be called onadmin_init and automagically saves settings, if the right nonce and $_REQUEST is set.

Settings Object

One of my goals in building this framework was to have an easily accessible settings object that can be used directly when the getters / setters are inconvenient. This is done by simply using $this->settings[$option_name].

Obviously this should be used in read-only applications. Setting values here will not update them in the database.

Feedback

Please let me know if you successfully use it in your project, and if you have any ideas for improvements!