Creating Plugin Settings Page without dealing with Official Settings API

This is what we are going to create:

TLDR;

Download the sample plugin, install it to see it in action or simply explore the code. Pass a config array to the helper class constructor and Boom! your plugin options page with auto-sanitized input is ready to rock.

What is it?

Its a helper class that you may require in your plugin and create plugin Settings page by just passing configuration array.

Why should i use it?

Create plugin options page without the pain of dealing with Settings API
One config array to create everything: admin menu, settings page, sections, fields.
Fields input is auto sanitized
Can be used to make Tabs or Tab-less Settings page
Can be used to add plugin action links
Ability to override sanitization callback
Ability to override fields display callback

How to use?

Complete Details can be found in the Wiki, in the nutshell, follow the steps:

copy the class in plugin vendor folder and require the class in your plugin files (add dependency)
hook into admin_menu and provide a callback function
in the callback function, pass the config array to this helper class object to build your sections and fields.

Its that easy. Here is a simple example code that will create a plugin menu, 2 sections and some fields under these sections.

Available Field Types:

Following Field Types can be added using this Helper Class:

text
url
number
color
textarea
radio
select
checkbox
multicheck
media
file
posts (WP posts and Custom Post Types)
pages (WP pages)
password
html

Step-by-Step: Creating Setting Page

1. Create admin_menu hook:

function plugin_menu_using_boo_setting_helper_simple() {
	// Our Code goes here
}

add_action( 'admin_menu', 'plugin_menu_using_boo_setting_helper_simple' );

2. Require helper class

Next step is to require our helper class.

function plugin_menu_using_boo_setting_helper_simple() {
	// Require Settings Helper Class
	require_once 'vendor/boospot/boo-settings-helper/class-boo-settings-helper.php';

}

3. Configuration Array

configuration array is the main array that shall be passed to the helper class. Complete configuration details can be found on Settings Configuration Array Wiki Page. It mainly has following 6 components.

$config_array = array(
	'prefix'   => 'plugin_prefix_',   // string to prefix with options id (optional)
	'tabs'     => true,     // true | false  (optional)  ( Default: true )
	'menu'     => array(),  // array of menu configuration
	'sections' => array(),  // array of arrays configuring sections
	'fields'   => array(),  // array of arrays configuring fields. array key same as sections  
	'links'    => array()   // configuration array for links (optional)
);

Lets start building these components

3.1. Prefix options ids

We should always prefix anything that goes in global namespace, so we can define our prefix once and it shall be added to all fields automatically

function plugin_menu_using_boo_setting_helper_simple() {
	// Require Settings Helper Class
	require_once 'vendor/boospot/boo-settings-helper/class-boo-settings-helper.php';
	// Create Config Array
	$config_array             = array();
	$config_array['prefix']   = 'plugin_prefix_';

}

4. Plugin Menu

We can create plugin menu using the menu array property. Complete configuration options for different fields can be found on Menu Configuration Wiki Page.

function plugin_menu_using_boo_setting_helper_simple() {
	// ...
	// ...
	$config_array             = array();
	$config_array['prefix']   = 'plugin_prefix_';
	$config_array['menu']     = array(
		'page_title' => __( 'Plugin Name Settings', 'plugin-name' ),
		'menu_title' => __( 'Plugin Name', 'plugin-name' ),
		'capability' => 'manage_options',
		'slug'       => 'plugin-name',
		'icon'       => 'dashicons-performance',
	);

}

5. Section for Options pages

Lets create some sections to group our options. The following will create two sections, general and advance. Notice the id for sections. This shall be used to assign fields to specific sections later-on.

function plugin_menu_using_boo_setting_helper_simple() {
	// ...
	// ...
	$config_array['sections'] = array(
		array(
			'id'    => 'general_section',
			'title' => __( 'General Settings', 'plugin-name' ),
			'desc'  => __( 'These are general settings for Plugin Name', 'plugin-name' ),
		),
		array(
			'id'    => 'advance_section',
			'title' => __( 'Advanced Settings', 'plugin-name' ),
			'desc'  => __( 'These are advance settings for Plugin Name', 'plugin-name' )
		)
	);
}

6. Configure Fields for sections

The following configuration shall create two fields, one for each section. Complete configuration options for different fields can be found on Fields Configuration Wiki Page. Array key defines the section_id where the field is to displayed

function plugin_menu_using_boo_setting_helper_simple() {
	// ...
	// ...
	$config_array['fields']   = array(
		'general_section' => array(
			array(
				'id'                => 'text_field_id_1',
				'label'             => __( 'First Text', 'plugin-name' ),
				'desc'              => __( 'Simple Description', 'plugin-name' ),
				'placeholder'       => __( 'Text Input placeholder', 'plugin-name' ),
				'type'              => 'text',
			)
		),
		'advance_section' => array(
			array(
				'id'                => 'text_field_id_2',
				'label'             => __( 'Another Text Field', 'plugin-name' ),
				'placeholder'       => __( 'Text Input placeholder', 'plugin-name' ),
				'type'              => 'text',
			)
		)
	);
}

7. Pass $config_array to helper class

Now, we can pass this config array to helper class. and Voila , Your settings page is ready to rock.

function plugin_menu_using_boo_setting_helper_simple() {
	// Require Settings Helper Class
	require_once 'vendor/boospot/boo-settings-helper/class-boo-settings-helper.php';
	// Create Config Array
	$config_array             = array();

	// ...
	// ...
	// ...

	// Pass Config Array to Class Constructor
	$settings_helper = new Boo_Settings_Helper( $config_array );
}

8. Create Plugin Links

You may also create plugin action links by passing the array param link. Details of link config is on the Wiki Page.

function plugin_menu_using_boo_setting_helper_simple() {
	$config_array             = array();
	// ...
	// ...
	// ...
	$config_array['links']    = array(
		'plugin_basename' => plugin_basename( __FILE__ ),
		'action_links'    => array(
			array(
				'type' => 'default',
				'text' => __( 'Configure', 'plugin-name' ),
			),
			array(
				'type' => 'internal',
				'text' => __( 'Gravity Forms', 'plugin-name' ),
				'url'  => 'admin.php?page=gf_edit_forms',
			),
			array(
				'type' => 'external',
				'text' => __( 'Github Repo', 'plugin-name' ),
				'url'  => 'https://github.com/boospot/boo-settings-helper',
			),
		),
	);

	// Pass Config Array to Class Constructor
	$settings_helper = new Boo_Settings_Helper( $config_array );
}

Full Code to create all field types

You may check the Detailed Example to create the settings page with all field types.

Final Thoughts

Using this class has helped me a lot while creating custom plugins for my own sites and clients. For me the benefit of not having to deal with official Settings API is a huge plus 🙂