WordPress add_option: Store Settings Safely [Guide]

Need store one plugin setting, an API key, or a small site-wide value? WordPress already provides a database-backed API for this job. The WordPress add_option function creates an option only when that option name does not already exist.

This guide explains the function signature, autoload behavior, return value, and complete option lifecycle. You will also see when to use update_option() instead.

What WordPress add_option Does

WordPress stores site-wide settings in the options table, commonly named wp_options. The table prefix can differ, so code should use WordPress functions rather than direct SQL.

add_option() inserts a new row with an option name and value. It does not overwrite an existing option with the same name. That behavior makes it useful for first-run defaults during plugin activation or theme setup.

Tip: Prefix custom option names with your plugin or company name. Names such as acme_checkout_settings reduce collisions with WordPress core and other plugins.

add_option Syntax and Arguments

<?php
add_option( string $option, mixed $value = '', string $deprecated = '', string|bool $autoload = 'yes' );

• $option is the unique option name.
• $value is the initial value. WordPress can store strings, numbers, arrays, and objects after serialization.
• $deprecated is retained for backward compatibility. Pass an empty string when using positional arguments.
• $autoload controls whether WordPress loads the value automatically on normal requests. Use yes or no.

How to Add an Option

For a plugin, add default settings during activation. The function returns true when it creates the option and false when the name already exists or insertion fails.

<?php
function acme_activate() {
    add_option(
        'acme_settings',
        array(
            'enabled' => true,
            'endpoint' => '',
        ),
        '',
        'no'
    );
}

register_activation_hook( __FILE__, 'acme_activate' );

Keep activation defaults small and predictable. Do not create a new option on every page request. Repeated calls add unnecessary database work, even though WordPress prevents duplicate option names.

[screenshot] Brief description: plugin activation code in a code editor, showing a prefixed option name and the no autoload value.

Read, Update, and Delete Options

Adding an option is only one part of its lifecycle. Use related core functions for later operations:

<?php
$settings = get_option( 'acme_settings', array() );

$settings['enabled'] = false;
update_option( 'acme_settings', $settings, false );

delete_option( 'acme_settings' );

• get_option() reads a value and accepts a fallback.
• update_option() changes an existing value or creates it when needed.
• delete_option() removes an option, commonly during plugin uninstall.
• get_site_option() reads network-wide settings in multisite installations.

For a full explanation of retrieval and defaults, see WordPress get_option Function. Use WordPress Developer Reference when checking current parameter details.

Autoload and Performance

Autoloaded options are loaded into memory for most WordPress requests. This is convenient for small settings used everywhere, but large arrays or rarely used data should normally use no.

Choose autoload deliberately. One oversized option can increase memory use and slow every request. If an option grows over time, split unrelated data or store records in a custom table instead.

[screenshot] Brief description: database or site-health view showing autoloaded options and a compact plugin settings value.

Common Mistakes

• Expecting overwrite behavior: add_option() does not replace an existing value. Use update_option() for changes.
• Using generic names: prefix names to avoid conflicts.
• Autoloading large data: set autoload to no for infrequent or bulky values.
• Direct SQL edits: use the Options API so caching and serialization work correctly.
• Deleting shared data: remove only options owned by your plugin during uninstall.

FAQs About WordPress add_option

Does add_option overwrite an existing option?

No. It returns false when option name already exists. Use update_option() to change value.

What does add_option return?

It returns true when new option is added and false when option already exists or cannot be inserted.

Should add_option autoload settings?

Small values used on most requests can autoload. Large or rarely used values should usually use no.

Where should plugin options be created?

Create defaults during plugin activation. Read and update them only where feature needs them.

Conclusion

The WordPress add_option() function gives plugins and themes a reliable way to create site-wide settings. Prefix option names, choose autoload behavior carefully, and use the right lifecycle function for reading, updating, and cleanup.

Need help building or repairing a custom WordPress plugin? Explore my WordPress plugin development service or hire an expert for your project.