As we can see, we use wp scaffold plugin pluginname to create the plugin. Once it’s created, we activate it — optionally also using WP CLI, with wp plugin activate pluginname.

Once it’s activated, we open the main plugin file — in this case sitepoint-settings-api.php.

Creating the Admin Page

It isn’t necessary to use WP CLI for this plugin. We could have simply created a directory with the name of the plugin, and the PHP file inside it with the same name. Anyhow, the creation of the plugin has left us with a sitepoint-settings-api.php which looks like this:

All the arguments are self-explanatory. $menu_slug must be a unique string that WordPress will use internally, but will also be reflected in the URL. $function is a string with a name of the function that will provide HTML output for our admin page.

After we’ve saved the file (presuming we activated our plugin), we’ll open our administration dashboard, and we’ll find our Settings API Page under Settings in the left side menu.

We can control, to a degree, the order or position of the submenu item by adding a priority argument to our add_action() function:

add_action( 'admin_menu', 'sitepoint_settings_page', 1 );

If we want to have our menu item to be in the root menu — rather than the Settings submenu — we’ll use add_menu_page(), which takes similar arguments.

Now, if we open the page in our browser, all we’ll see is an empty page, because we still haven’t created the settings_api_page() function that we specified:

The Settings API

The WordPress Settings API is an intricate mechanism that attempts to provide an easy way for developers to create settings pages.

Before we go into a full-fledged example of the settings page displaying and saving a setting to the WordPress database, we’ll explain couple of crucial functions that WordPress provides as part of its Settings API.

register_setting() is a function we use to register a setting, which equals a row in wp_options table. Before we can create actual field (or fields, as setting can be an array of values), we need to register it. This way we’ll leverage the WordPress CRUD mechanism for settings. Function arguments are as follows:

Of these, $id, $title, $callback and $page are required. The $callback function should output the HTML of the input field.

The Settings API provides $page argument for add_settings_section and add_settings_field as a means to add sections and fields to existing settings pages. We’ll use stpPlugin for both our option group — in register_setting() — and for attaching the settings section and settings fields to a ‘stpPlugin’ page in the add_settings_section() and add_settings_field() functions. We’ll then “quote it” in the next two functions in our example, to output relevant HTML.

settings_fields() outputs “nonce, action, and option_page fields for a settings page”. It takes the $option_group argument, used in register_setting().

do_settings_sections() outputs all the sections, with their respective fields, registered for a specific $page.

$page is the only argument here.

Having explained these functions, we now proceed to some actual code. The previous PHP code we added to the sitepoint-settings-api.php file we replace with the following:

Here we hook the stp_api_settings_init() function to the admin_init hook. There we define and register our settings, sections and fields.

stp_api_text_field_0_render() and stp_api_select_field_1_render() define HTML output of our two fields, text and select field, both belonging to the same stpPlugin group and stp_api_settings option — or setting — in the wp_options table in the database.

Lastly, we define stp_api_options_page(), which outputs the HTML for our admin options page. We incorporate the settings sections and fields in it. We’ve referred to this function at the top of our file, in the stp_api_add_admin_menu() function, where we registered the admin (options) page.

When we now go, again, to our settings page, we’ll see that it’s no longer empty:

If we try changing and saving these fields, we will see, upon refresh, that it works! WordPress abstracts away the database transactions for us, nonces, etc.

We could further add some validation functionality, further styling of this page, and other things.

If we go to WP CLI and try to run wp option get stp_api_settings — after we’ve changed some values for these two fields — we’ll get this:

This shows us that these two fields were saved in our wp_options database as fields of an array, as stp_api_settings setting.

If we now go to WP CLI shell, we can try out the code we’ll use to fetch these options in our plugin or theme files:

Conclusion

WordPress has become prominent in the web industry because of its ease of use and its gentle learning curve for developers. The Settings API is one example of this user-friendliness.

In this guide, we’ve introduced the WordPress Settings API. Much more can be said on this topic, but the intro we’ve presented here should demystify the topic to enable resourceful hackers to build their own solutions starting from this.