README

A helper package for working with the WordPress Settings API

Installation

composer require ralfhortt/wp-settings

Usage

Settings Page

The Settings Page approach uses the WordPress Settings API to create admin settings pages and subpages.

Basic Usage

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page('My Theme Settings')
    ->panel( __('My Panel', 'textdomain') )
        ->section( __('My Section', 'textdomain') )
            ->checkbox( 'my-checkbox', __('Checkbox', 'textdomain') )
            ->color( 'my-color', __('Color', 'textdomain') )
            ->file( 'my-file', __('File', 'textdomain') )
            ->image( 'my-image', __('Image', 'textdomain') )
            ->pageDropdown( 'my-page', __('Page', 'textdomain') )
            ->radio( 'my-radio', __('Radio', 'textdomain'), ['option1' => 'Option 1', 'option2' => 'Option 2'] )
            ->select( 'my-select', __('Select', 'textdomain'), ['option1' => 'Option 1', 'option2' => 'Option 2'] )
            ->text( 'my-text', __('Text', 'textdomain') )
            ->textarea( 'my-textarea', __('Textarea', 'textdomain') )
            ->wysiwyg( 'my-wysiwyg', __('WYSIWYG', 'textdomain') )
            ->url( 'my-url', __('Url', 'textdomain') )
    ->register();

Pages default to the Settings menu. Use a location method to place the page elsewhere (see Page Location).

Settings Page Configuration

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page(
        'Theme Configuration',
        'Theme Config',                    // menu title
        'my-theme-config',                // slug
        'edit_theme_options'              // capability
    )
    ->themesPage()
    ->panel('Design Settings')
        ->section('Colors')
            ->color('primary-color', 'Primary Color')
    ->register();

Page Location

Choose where the settings page appears in the WordPress admin menu:

Method	Admin menu
`optionsPage()`	Settings (default)
`themesPage()`	Appearance
`toolsPage()`	Tools
`pluginsPage()`	Plugins
`usersPage()`	Users
`topLevel($icon, $position)`	Top-level sidebar item
`subpageUnder($slug)`	Custom parent (escape hatch)

<?php
use RalfHortt\Settings\SettingsPage;

// Under Settings (optional — this is the default)
(new SettingsPage)
    ->page('Plugin Settings')
    ->optionsPage()
    ->register();

// Under Appearance
(new SettingsPage)
    ->page('Theme Options')
    ->themesPage()
    ->register();

// Under Tools
(new SettingsPage)
    ->page('Import / Export')
    ->toolsPage()
    ->register();

// Top-level menu item
(new SettingsPage)
    ->page('Brand Manager')
    ->topLevel('dashicons-art', 25)
    ->register();

// Custom parent (WooCommerce products, plugin menus, etc.)
(new SettingsPage)
    ->page('Product Settings')
    ->subpageUnder('edit.php?post_type=product')
    ->register();

Multiple Panel Tabs On One Page

When you register more than one panel on the same page, the page renders panel tabs automatically.

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page('Theme Configuration')
    ->themesPage()
    ->panel('Design')
        ->section('Colors')
            ->color('primary-color', 'Primary Color')
    ->panel('Content')
        ->section('Homepage')
            ->text('hero-title', 'Hero Title')
    ->panel('Integrations')
        ->section('API')
            ->url('api-endpoint', 'API Endpoint')
    ->register();

Notes:

Panels become tabs only when at least two panels exist.
A panel can contain multiple sections.
Section order follows the order you define in your fluent chain.

Top-Level Menu Page

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page(
        'Brand Manager',        // title
        null,                   // menu title (defaults to title)
        null,                   // slug (auto-generated)
        'manage_options'        // capability
    )
    ->topLevel('dashicons-art', 25)
    ->panel('Brand Assets')
        ->section('Logos')
            ->image('main-logo', 'Main Logo')
    ->register();

Advanced Usage

Settings Page Advanced Features

Options Storage

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page('My Settings')
    ->panel( __('My Panel', 'textdomain')  )
        ->section( __('My Section', 'textdomain') )
            ->text(
                'my-text',                    // identifier
                __('My Text', 'textdomain'),  // label
                ''                            // default value
            )
    ->register();

Check for a capability

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page('My Settings')
    ->panel( 'My Panel' )
        ->section( __('My Section', 'textdomain') )
            ->text(
                'my-text',                    // identifier
                __('My Text', 'textdomain'),  // label
                '',                           // default value
                'edit_posts'                  // capability
            )
    ->register();

Add a description

<?php
use RalfHortt\Settings\SettingsPage;

(new SettingsPage)
    ->page('My Settings')
    ->panel( 'My Panel' )
        ->section( 'My Section' )
            ->text(
                'my-text',                               // identifier
                'Text',                                  // label
                '',                                      // default value
                '',                                      // capability
                __('This is awesome', 'textdomain')     // description
            )
    ->register();

Retrieving data

<?php
// Retrieve data from your settings page fields
$option = get_option('my-text');

Changelog

Unreleased

Add wysiwyg() field type
Add named page location methods: optionsPage(), themesPage(), toolsPage(), pluginsPage(), usersPage()

v1.0.0

Initial release

ralfhortt / wp-settings

Maintainers

Package info

Statistics

Security