function to initiate your plugin options, run on plugin activation as covered in Chapter 2, could then look like the following:
<?php function pdev_plugin_create_options() { // front-end options: autoloaded add_option( 'pdev_plugin_options', array( 'color' => 'red', 'fontsize' => '120%', 'border' => '2px solid red' ) ); // back-end options: loaded only if explicitly needed add_option( 'pdev_plugin_admin_options', array( 'version' => '1.0', 'donate_url' => 'https://example.com/', 'advanced_options' => '1' ), '', 'no' ); } ?>
Again, don't forget the empty third parameter before the autoload value. This might seem a bit convoluted, and actually it is for so few options set. This professional technique makes sense if your plugin features dozens of options, or options containing long text strings.
NOTE As a rule of thumb, if your options are needed by the public part of the blog, save them with autoload. If they are needed only in the admin area, save them without autoload.
Toggling the Autoload Parameter
The autoload parameter is set when an option is created with add_option() and is not supposed to change afterward. With this said, if you believe that it would improve your plugin's efficiency to modify the autoload behavior, it is possible and easy: simply delete and then re‐create the option with an explicit autoload parameter.
<?php function pdev_plugin_recreate_options() { // get old value $old = get_option( 'pdev_plugin_admin_options' ); // delete then recreate without autoload delete_option( 'pdev_plugin_admin_options' ); add_option( 'pdev_plugin_admin_options', $old, '', 'no' ); } ?>
THE SETTINGS API
Options can be internally created and updated by your plugin (for instance, storing the time stamp of the next iteration of a procedure). But they are also frequently used to store settings the end user will modify through your plugin administration page.
When creating or updating user‐defined options for a plugin, relying on the Settings API can make your code both simpler and more efficient.
Benefits of the Settings API
Dealing with user inputs introduces new constraints in the option process: you need to design a user interface, monitor form submissions, handle security checks, and validate user inputs. To easily manage these common tasks, WordPress wraps the option functions into a comprehensive Settings API.
The Settings API enables you to handle these simple tasks:
Tell WordPress that you are going to use some new options and how you want them displayed.
Specify a function that will sanitize user inputs.
while WordPress transparently manages for you these cumbersome and repetitive parts:
Draw most of the option page itself.
Monitor form submission and handle $_POST data.
Create and update options if needed.
Wield all the required security measures and hidden fields for nonces, covered in detail in Chapter 4, “Security and Performance.”
Now it's time to dissect the Settings API; you'll learn to use it through a step‐by‐step example.
Settings API Functions
The Settings API functions consist of three steps:
1 Tell WordPress the new settings you want it to manage for you. Doing so adds your settings into a list of authorized options (also known as whitelisting).
2 Define the settings (text areas, input boxes, and any HTML form element) and how they will be visually grouped together in sections.
3 Tell WordPress to display your settings in an actual form.
But first, you create a setting management page for your plugin.
Creating the Plugin Administration Page
The plugin page will be located at Settings ➪ PDev Settings:
<?php // Add a menu for our option page add_action( 'admin_menu', 'pdev_plugin_add_settings_menu' ); function pdev_plugin_add_settings_menu() { add_options_page( 'PDEV Plugin Settings', 'PDEV Settings', 'manage_options', 'pdev_plugin', 'pdev_plugin_option_page' ); } // Create the option page function pdev_plugin_option_page() { ?> <div class="wrap"> <h2>My plugin</h2> <form action="options.php" method="post"> </form> </div> <?php } ?>
This page is empty for now. You will add form inputs later. Creating pages for plugins is covered in detail earlier in the “Plugin Settings” section of this chapter, so refer to it for more explanation about this code.
Registering New Settings
The next step is to register your new settings. The function you need here is register_setting() and three parameters, used as follows:
<?php register_setting( option group, option name, args ); ?>
The register_setting()function accepts the following parameters:
option_group: Group name for your settings.
option_name: Name of an option to sanitize and save.
args: Data used to describe the setting when registered.type: Type of data associated with this setting. Valid values are string, boolean, integer, and number.description: Description of the data for this setting.sanitize_callback: Callback function to sanitize the option's value.show_in_rest: Whether the data with this setting should be included in the REST API.default: Default value when calling get_option().
Now let's register your plugin settings using the register_setting() function. The first parameter you'll set is the setting group name, and the second parameter is the option name as you would use it in a get_option() call. The group name can be anything actually, but it's just simpler to name it the same as the option that will get stored in the database.
The third parameter is an array of additional arguments defining the type of data. In this case, it's a string and references your callback function, here named pdev_plugin_validate_options(), that will be passed all the settings saved in your form. You'll define this function later.
<?php $args = array( 'type' => 'string', 'sanitize_callback' => 'pdev_plugin_validate_options', 'default' => NULL ); register_setting( 'pdev_plugin_options', 'pdev_plugin_options', $args ); ?>
