Using Custom WordPress Plugin Options

One of the most commonly used types of WordPress functions by developers are the option functions.

Options give developers an easy way to store and retrieve information from the database.

In many cases, these are used for plugin settings pages so user preferences for the plugin can be saved for future uses.

Important Note Concerning WP Option Functions

The standard WP option functions may actually not be available in all installations of WordPress! WP MultiSite actually uses option functions with a different name, so if you want your plugin to be compatible with both the standard and MultiSite installations of WordPress, be sure to account for this in your coding. See the bottom of the page for a tutorial on how to do this.

Create A WordPress Option

To start learning how to use custom options with your WordPress plugin, you first need to know how to create an option.

When you create an option, you need two pieces of information: a unique name for the option and the value of the option.

The unique name should not contain any spaces or special characters except for underscores. The value can really be almost anything, including long HTML code.

To ensure that you are using a unique name for each option, I recommend using a prefix for your plugin options. This prefix is discussed in my tutorial on naming functions, options and variables.

For this tutorial, I am going to name an example option "rsplugins_option_name". In the example script below, I am creating this option with the value of "Test option value".

add_option('rsplugins_option_name', 'Test option value');
Updating WP Options

Once an option has been created, there is often a need to change the saved value. The update_option() function accomplishes this task.

The syntax of this function is exactly the same as the function used to create the option.

The example code below shows the value being updated to "My new option value".

update_option('rsplugins_option_name', 'My new option value');
Get Option Value From Database

Obviously, there isn't much point to saving information to a database if there is no way to access it.

The get_option() function allows you to retrieve the value of any saved option in the WP database.

With this function, all you need to provide is the unique name of the option.

The saved value will be returned from this function, so be sure to save that returned value to a variable unless you only need to use it once (the function can be used directly where the value is needed, if you only need to call that value once).

This example code retrieves the value of our previously saved and updated option, then it saves that value to the variable named "rsplugins_saved_value".

$rsplugins_saved_value = get_option('rsplugins_option_name');
How to Delete An Option

Some situations may call for the need to completely delete an option from the WP database, especially in the deactivation script of a plugin.

To accomplish this, simply use the delete_option() function.

Once again, all you need to provide is the unique name of the option you want deleted.

This code deletes the option we previously used.

delete_option('rsplugins_option_name');
WordPress MultiSite Option Functions

As previously mentioned, the option functions in a WP MultiSite installation are completely different, so it is important for developers to keep this in mind.

Two things are different about the WordPress MultiSite option functions:

  1. The name of the function has an extra word: blog
  2. The function requires an extra variable: the blog id number

The code below replicates the same exact thing as the previous four code tutorials on this page, except this code works with WP MultiSite.

// This retrieves the id number of the blog, which is a global WP variable
global $blog_id;

//Create
add_blog_option($blog_id, 'rsplugins_option_name', 'Test option value');

// Update Value
update_blog_option($blog_id, 'rsplugins_option_name', 'My new option value');

// Retrieve Value
get_blog_option($blog_id, 'rsplugins_option_name');

// Delete
delete_blog_option($blog_id, 'rsplugins_option_name');

Option Code Compatible With Standard & MultiSite WordPress

Since most developers are likely looking for a way to handle WP options no matter what type of installation is being used, I thought it would be worth the effort to show you how to accomplish that.

To do this, we need to be able to do two things:

  1. Create our own option functions for use with our plugin
  2. Have our option functions detect whether WP MultiSite is being used & use the correct functions

In the example code below, I have done exactly that. I have used the function name prefix of rsplugins for this tutorial, which you will obviously want to change to your own plugin prefix.

// Universal Add Function
function rsplugins_add_option($key, $value)
{
if (is_multisite())
{
global $blog_id;
add_blog_option($blog_id, $key, $value);
}else
add_option($key, $value);
}

// Universal Update Function
function rsplugins_update_option($key, $value)
{
if (is_multisite())
{
global $blog_id;
update_blog_option($blog_id, $key, $value);
}else
update_option($key, $value);
}

// Universal Get Function
function rsplugins_get_option($key)
{
if (is_multisite())
{
global $blog_id;
$result = get_blog_option($blog_id, $key);
}else
$result = get_option($key);

return $result;
}

// Universal Delete Function
function rsplugins_delete_option($key)
{
if (is_multisite())
{
global $blog_id;
delete_blog_option($blog_id, $key);
}else
delete_option($key);
}

To use the functions above to replace the standard and multisite option functions, just call the new functions instead (same syntax and everything, just use your new function names - no messy blog id number needed now).

The example code below once again does the exact same option manipulations as the other tutorials on this page, except this time, the code can be used on both standard and multisite WordPress installations (make sure to use in combination with the new option functions above).

// Universal Create
rsplugins_add_option('rsplugins_option_name', 'Test option value');

// Universal Update Value
rsplugins_update_option('rsplugins_option_name', 'My new option value');

// Universal Retrieve Value
rsplugins_get_option('rsplugins_option_name');

// Universal Delete
rsplugins_delete_option('rsplugins_option_name');

Comments are closed.