Расширенные примеры использования

Пример с валидацией, несколькими секциями и типами полей

Ниже представлен полный код страницы настроек с тремя секциями: текст, медиа, выбор. Используются поля: текст, textarea, медиа (через Media Uploader), select, чекбоксы.

// functions.php

add_action('admin_menu', function() {
    add_options_page('Продвинутые настройки', 'Продвинутые', 'manage_options', 'advanced-settings', 'advanced_settings_page');
});

add_action('admin_init', function() {
    register_setting('advanced-settings-group', 'advanced_options', 'advanced_sanitize');

    // Секция 1 - Основные
    add_settings_section('advanced_main', 'Основные параметры', '', 'advanced-settings');
    add_settings_field('header_text', 'Текст в шапке', 'field_text', 'advanced-settings', 'advanced_main', ['id' => 'header_text']);
    add_settings_field('footer_text', 'Текст в подвале', 'field_textarea', 'advanced-settings', 'advanced_main', ['id' => 'footer_text']);

    // Секция 2 - Медиа
    add_settings_section('advanced_media', 'Медиафайлы', '', 'advanced-settings');
    add_settings_field('logo_url', 'Логотип (URL)', 'field_media', 'advanced-settings', 'advanced_media', ['id' => 'logo_url']);

    // Секция 3 - Дополнительно
    add_settings_section('advanced_extra', 'Дополнительные опции', '', 'advanced-settings');
    add_settings_field('color_scheme', 'Цветовая схема', 'field_select', 'advanced-settings', 'advanced_extra', ['id' => 'color_scheme']);
    add_settings_field('enable_analytics', 'Включить аналитику', 'field_checkbox', 'advanced-settings', 'advanced_extra', ['id' => 'enable_analytics']);
});

function advanced_settings_page() {
    ?>
    

        
Продвинутые настройки
        

            <?
            settings_fields('advanced-settings-group');
            do_settings_sections('advanced-settings');
            submit_button();
            ?>
        
    
    <?
}

// Поле текст
function field_text($args) {
    $options = get_option('advanced_options');
    $value = isset($options[$args['id']]) ? $options[$args['id']] : '';
    echo '<input type="text" id="' . esc_attr($args['id']) . '" name="advanced_options[' . esc_attr($args['id']) . ']" value="' . esc_attr($value) . '" class="regular-text" />';
}

// Поле textarea
function field_textarea($args) {
    $options = get_option('advanced_options');
    $value = isset($options[$args['id']]) ? $options[$args['id']] : '';
    echo '<textarea id="' . esc_attr($args['id']) . '" name="advanced_options[' . esc_attr($args['id']) . ']" rows="5" cols="50" class="large-text">' . esc_textarea($value) . '</textarea>';
}

// Поле медиа (с кнопкой выбора)
function field_media($args) {
    $options = get_option('advanced_options');
    $value = isset($options[$args['id']]) ? $options[$args['id']] : '';
    ?>
    

        <input type="text" id="<?php echo esc_attr($args['id']); ?>" name="advanced_options[<?php echo esc_attr($args['id']); ?>]" value="<?php echo esc_url($value); ?>" class="regular-text" />
        <button type="button" class="button upload-media-button" data-target="<?php echo esc_attr($args['id']); ?>">Выбрать изображение
    
    <script>
    jQuery(document).ready(function($) {
        $('.upload-media-button').click(function(e) {
            e.preventDefault();
            var target = $(this).data('target');
            var frame = wp.media({
                title: 'Выберите изображение',
                button: { text: 'Использовать' },
                multiple: false
            });
            frame.on('select', function() {
                var attachment = frame.state().get('selection').first().toJSON();
                $('#' + target).val(attachment.url);
            });
            frame.open();
        });
    });
    </script>
    <?
}

// Поле select
function field_select($args) {
    $options = get_option('advanced_options');
    $selected = isset($options[$args['id']]) ? $options[$args['id']] : 'light';
    $choices = array('light' => 'Светлая', 'dark' => 'Тёмная', 'custom' => 'Пользовательская');
    echo '<select id="' . esc_attr($args['id']) . '" name="advanced_options[' . esc_attr($args['id']) . ']">';
    foreach ($choices as $val => $label) {
        echo '<option value="' . esc_attr($val) . '" ' . selected($selected, $val, false) . '>' . esc_html($label) . '</option>';
    }
    echo '</select>';
}

// Поле чекбокс
function field_checkbox($args) {
    $options = get_option('advanced_options');
    $checked = isset($options[$args['id']]) && $options[$args['id']] == 1 ? 'checked' : '';
    echo '<input type="checkbox" id="' . esc_attr($args['id']) . '" name="advanced_options[' . esc_attr($args['id']) . ']" value="1" ' . $checked . ' />';
}

// Санитизация
function advanced_sanitize($input) {
    $output = array();
    $output['header_text'] = isset($input['header_text']) ? sanitize_text_field($input['header_text']) : '';
    $output['footer_text'] = isset($input['footer_text']) ? sanitize_textarea_field($input['footer_text']) : '';
    $output['logo_url'] = isset($input['logo_url']) ? esc_url_raw($input['logo_url']) : '';
    $output['color_scheme'] = isset($input['color_scheme']) && in_array($input['color_scheme'], ['light','dark','custom']) ? $input['color_scheme'] : 'light';
    $output['enable_analytics'] = isset($input['enable_analytics']) ? 1 : 0;
    return $output;
}

Результат: После сохранения в таблице wp_options появится запись с ключом advanced_options и массивом значений.

// Пример сохранённых данных (сериализованный массив)
a:5:{s:11:"header_text";s:13:"Добро пожаловать";s:11:"footer_text";s:9:"2025 год";s:8:"logo_url";s:59:"http://example.com/wp-content/uploads/2025/01/logo.png";s:12:"color_scheme";s:5:"light";s:16:"enable_analytics";i:1;}

Добавление сообщений об ошибках через add_settings_error

Можно отображать кастомные сообщения после сохранения, используя add_settings_error() и settings_errors().

function advanced_sanitize($input) {
    // ... валидация
    if ( empty($input['header_text']) ) {
        add_settings_error('advanced_options', 'header_empty', 'Поле заголовка не должно быть пустым.', 'error');
    }
    // ...
    return $output;
}

function advanced_settings_page() {
    ?>
    

        
Продвинутые настройки
        <? settings_errors('advanced_options'); // вывод ошибок ?>
        

            ...
        
    
    <?
}

Использование кастомной таблицы для хранения настроек

Вместо wp_options можно хранить настройки в отдельной таблице БД. Пример:

// Создание таблицы при активации темы/плагина
function create_custom_settings_table() {
    global $wpdb;
    $table_name = $wpdb->prefix . 'my_settings';
    $charset_collate = $wpdb->get_charset_collate();
    $sql = "CREATE TABLE IF NOT EXISTS $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        setting_name varchar(255) NOT NULL,
        setting_value text NOT NULL,
        PRIMARY KEY (id)
    ) $charset_collate;";
    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    dbDelta($sql);
}
register_activation_hook(__FILE__, 'create_custom_settings_table');

// Функции для сохранения/получения
function my_custom_setting_get($name) {
    global $wpdb;
    $table = $wpdb->prefix . 'my_settings';
    $row = $wpdb->get_row($wpdb->prepare("SELECT setting_value FROM $table WHERE setting_name = %s", $name));
    return $row ? $row->setting_value : false;
}

function my_custom_setting_update($name, $value) {
    global $wpdb;
    $table = $wpdb->prefix . 'my_settings';
    $exists = $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM $table WHERE setting_name = %s", $name));
    if ($exists) {
        $wpdb->update($table, array('setting_value' => $value), array('setting_name' => $name));
    } else {
        $wpdb->insert($table, array('setting_name' => $name, 'setting_value' => $value));
    }
}

// Использование в обработчике
function my_save_handler() {
    if ( isset($_POST['custom_field']) ) {
        my_custom_setting_update('custom_field', sanitize_text_field($_POST['custom_field']));
    }
}

Преимущества: Производительность при большом количестве настроек, возможность индексирования, изоляция от других опций. Недостатки: Нужно создавать таблицу, нет встроенного кэширования WordPress, больше кода.