Mastering the WordPress Options API

WordPress needs a way to store small bits of sitewide data—things like your site title, admin email, or custom color schemes. That’s what the Options API handles. It’s one of those WordPress features that seems almost too simple at first, but you’ll use it constantly once you understand it.

What Are Site Options?

Site options (sometimes called “site settings”) are name/value pairs stored in your database’s wp_options table. Think of them as WordPress’s filing system for global configuration data.

Here are a few examples:

• The URL of your custom header logo
• Your site’s background color
• The admin email address
• Your timezone setting

If you’ve never looked at your wp_options table before, it’s worth checking out. You’ll find hundreds of entries. Everything from your site’s tagline to when your last cron job ran is recorded here. WordPress uses options extensively under the hood.

The Three Functions You Need to Know

The Options API gives you three functions, and they do exactly what their names suggest:

• get_option() – retrieves an option’s value
• update_option() – creates or updates an option
• delete_option() – removes an option

Let’s dig into each one.

get_option(): Reading Site Options

Getting an option is straightforward:

<?php
$site_title = get_option( 'blogname' );
?>
Code language: HTML, XML (xml)

That’s it. You pass in the option name, and WordPress returns the value.

What if the option doesn’t exist?

By default, get_option() returns false if the option isn’t set. You can specify a different default value as the second parameter:

<?php
$custom_color = get_option( 'my_theme_color', '#000000' );
?>
Code language: HTML, XML (xml)

If my_theme_color doesn’t exist, you’ll get #000000 instead of false.

Working with arrays and objects

Here’s something nice: if you stored an array or object as an option, that’s what you get back. WordPress handles the serialization automatically. No need to manually unserialize() anything.

<?php
$theme_settings = array(
    'color' => '#FF0000',
    'font_size' => 16,
    'layout' => 'sidebar-left'
);
update_option( 'my_theme_settings', $theme_settings );

// Later...
$settings = get_option( 'my_theme_settings' );
echo $settings['color']; // Outputs: #FF0000
?>
Code language: HTML, XML (xml)

update_option(): Creating and Updating Options

You use the same function for both creating and updating:

<?php
update_option( 'blogname', 'My Awesome Site' );
?>
Code language: HTML, XML (xml)

If the option already exists, WordPress updates it. If it doesn’t exist, WordPress creates it. The function returns true if the value changed, and false if it stayed the same or the update failed.

What about add_option()?

WordPress also has an add_option() function that works like this:

<?php
add_option( 'my_custom_setting', 'default_value' );
?>
Code language: HTML, XML (xml)

The difference is subtle but important: add_option() only creates the option if it doesn’t already exist. If the option is already there, add_option() does nothing and returns false.

In contrast, update_option() creates the option if it’s missing or updates it if it exists.

So why do I recommend just using update_option()? Because in practice, you rarely care whether an option already exists. You just want to set it to a specific value. Using update_option() means you don’t have to check whether the option exists first, which keeps your code simpler.

The only time add_option() is useful is when you specifically want to avoid overwriting an existing value. That’s pretty rare, which is why most WordPress developers stick with update_option() for everything.

The autoload parameter

Since WordPress 4.2, update_option() takes an optional third parameter called $autoload. This controls whether the option loads on every page request. Unless you have a specific performance reason to change this, just leave it alone. The defaults work fine for almost everyone.

delete_option(): Removing Options

Deleting is equally simple:

<?php
delete_option( 'blogname' );
?>
Code language: HTML, XML (xml)

The function returns true if the deletion succeeded, and false if it failed or the option didn’t exist.

A Real Example: April Fool’s Site Title

Let’s look at a practical example. This plugin changes your site title to “WPSnort” on April 1st, then changes it back afterward:

<?php
/*
Plugin Name: April Fool's Title Changer
*/

function april_fools_title() {
    $joke_title = 'WPSnort';
    $site_title = get_option( 'blogname' );

    // Store the original title if we haven't already
    if ( $site_title !== $joke_title ) {
        update_option( 'site_normal_title', $site_title );
    }

    // Switch to joke title on April 1
    $today = date( 'F j' );
    if ( $today === 'April 1' ) {    
        update_option( 'blogname', $joke_title );
        return;
    }

    // Switch back to normal title after April 1
    $normal_title = get_option( 'site_normal_title' );
    if ( $site_title === $joke_title && $normal_title ) {
        update_option( 'blogname', $normal_title );
    }
}
add_action( 'init', 'april_fools_title' );
?>
Code language: PHP (php)

This example shows both get_option() and update_option() in action. Notice how we create a new option (site_normal_title) to store the original title so it doesn’t get lost.

Here’s the thing though… This approach works, but it’s messier than it needs to be. All those conditional statements and temporary variables are a code smell. A cleaner way would be to filter the site title on April 1st instead of actually changing the database value. If you find yourself writing lots of nested conditionals with the Options API, there’s usually a simpler approach.

☝️ Quick Tip: View All Options at Once
Want to see every option on your site without touching the database? Go to http://yoursite.com/wp-admin/options.php in your browser. WordPress shows you a complete list of every option, which is incredibly handy for debugging or just understanding what your site stores.

When to Use the Options API

The Options API works great for:

• Theme and plugin settings
• Sitewide configuration data
• Small pieces of data that don’t fit elsewhere
• Anything you’d set once and rarely change

Don’t use it for:

• Data that belongs to specific posts or pages (use post meta instead)
• User-specific data (use user meta)
• Large datasets (use custom database tables)
• Rapidly changing data (options aren’t built for high-frequency updates)

Options API vs. Custom Fields

If you’re familiar with custom fields (post meta), the Options API probably looks familiar. The main difference is scope: custom fields attach to individual posts, while options are sitewide. The API structure is almost identical and both use simple name/value pairs and similar functions (get_post_meta() vs get_option(), etc.).

That’s Really All There Is to It

The Options API is one of WordPress’s simpler features, which is part of its charm. Three functions, straightforward syntax, and you can control global settings across your entire site. Once you’ve got these basics down, you’ll find yourself reaching for the Options API constantly in theme and plugin development.