class-option-page.php

<?php
/**
 * Class used to create a new options page.
 * 
 * @package WP_Options_Page
 * @author Mikael Fourré
 * @version 1.4.0
 * @see https://github.com/FmiKL/wp-options-page
 */
class Option_Page {
    /**
     * Path to the assets.
     * 
     * @var string
     * @since 1.0.0
     * @see Option_Page::enqueues_scripts()
     */
    private const ASSETS_PATH = '/wp-options-page/assets';

    /**
     * Title of the page.
     * 
     * @var string
     * @since 1.0.0
     */
    private $title;

    /**
     * Unique identifier needed to register the settings.
     * 
     * @var string
     * @since 1.0.0
     */
    private $key;

    /**
     * Fields to create.
     * 
     * @var array<string, array>
     * @since 1.0.0
     * @see Option_Page::add_field()
     */
    private $fields = array();

    /**
     * Sections to group fields.
     *
     * @var array<string, array>
     * @since 1.3.0
     * @see Option_Page::add_section()
     */
    private $sections = array();

    /**
     * @param string $title Title of the page.
     * @param string $key   Unique identifier needed to register the settings.
     * @since 1.0.0
     */
    public function __construct( $title, $key ) {
        $this->title = $title;
        $this->key   = $key;
        $this->add_hooks();
    }

    /**
     * Hooks the methods to the appropriate actions.
     * 
     * @since 1.0.0
     */
    private function add_hooks() {
        add_action( 'admin_menu', array( $this, 'add_page' ) );
        add_action( 'admin_init', array( $this, 'register_setting' ) );
        add_action( 'admin_enqueue_scripts', array( $this, 'enqueues_scripts' ) );
    }

    /**
     * Adds a new section.
     *
     * Sections allow you to group fields visually on the options page.
     *
     * @param string $id          Unique ID of the section.
     * @param string $title       Title of the section.
     * @param string $description Optional description displayed under the section title.
     * @since 1.3.0
     */
    public function add_section( $id, $title, $description = '' ) {
        $this->sections[ $id ] = array(
            'title'       => $title,
            'description' => $description,
        );
    }

    /**
     * Adds a new field.
     * 
     * @param string $type    Type of the field.
     * @param string $name    Name of the field.
     * @param array  $options Additional options for the field. Can include label and placeholder.
     *                        If the placeholder contains a reserved word (e.g., "image", "avatar" or "icon"),
     *                        a double-click will trigger the WordPress media library to open directly.
     *                        If the placeholder contains an indication of an image size "{size}px", the selected image will be the one closest to this size.
     * @since 1.0.0
     */
    public function add_field( $type, $name, $options = array() ) {
        $types = array( 'type' => $type );
        $this->fields[ $name ] = array_merge( $types, $options );
    }

    /**
     * Adds a page to the WordPress admin area.
     * 
     * @since 1.0.0
     * @link https://developer.wordpress.org/reference/functions/add_options_page/
     */
    public function add_page() {
        add_options_page( $this->title, $this->title, 'manage_options', $this->key, array( $this, 'render_form' ) );
    }

    /**
     * Renders the form for the options page.
     * 
     * @since 1.0.0
     */
    public function render_form() {
        ?>
        <div class="wrap">
            <h1><?php echo esc_html( $this->title ); ?></h1>
            <form method="post" action="options.php">
                <?php settings_fields( $this->key ); ?>
                <?php
                if ( ! empty( $this->sections ) ) :
                    foreach ( $this->sections as $section_id => $section ) :
                        $section_fields = array();
                        foreach ( $this->fields as $name => $field ) {
                            if ( isset( $field['section'] ) && $field['section'] === $section_id ) {
                                $section_fields[ $name ] = $field;
                            }
                        }
                        if ( empty( $section_fields ) ) {
                            continue;
                        }
                        ?>
                        <h2><?php echo esc_html( $section['title'] ); ?></h2>
                        <?php if ( ! empty( $section['description'] ) ) : ?>
                            <p class="description"><?php echo esc_html( $section['description'] ); ?></p>
                        <?php endif; ?>
                        <table class="form-table" role="presentation">
                            <tbody>
                            <?php foreach ( $section_fields as $name => $field ) : ?>
                                <tr>
                                    <th scope="row">
                                        <?php if ( ! empty( $field['label'] ) ) : ?>
                                            <label for="<?php echo esc_attr( $name ); ?>"><?php echo esc_html( $field['label'] ); ?></label>
                                        <?php endif; ?>
                                    </th>
                                    <td>
                                    <?php $this->render_field_by_type( $name, $field ); ?>
                                    </td>
                                </tr>
                            <?php endforeach; ?>
                            </tbody>
                        </table>
                        <?php
                    endforeach;

                    $unsectioned = array();
                    foreach ( $this->fields as $name => $field ) {
                        if ( empty( $field['section'] ) || ! isset( $this->sections[ $field['section'] ] ) ) {
                            $unsectioned[ $name ] = $field;
                        }
                    }
                    if ( ! empty( $unsectioned ) ) : ?>
                        <table class="form-table" role="presentation">
                            <tbody>
                            <?php foreach ( $unsectioned as $name => $field ) : ?>
                                <tr>
                                    <th scope="row">
                                        <?php if ( ! empty( $field['label'] ) ) : ?>
                                            <label for="<?php echo esc_attr( $name ); ?>"><?php echo esc_html( $field['label'] ); ?></label>
                                        <?php endif; ?>
                                    </th>
                                    <td>
                                    <?php $this->render_field_by_type( $name, $field ); ?>
                                    </td>
                                </tr>
                            <?php endforeach; ?>
                            </tbody>
                        </table>
                    <?php endif; ?>
                <?php else : ?>
                    <table class="form-table" role="presentation">
                        <tbody>
                        <?php foreach ( $this->fields as $name => $field ) : ?>
                            <tr>
                                <th scope="row">
                                    <?php if ( ! empty( $field['label'] ) ) : ?>
                                        <label for="<?php echo esc_attr( $name ); ?>"><?php echo esc_html( $field['label'] ); ?></label>
                                    <?php endif; ?>
                                </th>
                                <td>
                                <?php $this->render_field_by_type( $name, $field ); ?>
                                </td>
                            </tr>
                        <?php endforeach; ?>
                        </tbody>
                    </table>
                <?php endif; ?>
                <?php submit_button(); ?>
            </form>
        </div>
        <?php
    }

    /**
     * Renders a field by its declared type.
     *
     * @param string $name  Field name.
     * @param array  $field Field configuration.
     * @since 1.3.0
     */
    private function render_field_by_type( $name, $field ) {
        switch ( $field['type'] ) {
            case 'textarea':
                $this->render_textarea_field( $name, $field );
                break;
            case 'select':
                $this->render_select_field( $name, $field );
                break;
            case 'checkbox':
                $this->render_checkbox_field( $name );
                break;
            case 'color':
                $this->render_color_field( $name );
                break;
            default:
                $this->render_input_field( $name, $field );
                break;
        }
    }

    /**
     * Renders the textarea field.
     *
     * @param string $name  Name of the field.
     * @param array  $field Field to render a textarea for.
     * @since 1.2.0
     */
    private function render_textarea_field( $name, $field ) {
        ?>
        <textarea
            id="<?php echo esc_attr( $name ); ?>"
            class="regular-text"
            name="<?php echo esc_attr( $name ); ?>"
            placeholder="<?php echo esc_attr( $field['placeholder'] ?? '' ); ?>"
            rows="<?php echo esc_attr( $field['rows'] ?? '10' ); ?>"
        ><?php echo esc_textarea( get_option( $name ) ); ?></textarea>
        <?php
    }

    /**
     * Renders the select field.
     * 
     * @param string $name  Name of the field.
     * @param array  $field Field to render a select for.
     * @since 1.1.0
     */
    private function render_select_field( $name, $field ) {
        $current_value = get_option( $name );
        $label         = $field['label'] ?? '';
        $choices       = $field['choices'] ?? array();
        ?>
        <select
            id="<?php echo esc_attr( $name ); ?>"
            class="regular-text"
            name="<?php echo esc_attr( $name ); ?>"
        >
            <?php if ( $label ) : ?>
                <option value="" <?php echo $current_value ? '' : 'selected'; ?> disabled><?php echo esc_html( $label ); ?></option>
            <?php endif; ?>
            <?php foreach ( $choices as $choice ) : ?>
                <option value="<?php echo esc_attr( $choice ); ?>" <?php selected( $current_value, $choice ); ?>>
                    <?php echo esc_html( $choice ); ?>
                </option>
            <?php endforeach; ?>
        </select>
        <?php
    }

    /**
     * Renders the color field.
     *
     * @param string $name Name of the field.
     * @since 1.4.0
     */
    private function render_color_field( $name ) {
        ?>
        <input
            type="color"
            id="<?php echo esc_attr( $name ); ?>"
            name="<?php echo esc_attr( $name ); ?>"
            value="<?php echo esc_attr( get_option( $name, '#000000' ) ); ?>"
        >
        <?php
    }

    /**
     * Renders the checkbox field.
     * 
     * @param string $name Name of the field.
     * @since 1.0.1
     */
    private function render_checkbox_field( $name ) {
        ?>
        <input
            type="checkbox"
            id="<?php echo esc_attr( $name ); ?>"
            name="<?php echo esc_attr( $name ); ?>"
            value="1"
            <?php checked( 1, get_option( $name ), true ); ?>
        >
        <?php
    }

    /**
     * Renders the input field.
     * 
     * @param string $name  Name of the field.
     * @param array  $field Field to render an input for.
     * @since 1.0.1
     */
    private function render_input_field( $name, $field ) {
        ?>
        <input
            type="<?php echo esc_attr( $field['type'] ?? 'text' ); ?>"
            id="<?php echo esc_attr( $name ); ?>"
            class="regular-text"
            name="<?php echo esc_attr( $name ); ?>"
            value="<?php echo esc_attr( get_option( $name ) ); ?>"
            placeholder="<?php echo esc_attr( $field['placeholder'] ?? '' ); ?>"
        >
        <?php
    }

    /**
     * Sanitizes a field value based on its type.
     *
     * @param mixed $input Raw input value.
     * @param array $field Field configuration.
     * @return string Sanitized value or empty string on invalid input.
     * @since 1.3.2
     */
    private function sanitize_field_value( $input, $field ) {
        if ( is_array( $input ) ) {
            return '';
        }

        $type  = $field['type'] ?? 'text';
        $value = trim( (string) $input );

        switch ( $type ) {
            case 'checkbox':
                return ( '1' === $value ) ? '1' : '0';
            case 'email':
                return sanitize_email( $value );
            case 'url':
                return esc_url_raw( $value );
            case 'number':
                return is_numeric( $value ) ? $value : '';
            case 'color':
                return sanitize_hex_color( $value ) ?: '';
            case 'textarea':
                return sanitize_textarea_field( $value );
            case 'select':
                $choices = is_array( $field['choices'] ?? null ) ? array_values( $field['choices'] ) : array();
                return in_array( $value, $choices, true ) ? $value : '';
            default:
                return sanitize_text_field( $value );
        }
    }

    /**
     * Enqueues the necessary scripts.
     * 
     * @since 1.0.0
     */
    public function enqueues_scripts() {
        wp_enqueue_media();

        if ( ! wp_script_is( 'field-media', 'registered' ) ) {
            wp_enqueue_script( 'field-media', get_template_directory_uri() . self::ASSETS_PATH . '/js/field-media.js', array(), null, true );
        }
    }

    /**
     * Registers the settings.
     * 
     * @since 1.0.0
     * @link https://developer.wordpress.org/reference/functions/register_setting/
     */
    public function register_setting() {
        foreach ( $this->fields as $name => $field ) {
            register_setting( $this->key, $name, array(
                'sanitize_callback' => function ( $input ) use ( $name, $field ) {
                    if ( null === $input || '' === $input ) {
                        delete_option( $name );
                        return false;
                    }

                    $sanitized = $this->sanitize_field_value( $input, $field );
                    if ( '' === $sanitized ) {
                        delete_option( $name );
                        return false;
                    }

                    return $sanitized;
                }
            ) );
        }
    }
}