As WordPress developers, we often need a way to store and retrieve data. The most common reason for that is that we need to store and retrieve settings for our plugin or theme. But the reality is that there are countless of other reasons why you’d need to store and retrieve data.
So how do we do it? Well, the primary tool that we have at our disposal to do this is the options API. It’s an API that offers a way for us to store and retrieve data from the WordPress database.
It’s pretty much as indispensable as the plugin API. We often can’t build anything in WordPress without it. That’s why it’s worth looking a bit deeper at how it works.
The wp_options table
At its core, the options API is an API that lets us interact with the
wp_options database table. With it, we can add, remove and update values stored in the database table. The database table itself has four columns:
option_id is the primary key of the
wp_options table. It autoincrements each time that MySQL adds a new row to the table. But, in practice, WordPress doesn’t use it for anything.
The two important columns of the
wp_options table are the
option_value columns. WordPress uses these two columns as a key-value pair. This is a form of data representation where we assign data to a key. PHP associative arrays work the same way.
The options API doesn’t expect you to use
option_id to retrieve your data. In fact, it doesn’t even let you use it. What it wants is for you to always use a key to store your data. And you use that same key to retrieve it.
The last column of the
wp_options table is the
autoload column. This is a flag used to determine whether WordPress will autoload an option or not. The flag should be one of two values:
On option autoloading
So what’s special about autoloading an option? Well, let’s imagine that you need to know the value of a specific option. You’ll use the options API to fetch that option from the database. And, to do that, WordPress will need to perform a SQL query.
Now, let’s say that you need another option. WordPress will need to query the database one more time to get it. Making SQL queries over and over like that doesn’t scale well at all.
So to solve this problem, WordPress created the concept of autoloaded options. WordPress will load all options that have the
autoload flag set to
yes in memory. This reduces the number of SQL queries that WordPress needs to do to fetch options from the database.
From a code perspective, the
wp_load_alloptions function is in charge of loading all the autoloaded options. In practice, you shouldn’t need to ever use this function. Every time that you use the options API it will call the
wp_load_alloptions function if it needs to load all the autoloaded options.
Alright, this pretty much covers everything surrounding the
wp_options table in the database. Next, let’s look at the options API functions themselves. We’re going to group them into four categories: adding, deleting and getting and updating options.
Types of API functions
First, it’s worth noting that each options API function comes in two types: regular and multisite. The regular functions are the ones that most of us use. They interact with the
wp_options table that we just discussed.
Meanwhile, the multisite versions all have
_site_ in their name. All multisite options API functions behave more or less the same as their regular counterpart. But they do have two architectural differences that are worth pointing out.
The other difference is that site options (as we call them) are all autoloaded whether you want to or not. You don’t have a flag that you can set to control whether WordPress will autoload them or not. This might seem like a big change, but it’s not.
The reality is that most of the time we don’t overwrite the default autoload flag. We leave it as is. This which means that WordPress will autoload most of the options that we add anyways.
What if I don’t know which one to use?
Having to think about which type of functions to use can be annoying. That’s why there’s a third lesser known type of functions that you can use instead of the two that we’ve seen. These are the network option functions.
Like the multisite functions, the network functions have
_network_ in their name. But, unlike the other two types of options API functions, the network ones don’t interact with a specific database table. They will pick whether to use the
wp_sitemeta table based on whether WordPress is using multisite or not.
Using these functions can be useful if you’re not sure which type of function to use. They’ll ensure that there’s only one set of options for your plugin whether someone is using multisite or not. So you should keep those functions in mind for those situations.
That said, the rest of this article will focus on the regular and multisite types of functions. That’s because these are the functions that you’ll use the most. They’re also the ones that interact with the WordPress database tables.
Adding an option
The first set of functions that we’ll see deal with adding new options. You have the
add_option which adds a new option to the
wp_options table. It uses four parameters:
Most of these parameters fit what we’ve talked about so far about the options API.
option is the name of the option that we want to add. Meanwhile,
value is the value of that we’ll store in the
This third parameter is deprecated (thus the name!) so you should always pass it an empty value. The last parameter is
autoload. This is the autoload flag that we’ve been talking about where the default value is
The other function that we have is the
add_site_option function. It adds a new option to the
wp_sitemeta table. It uses two parameters:
value. These two parameters are the same as the ones used by the
Both functions return a boolean value. If the function managed to add the option, the function will return
true. Otherwise, it’ll return
Deleting an option
Next up are functions that we use to delete options. You have the
delete_option to delete an option from the
wp_options table. The other function is
delete_site_option which deletes an option from the
Both functions only use one parameter. It’s the name of the option that we want to delete. They also return a boolean value like the previous functions did. The return value will be
true if the function deleted the option and
false if it didn’t.
Getting an option
After deleting an option, let’s look at the functions that you can use to get an option. As usual, we have two functions:
get_site_option. The first one is for the
wp_options table and the other is for the
Both functions use two parameters:
option is the name of the option that we’re trying to get. If the functions find a value using the
option parameters, they’ll return it. Otherwise, they’ll return the value that you passed as the
default argument of the functions.
Updating an option
Both functions use similar parameters. They both use
option is the name of the option that we want to update. Meanwhile,
value is the new value that we’re going to assign to the existing option.
That said, the
update_option function also has a third parameter:
autoload. This parameter lets you update the autoload flag of an option as well as the value.
update_site_option doesn’t use that parameter because the
wp_sitemeta doesn’t use the autoload flag.
Both functions return a boolean value. The function will return
true when WordPress updated the option. Otherwise, it’ll return
Updating an option that doesn’t exist
But what happens if we try to update an option that doesn’t exist? In that scenario, both functions will call either the
add_site_option functions. This is an important (if not the most important) thing to know about the options API.
It means that, in practice, you don’t need to use the functions to add a new option. Instead, you can just use the update functions for both adding and updating an option. This simplifies your code around these two operations.
That’s because the functions that let you add an option only work if the option doesn’t exist already. So you need to add a conditional statement to check if an option exists already if you’re going to use them.
But this isn’t necessary if you use the update option functions everywhere. So feel free to do that in your code. There’s no reason not to.
Actions and filters
Now that we’ve covered all the functions that make up the options API. Let’s talk a bit about the actions and filters that you can use with it. We’re not going to look at them all because that’s a bit excessive. (And not super useful either.)
Here’s what’s important to know. First, every options API function uses at least one dynamic action or filter. This is an action or filter with a name that follows the format:
These actions or filters allow you to target an option with a specific name. Without them, you’d have to use generic actions or filters that don’t use the option name. And then you’d have to check the option name each time WordPress calls your action or filter option.
The other important thing to know is the timing surrounding actions and filters. All option API functions have actions and filters before and after interacting with an option. This gives you another angle for targeting options using the plugin API.
For example, you can short-circuit the process of getting an option with the
get_option function. Using the
pre_option_$option filter, you can pass an option value without even querying the database. This is useful if you want to enforce a specific value for an option.
The WordPress hard drive
So that wraps up our look at the options API! As you saw, it’s a pretty small API. But don’t let its size fool you. It does a huge amount of work for WordPress.
As WordPress developers, we’re in constant contact with it. It’s a good reason to know all the little details about it. That way, you can use it to its full potential.