README

Stop fighting the WordPress Settings API. This framework provides a modern, object-oriented, and fluent API that streamlines the creation of powerful and maintainable settings pages.

Showcase

Create anything from a simple plugin options page to a complex, tabbed interface for a theme, all with the same clean API.

Simple Layout

A single page with one or more sections of fields. Perfect for most plugins.

Tabbed Layout

Organize a large number of settings into a clean, tabbed interface, complete with Dashicons for a native WordPress feel.

Why This Framework?

✅ Declarative & Fluent API: Define entire pages with a clean, chainable API that is easy to read and version control.
🚀 Comprehensive Field Library: Over 30 field types included, from basic inputs to advanced AJAX-powered relationship pickers.
🧠 Built-in Conditional Logic: Show or hide fields based on other fields' values without writing a single line of JavaScript.
⚙️ Intelligent Asset Loading: CSS and JS are loaded only when a field that needs them is used, keeping your admin pages lightweight and fast.
⚡ High-Performance Relational Fields: Add searchable fields for Posts, Users, and Terms that load data via AJAX, ensuring excellent performance even on sites with thousands of entries.
🔒 Secure by Default: Built-in sanitization for all standard field types and secure handling for sensitive data like password fields (values are never rendered in the HTML).
🧩 Truly Extensible: Designed from the ground up to be extended. Register your own custom field types to meet any project requirement.

The 3-Step Workflow

The framework follows a simple and memorable pattern:

create(): Get a Settings_Builder instance and create a new Settings_Page.
configure(): Use the fluent methods (set_page_title, add_section, add_field, etc.) to define the entire structure and content of your page.
init(): Make one final call to init() to build the page and register all the necessary hooks with WordPress.

Installation

Install via Composer into your plugin or theme:

composer require wptechnix/wp-settings-builder

Ensure your project includes the Composer autoloader:

require_once __DIR__ . '/vendor/autoload.php';

Quick Start: A Practical Example

This example creates a settings page with three powerful fields and shows how to retrieve a saved value.

1. Create the Settings Page

<?php
use WPTechnix\WP_Settings_Builder\Settings_Builder;

// 1. CREATE: Get a builder and create a page instance.
$page = ( new Settings_Builder() )->create( 'my_plugin_options', 'my-plugin-settings' );

// 2. CONFIGURE: Define the page's location, sections, and fields.
$page->set_page_title( 'My Awesome Plugin Settings' )
        ->set_menu_title( 'My Plugin' )
        ->set_parent_slug( 'tools.php' ); // Places it under the "Tools" menu

$page->add_section( 'api_section', 'API & General Configuration' );

$page->add_field( 
    'api_key', 
    'api_section',
    'password', 
    'Service API Key',
    [
        'description' => 'Your secret key is masked and protected.',
    ]
);

$page->add_field( 
    'enable_feature', 
    'api_section', 
    'switch', 
    'Enable Awesome Feature',
    [
        'description' => 'Turn the main feature on or off.',
        'default'     => true,
    ]
);

$page->add_field( 
    'featured_post', 
    'api_section', 
    'post', 
    'Featured Post', 
    [
        'description' => 'Type to search for a post to feature on the homepage.',
        'query_args'  => [ 'post_type' => 'post' ],
    ]
);

// 3. INITIALIZE: Build the page and register all WordPress hooks.
$page->init();

2. Retrieve a Setting

To use a saved setting elsewhere in your code:

use WPTechnix\WP_Settings_Builder\Settings_Builder;

$settings_page = Settings_Builder::get_instance( 'my-plugin-settings' );

if ( $settings_page ) {
    $featured_post_id = $settings_page->get_setting( 'featured_post', 0 );
    
    if ( $featured_post_id > 0 ) {
        // Now you can use this ID in a WP_Query or get_post().
        $post_title = get_the_title( $featured_post_id );
    }
}

Field Reference Table

This is a quick reference for all available field types. For detailed options and examples, see the full documentation guides.

Type	Description	Saves As	Key Options
Basic Inputs
`text`	A standard single-line text input.	`string`	`default`, `html_attributes`
`url`	An input for URLs.	`string`	`placeholder`
`email`	An input for email addresses.	`string`	`default`
`password`	A secure input for API keys/passwords.	`string`	`description`
`number`	An HTML5 number input.	`string`	`default`, `min`, `max`, `step`
`textarea`	A multi-line text area.	`string`	`rows`, `cols`
`color`	The native WordPress color picker.	`string`	`default`
Choice & Toggles
`checkbox`	A standard single checkbox.	`bool`	`description`, `default`
`switch`	A modern, styled toggle switch.	`bool`	`description`, `default`
`choice`	Radio buttons for selecting one option.	`string`	`options`, `default`
`buttons_group`	A styled, segmented button control.	`string`	`options`, `default`
`select`	A searchable dropdown (Select2).	`string`	`options`, `default`
`multi_check`	Checkboxes for selecting multiple options.	`string[]`	`options`, `default`
`multi_select`	A searchable multi-select dropdown.	`string[]`	`options`, `default`
Content & Media
`wysiwyg`	The WordPress TinyMCE rich text editor.	`string`	`editor_settings`
`code_editor`	A syntax-highlighting code editor.	`string`	`mode`, `editor_settings`
`media`	Select a single item from the Media Library.	`int`	`media_settings`
`media_multiple`	Select multiple items from the Media Library.	`int[]`	`media_settings`
Date & Time Pickers
`date`	A date picker (Flatpickr).	`string`	`display_format`, `flatpickr_options`
`time`	A time picker (Flatpickr).	`string`	`display_format`, `flatpickr_options`
`date_time`	A combination date and time picker.	`string`	`display_format`, `flatpickr_options`
`date_range`	A date range picker.	`string[]`	`display_format`
`date_time_range`	A date and time range picker.	`string[]`	`display_format`
Relational (AJAX)
`post`	AJAX search for a single post/page.	`int`	`query_args`
`posts`	AJAX search for multiple posts/pages.	`int[]`	`query_args`
`user`	AJAX search for a single user.	`int`	`query_args`
`users`	AJAX search for multiple users.	`int[]`	`query_args`
`term`	AJAX search for a single taxonomy term.	`int`	`query_args`
`terms`	AJAX search for multiple taxonomy terms.	`int[]`	`query_args`
Helpers
`description`	Displays read-only text/HTML.	`(not saved)`	`description`

Full Documentation

For a deep dive into every feature and method, please see the full documentation.

Contributing

Contributions are welcome! Please feel free to open a pull request or submit an issue on the GitHub repository with your suggestions or bug reports.

License

This project is licensed under the MIT License. See the LICENSE file for details.

wptechnix / wp-settings-builder

Maintainers

Details