README

An abstract class that simplifies the process of creating WordPress admin settings pages using the WordPress Settings API.

Installation

You can install this package via Composer:

composer require yipresser/wp-settings-api-helper

Alternatively, you can use this class in your WordPress plugins or themes to easily define settings sections, fields, and handle their saving process.

Usage

To use the helper, create a new class that extends Yipresser\WpSettingsApiHelper\WP_Settings_API_Helper.

1. Extend the Class and initialize the Settings

You need to define $settings_options for your database options and $settings_sections for the visual sections and fields you want to show on the page. Lastly, you need to run the setup() method.

namespace MyPlugin\Admin;

use Yipresser\WpSettingsApiHelper\WP_Settings_API_Helper;

class My_Settings extends WP_Settings_API_Helper {

    public function __construct() {
        add_action( 'admin_init', [ $this, 'init' ] );
	}
      
    /**
	 * Start the engine running
	 *
	 * @return void
	 */
	public function init() {
        // Define your options
        $this->settings_options = [
            [
                'option_group' => 'my_plugin_settings_group',
                'option_name'  => 'my_plugin_settings',
                // Optional args for register_setting():
                // 'args' => [ 'sanitize_callback' => [$this, 'sanitize_settings'] ]
            ]
        ];

        // Define your sections and fields
        $this->settings_sections = [
            [
                'id'          => 'my_plugin_general_section',
                'title'       => 'General Settings',
                'description' => 'These are the general settings for the plugin.',
                'menu_slug'   => 'my_plugin_slug', // Slug of the settings page
                'option_name' => 'my_plugin_settings',
                'fields'      => [
                    [
                        'type'    => 'text',
                        'title'   => 'API Key',
                        'id'      => 'api_key',
                        'name'    => 'api_key',
                        'default' => '',
                        'desc'    => 'Enter your API key here.',
                    ],
                    [
                        'type'    => 'checkbox',
                        'title'   => 'Enable Feature',
                        'id'      => 'enable_feature',
                        'name'    => 'enable_feature',
                        'label'   => 'Check to enable',
                        'default' => 0,
                    ]
                ]
            ]
        ];
        $this->setup();
    }
}

2. Display the Settings Form

When rendering your options page HTML, call the render_settings_on_page() method so it can generate the settings form, fields, and submit button.

// Assuming this is inside your admin page callback function
public function my_plugin_options_page() {
    echo '<div class="wrap">';
    echo '<h1>My Plugin Options</h1>';
    
    // Pass the menu_slug used in your $settings_sections
    $my_settings->render_settings_on_page( 'my_plugin_slug' );
    
    echo '</div>';
}

Supported Field Types

The type key in your field configuration supports the following values:

text
number (supports min and max attributes)
email
password
textarea
code-editor (supports optional code_type and code_theme)
select (requires a choices array ['value' => 'Label'])
radio (requires a choices array)
checkbox (optional label for text next to checkbox)
checkboxes (requires a choices array)
slider-checkbox
dropdown_pages
hidden
callback (requires callback and optional param keys to render custom HTML)

Example Select Field

[
    'type'    => 'select',
    'title'   => 'Select Mode',
    'id'      => 'mode',
    'name'    => 'mode',
    'choices' => [
        'light' => 'Light Mode',
        'dark'  => 'Dark Mode'
    ],
    'default' => 'light'
]

Example Code Editor Field

[
    'type'       => 'code-editor',
    'title'      => 'Custom CSS',
    'id'         => 'custom_css',
    'name'       => 'custom_css',
    'code_type'  => 'css',
    'code_theme' => 'dracula',
    'default'    => '',
]

code_type accepts shorthand values like css, js, javascript, php, html, json, scss, and markdown, or a full MIME-style value like text/css or application/x-httpd-php.

If you set code_theme, the helper only passes the theme name to CodeMirror. It does not enqueue the theme stylesheet for you. You can get the matching CodeMirror 5 theme CSS file from https://github.com/codemirror/codemirror5/tree/master/theme, add it to your plugin or theme, and enqueue it yourself:

add_action( 'admin_enqueue_scripts', function() {
    wp_enqueue_style(
        'my-plugin-codemirror-theme',
        plugins_url( 'assets/css/codemirror/dracula.css', __FILE__ ),
        [ 'wp-codemirror' ],
        false
    );
} );

Sanitization and Validation

By default, a placeholder sanitize_settings method is provided which returns the options untouched. You need to override sanitize_settings($option) in your child class to safely sanitize your data before saving them to the database.

public function sanitize_settings( $option ) {
    if ( isset( $option['api_key'] ) ) {
        $option['api_key'] = sanitize_text_field( $option['api_key'] );
    }
    return $option;
}

yipresser / wp-settings-api-helper

Maintainers

Package info

Statistics

Security