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. 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');

baxtian / wp_settings

Maintainers

Details