README

Class to be inherited to create a WP Settings.

Mantainers

Juan Sebastián Echeverry baxtian.echeverry@gmail.com

🚀 Usage Guide

This library requires a minimum of two configuration files: one to define the Page and one to define a Section within that page.

1. Defining the Settings Page

The page configuration file sets up the main menu item, its location, and basic properties within the WordPress dashboard.

Property	Description	Required?	Example Value
slug	The unique identifier (slug) for this settings page in WordPress.	Yes	my_plugin_options
page_title	The title displayed at the top of the settings screen.	Yes	My Plugin Settings
sections	An array containing instances of the defined Section classes.	Yes	See examples below.
menu_title	The text displayed for the menu/sub-menu item in the dashboard.	Yes	Plugin Options
parent_slug	The slug of the existing parent menu this page belongs to.	Yes	options-general.php

Parent Slugs for Standard WordPress Menus:

• Appearance: themes.php
• Tools: tools.php
• Settings: options-general.php
• (Use a custom slug for a new top-level menu.)

<?php
namespace My_Plugin\Settings;

use My_Plugin\Settings\Section\Style;
use Baxtian\WP_Settings;

/**
 * Configuration page
 */
class My_Plugin extends WP_Settings
{
	use \Baxtian\SingletonTrait;

	protected function __construct()
	{
		$this->slug        = 'my_plugin';
		$this->parent_slug = 'options-general.php';
		$this->sections    = [
			new Style()
		];

		add_action('init', [$this, 'init']);

		parent::__construct();
	}

	public function init()
	{
		$this->page_title = __('My Plugin Settings', 'my_plugin');
		$this->menu_title = __('My Plugin', 'my_plugin');
	}

}

Filename: src/Settings/My_Plugin.php

2. Defining a Section

The section configuration defines a tab or logical grouping of settings within the Page.

Property	Description	Required?	Example Value
slug	The unique identifier (slug) for this section within the page.	Yes	general_settings_tab
title	The title displayed for the section's tab.	Yes	General Settings
subsections	An array containing the definitions for each subsection.	Yes	See Subsection Properties below.

3. Defining Subsections and Fields

The subsections array holds definitions for the fields that will actually store data, grouped logically for display.

Subsection Properties

Each item in the subsections array defines a block of related fields:

Property	Description	Notes
slug	The unique identifier (slug) for this subsection within the section.	Used internally for grouping fields.
title	The displayed title for this subsection block.	Set to false to suppress the title display.
description	Descriptive text displayed below the title.	Set to false to suppress the description.
fields	An array defining all input fields for this subsection.	See Field Properties below.

Field Properties

Each item in the fields array defines a single input control:

Property	Description	Default	Available Types
name	The unique option name used to retrieve this field's stored value.
label	The descriptive label displayed next to the field.
type	The type of input field to render.	text	text, checkbox, dropdown, number, password
default	The fallback value used if the option has not yet been saved by the user.
description	Help text displayed beneath the input field.	Set to false to hide.
class	Custom CSS classes to apply to the input element.

<?php
namespace My_Plugin\Settings\Section;

use Baxtian\WP_Settings\Section;

/**
 * Section of the configuration
 */
class Style extends Section
{
	public function __construct()
	{
		$this->slug = 'style';
		add_action('init', [$this, 'init']);

		parent::__construct();
	}

	public function init()
	{
		$this->title = __('Style', 'my_plugin');

		$this->subsections = [
			[
				'slug'        => 'colors',
				'title'       => __('Colors', 'my_plugin'),
				'description' => false,
				'fields'      => [
					[
						'name'        => 'text_color',
						'label'       => __('Text color', 'my_plugin'),
						'class'       => false,
						'description' => false,
						'default'     => 'black',
						'type'        => 'string',
					],
					[
						'name'        => 'text_background',
						'label'       => __('Text background color', 'my_plugin'),
						'class'       => false,
						'description' => false,
						'default'     => 'silver',
						'type'        => 'string',
					],
				],
			],
		];
	}
}

Filename: src/Settings/Section/Style.php

4. Extending Sections from Another Plugin

WP_Settings::__construct() applies the filter wp_settings_sections_{slug} (where {slug} is the transformed slug, e.g. 'indipos' → 'config_indipos') right after computing $this->slug and before linking sections to it. This lets a separate plugin add its own Section to an existing settings page without modifying its source:

<?php
namespace Other_Plugin\Settings;

class Sections
{
    use \Baxtian\SingletonTrait;

    protected function __construct()
    {
        add_filter('wp_settings_sections_config_indipos', [$this, 'add_section']);
    }

    public function add_section($sections)
    {
        $sections[] = new Section\MySection();
        return $sections;
    }
}

Computing the filter name: the slug passed to the filter is str_replace('-', '_', sanitize_title('Config-' . $original_slug)). For $this->slug = 'indipos' this yields config_indipos.

Load-order guarantee: as long as add_filter() runs during normal plugin loading (i.e. not deferred to a hook that fires after init), it is guaranteed to be registered before any WP_Settings subclass is constructed — WordPress finishes include-ing every active plugin's main file (where add_filter calls like the one above typically run) before it fires plugins_loaded and init. If the settings page itself is constructed eagerly (not deferred), make sure plugins that extend it register their filter unconditionally at load time, and the page-owning plugin defers its own get_instance() to init (so extending plugins always run first).

5. Retrieving an Option Value

To retrieve a field's value, call the instance of the settings class and use the get_option() method. If the field has not been configured by the user, the system automatically returns the defined default value. If the field is not registered or does not have a default value, the system generates an exception.

use My_Plugin\Settings\My_Plugin as Settings;
.
.
.
$settings = Settings::get_instance();
$text_color = $settings->get_option('text_color');
$text_background = $settings->get_option('text_background');

Changelog

0.1.11

• ✨ feat(settings): keep the tab active after saving the settings

0.1.9

• Add filter wp_settings_sections_{slug} in WP_Settings::__construct(), allowing other plugins to extend an existing settings page with their own sections.

0.1.8

• Add type image.
• Sanitize checkbox.
• Use toggler for checkboxes.

0.1.5

• Add type dropdown.

0.1.4

• Keep opened last selected tab.

0.1.3

• Add type textarea.

0.1.2

• Documentation.

0.1.1

• First stable release.