Using update_option & get_option Instead of the Complicated Settings API in WordPress Plugin Development

IMPORTANT EDIT: Security is vital, and I’ve been called out by two very respectable WordPress engineers on Advanced WordPress for my lack of security in this post and that using the Settings API is important because it handles this security for you.  I’m adding nonce, capability checks and proper sanitization to this code right now and should be in place shortly.

The code in here is also written for brevity of example.  Copying and pasting will work but it’s best practice to put functionality in the appropriate places.  For example instead of just using sanitize( $_POST[‘var’] ) you should add a filter that’s global.

WOAH that’s a long title.  This isn’t going to be a crazy long post but all those items mentioned are very important to the content.  The WordPress Settings API is powerful and for large plugins or themes it might be the best way to go about managing a large array of settings and options.  But most of my plugins are small scale and I find it overly complicated and bulky.

My Experience With The WP Settings API

If you don’t care about my experience and just want to see my solution click here.

My first plugin where I needed a core admin page just for settings was the WP Name Your Donation plugin.  I’ve all but abandoned that plugin because there are so many awesome plugins out there that cover its functionality and more.  It was a great learning experience building it though.

It allows multiple gateway options for accepting user determined amounts of money, i.e. donations.  So the admin page needed to allow a user to set the api keys for multiple gateways and I was starting off with Stripe, Authorize.Net and PayPal.

Googling admin settings in plugin development while I was building this, which was only my second plugin, referred me to articles on the WP Settings API.  It took a TON of trial and error to get this functioning and I still don’t think it’s implemented right.  Take a look at this:

I start by building out all my options in arrays.  These arrays hold all the info for each setting input I will need for each payment method option.  Then I loop through them all using the Settings API method add_settings_field() after using the methods register_setting() and add_settings_section(), note this is in the admin_init hook:

I have different functions for different kinds of fields which you can see in the parameters of add_settings_field.

Codex Confusion

Over in the codex for the Settings API you will notice multiple times they have small callout notes saying “make sure this was done first.” The confusion is real because my code does not follow a lot of the directions yet it works.  But when I was playing with it last night in a new plugin I was following directions exactly and it wouldn’t work.  For example:

NOTE: You MUST register any options used by this function with register_setting() or they won’t be saved and updated automatically.

In my code you will see I use the register_setting method, but I use it with the parameters

( self::PLUGIN_ABBR . '-group', self::PLUGIN_ABBR . '-group' )

The PLUGIN_ABBR is just wpnyd so the string “wpnyd-group” is set for both parameters and here’s the kicker: I DON’T USE THAT STRING ANYWHERE ELSE IN MY SETTINGS CODE.  What the hell???  I look back at this and wonder what the hell brought me to the code that’s in place and that works.

I’m not going to expand on this too much but will in comments if we have discussion.  This is just one example of my insane confusion from trying to implement the Settings API for the second time and trying to actually follow directions.

Using update_option and get_option For Admin Settings in a Plugin

These methods are lightweight and serve a simple but awesome purpose.  You set a unique key and a value and those are accessible at any time.  I find it best just to learn by example so I will show what I recently did and explain along the way.

I need the ability to let an admin set a few checkbox options and a color.  For simplicity’s sake in this post I’ll show how I do that with just one checkbox and a text field (I use a color picker but that makes it complicated, so we will just use text).

Here’s the full code, explanation below that:

Let’s look at the form first.  We have two inputs, feature_on and settings_color, a checkbox and a text input respectively.  These represent two settings we want the admin to be able to control.

Now let’s look at the php up top.  The first thing I do is set a default value $settings_color which will be used in case this has not been set by the admin yet.  Then I check if the form has been submitted by detecting if $_REQUEST[‘settings_color’] is set.  If it is, let’s update some settings.

The first method we use is the WordPress method update_option().  I love this method.  If the option doesn’t exist, it creates it, if it does exist then it simply updates it! So simple, so straight forward, so not messy, YES.

NOTE: Option keys MUST be unique so be carful naming as you don’t want to overwrite an option in another plugin.  Here I added “myplugin_” to the beginning but I’m sure you can be more creative than that.

Setting & Getting Text Input Values

This is so straight forward.  First thing we do after checking if the form was submitted is simply set the options value with the (sanitized) submitted value:

update_option( “myplugin_settings_color”, sanitize_hex_color( $_POST[‘settings_color’] ) );

Done! Now we can call this value and use it, overwriting our default set value with:

if( get_option( “myplugin_settings_color” ) !== false ) {
$settings_color = get_option( “myplugin_settings_color” );

We must check if the admin has already set this or not by testing if it exists via the !== false or we will throw a php warning.

Sanitizing with pre_update_option

It’s important to sanitize any posted data going into your database.  For options we use pre_update_option filter.  To use this you need to add your option’s key to the end of the filter.  So for my settings_color option it would be like this:

add_filter( 'pre_update_option_settings_color', array( &$this, 'hexcolor_sanitize' ), 10, 2 );

Then a function ‘hexcolor_sanitize’ needs to be defined for handling this.  In this code example below you will see how that is handled.  Side note, sanitize_hex_color is not available outside of the customizer so I just copied the function into my plugin’s code:

Setting & Getting Checkboxes

If a checkbox is checked when a form is submitted then it’s value is accessible via $_REQUEST[‘checkbox_name’].  If it is NOT checked, then that request variable is not set at all.  So if we don’t need a value from it but simply need to detect if it’s checked or not we just see if it exists:

if( isset( $_REQUEST[feature_on] ) ) {

For my purposes this is all we need so we update our option to either true or false.  Now if we want to set the box to checked or unchecked in the admin interface based on what an admin has or has not set already then we need to check a couple of things.  Has this setting been set previously? If so is this setting true or false? We accomplish this with:

if ( get_option( “myplugin_feature_on” ) !== false && get_option( “myplugin_feature_on” ) ) {
echo ‘checked=”checked” ‘;


The purpose of this article isn’t to make the Settings API look like a bad choice.  It’s extremely powerful and a great choice for many applications.  But for simple plugins like mine it’s overkill.  And I will say this, the codex and documentation on the Settings API are fucking horrible and confusing.

Tutorial, Shmutorial, Learn New Stuff By Switching It Up

My new job needs an iPhone and Android app.  I’ve built a few shaky Android apps using java and a LOT of google.  They worked but not being a java developer I know my methods and coding standards were sub-par at best.  I’ve never attempted an iOS app.

Thankfully there are few pretty badass frameworks out now that let you use javascript or something similar to build native apps.  A friend recommended NativeScript.js and so far I’m really liking it.  But I’m learning a brand new technology so I do the same thing most of us do.  I go through the official, beginners tutorial example to build out a sample app.

Make It Your Project

But I like to do it different.  I find this method not only immerses you in the new language or framework but also helps you start solving problems and learning deeper parts of the system at the same time.

I need a fairly basic app.  It needs to let users log some information kind of like MyFitnessPal and keep track with analytics.  Nothing crazy but will include a couple features that dive into some deeper modules like using the camera.

So I start the tutorial going step by step which gets a nice boilerplate up, gives you a hello world and then moves onto building out features for their sample which is a groceries list app.  This is when I start changing things to do what I want them to do.

For Example

Chapter 2 gets into building out a view for the initial screen which is a login or sign up screen.  Hey, we need this in our app! Awesome, so I’m going to follow this part exactly for now.

The tutorial taught me how to implement css stylesheets app wide or specific to individual pages.  We styled up the login inputs and buttons and now I want to side-track a bit.  I want my companies logo at the top.  I leave the tutorial right where it is and I pop open a new tab and find the developers resources on the website.  I find UI Components section, Images is listed in there, I click and now I dive into how images work.

I already know how to put UI components in the layout from the tutorial so this should be easy.


OK, so I have to load the Image module and I also have to then create an Image instance.  I’ve loaded the main module already and that was in the main app file, so do I do it there or do I do it in the page’s JS file? Let’s experiment!!

This is how I find the learning process really starts getting more intuitive.  I’m forced to solve a problem instead of just following a line by line tutorial on creating an app.  For me, and I suspect for others, this process actually makes learning a lot faster and more in depth.  It might not work for everyone but I have to suggest giving it a go.

Note: They actually show how to add an image not even a section further down the tutorial but I still find the fact I took the time to dig through developer resources for a few a great learning experience.

In Conclusion

This won’t work for everything.  Some languages and frameworks, especially those you have absolutely zero knowledge of, following the initial tutorials exactly is not a bad idea for introducing yourself to the system.  But this comes in handy and again, I do recommend giving it a go sometime.

My First WordCamp Presentation Was Awesome

I’m sitting in a tattoo parlor in St. Louis right now waiting on the artist to sketch up my art.  I love tattoos, I love getting them, I love appreciating other people’s, I can’t get enough of them.  I get tattoos to memorialize events in my life.  I get them for other reasons too but that’s a big one.  I decided to get one that represents my experience this weekend.

haildale-shamrockI’m on stage all the time with my band.  We’ve played in front of 500 people and I didn’t have a single butterfly.  But the day before doing my first WordCamp presentation I was nervous as hell.  I was terrified honestly.  I’ve never spoken as an expert.  I’ve never considered myself an expert.  I was encouraged by my piers to apply for speaker positions though so I decided why not and sent out a few applications.  To my surprise three got back to me and I was actually doing it.

I spoke on Plugin Development 101.  It was a basic introductory to how plugins are built in WordPress and how simple it is to actually make one.  The end of the presentation I build a plugin in just a few minutes to demo the simplicity.  The slides can be found here:

When I got to the conference and was setting up my computer with the projector I felt a lot calmer.  There were only two people in there.  As much as I wanted to have a big group, my nerves were very happy at the tiny turn out.  I was supposed to start at 9, but decided to wait a couple minutes to see if anyone else showed up.  By 9:04 every seat in the room was filled… shit.

I kept my composure and just went at it, started talking, introduced myself and went slide by slide.  I was fast, and I probably rushed a couple of slides because I was finished in 25 minutes when it was supposed to be 40 minutes with a 5 min q & a.  Thankfully everyone seemed to really enjoy it and there were loads of questions to fill the remaining time.  We had an awesome discussion overall and I think people really got some good stuff out of it.

So in a few minutes the tattoo artist will be back to get me.  I’m getting an old school radio microphone with WCSTL in red lettering above it.  I added a pic below, skin is swollen, pink and twisted a little weird, it looks really good though and can’t wait for it to heal.

Up next, June 4th in Asheville, I’ll be presenting on leveling up as a developer.