В качестве предисловия
WordPress — самая широко используемая система управления контентом в мире, на которой работает более 40% всех веб-сайтов. Разработчики ежедневно создают на её основе темы, плагины и целые приложения. Однако удивительно большое число этих разработчиков либо вообще не использует Settings API — собирая самодельные страницы опций с ручной обработкой форм и прямыми записями в базу данных, — либо использует его неправильно, копируя фрагменты кода без понимания того, что каждая функция делает на самом деле.
Эта серия руководств существует для решения этой проблемы. Мы не будем показывать, как на скорую руку собрать страницу настроек. Мы научим вас Settings API с базовых принципов, чтобы вы понимали «почему» за каждым вызовом функции, последствия для безопасности каждого проектного решения и архитектурные шаблоны, отличающие профессиональный код WordPress от любительского. К концу этой серии вы сможете создавать страницы настроек, которые безопасны, поддерживаемы и неотличимы от страниц админ-панели ядра WordPress.
Что представляет собой Settings API?
Settings API — это фреймворк, встроенный в ядро WordPress, стандартизирующий создание страниц административных настроек. Он обрабатывает отрисовку форм, валидацию и очистку опций, проверку nonce для безопасности и интеграцию с системой хранения опций WordPress. Это тот же API, на котором работают встроенные страницы «Настройки → Общие», «Написание», «Чтение», «Обсуждение», «Медиафайлы» и «Постоянные ссылки» в каждой установке WordPress.
В практическом смысле Settings API — это набор функций: register_setting(), add_settings_section(), add_settings_field(), settings_fields() и do_settings_sections(), — которые вместе формируют полный конвейер для создания страниц административной конфигурации. Вы определяете, какие опции существуют, как выглядят их поля формы, как они группируются в секции и как отправленные данные проверяются и очищаются. WordPress берёт на себя всё остальное.
Важно понимать, что Settings API — это не просто удобная обёртка над формами. Это архитектурный слой, обеспечивающий единообразие пользовательского опыта во всей экосистеме WordPress. Когда посетитель сайта заходит в админ-панель и видит страницу настроек плагина, она должна выглядеть и работать точно так же, как страницы настроек ядра. Это не вопрос эстетики — это вопрос предсказуемости интерфейса, снижающей когнитивную нагрузку на пользователя и количество ошибок при конфигурации. Именно поэтому Settings API жёстко привязан к CSS-фреймворку админ-панели и не позволяет произвольного оформления.
\u{201c}Settings API, добавленный в WordPress 2.7, позволяет полуавтоматически управлять страницами администратора, содержащими формы настроек. Он позволяет определять страницы настроек, секции и поля внутри них.
Зачем использовать Settings API вместо своего кода?
Технически вы можете создать страницу администратора без Settings API. Написать функцию, выводящую форму, подключить её к admin_menu, вручную проверить nonce при отправке, вручную очистить каждое поле и вручную вызвать update_option() для каждого значения. Многие разработчики делали именно так. Многие сайты WordPress работают именно на таком коде. И многие из этих сайтов имеют уязвимости безопасности, проблемы повреждения данных или кошмары поддержки, скрытые в этой самодельной реализации.
Вот что вы получаете бесплатно при использовании Settings API, что иначе вам пришлось бы реализовать самостоятельно:
| Функция | Усилия при самодельной реализации | Settings API |
|---|---|---|
| Проверка nonce | Ручное создание поля nonce, проверка и обработка ошибок | Автоматически через settings_fields() |
| Белый список опций | Требуется ручной эквивалент register_setting() для безопасности | Встроено в register_setting() |
| Конвейер очистки | Ручная очистка каждого поля, легко пропустить | Единый колбэк очистки обрабатывает все поля |
| Структура формы | Самодельные HTML-формы, несогласованные между страницами | Стандартизировано через API секций и полей |
| Уведомление при сохранении | Ручное сообщение «Настройки сохранены» | Автоматическое уведомление о сохранении |
| Обратная совместимость | Ваш код может сломаться при обновлениях WordPress | API ядра поддерживается с обратной совместимостью |
| Поддержка мультисайта | Своя логика для сетевых и локальных опций | Обрабатывается register_setting() с контекстом сети |
Settings API не просто экономит ваше время. Он защищает ваших пользователей от ошибок безопасности, которые вы допустили бы, если бы писали всё это с нуля. Безопасность через API — это реальная стратегия: каждый разработчик, использующий одни и те же хорошо протестированные функции, поддерживаемые ядром, по своей сути более защищён, чем каждый разработчик, пишущий свою собственную проверку nonce.
Взаимодействие Settings API с ядром WordPress
Settings API — это не автономная система. Он построен поверх нескольких других API WordPress и глубоко взаимодействует с инфраструктурой админ-панели WordPress. Понимание этих взаимодействий помогает отлаживать проблемы и принимать обоснованные проектные решения.
Settings API зависит от Options API для хранения данных. Когда вы вызываете register_setting(), WordPress создаёт запись в глобальном белом списке, контролирующем, какие опции могут обновляться через админ-панель. При отправке формы WordPress передаёт отправленные данные через ваш колбэк очистки, затем вызывает update_option() для сохранения очищенных значений. Связь между Settings API и Options API — причина того, почему имя вашей опции должно быть согласованным между register_setting(), атрибутами name полей формы и вызовами get_option() в коде вашей темы или плагина.
Settings API использует Plugin API (хуки) для времени выполнения. Регистрация настроек происходит на хуке admin_init. Регистрация меню — на admin_menu. Отрисовка формы происходит во время загрузки страницы при вызове do_settings_sections(). Ваш колбэк очистки вызывается как фильтр на хуке sanitize_option_{имя_опции}. Понимание этой архитектуры на основе хуков необходимо при отладке проблем — почему настройка не сохраняется или поле не отображается.
Settings API интегрируется с инфраструктурой экранов администратора для обеспечения визуальной согласованности. Когда вы оборачиваете страницу настроек в стандартный контейнер <div class="wrap">, CSS ядра WordPress стилизует элементы вашей формы в соответствии с остальной частью админ-панели. Функция submit_button() выводит кнопку сохранения, стилизованную идентично любой другой кнопке админ-панели WordPress.
Исторический контекст: до и после Settings API
WordPress 2.7, выпущенный в декабре 2008 года, представил Settings API вместе с капитальным редизайном интерфейса администратора. До версии 2.7 разработчикам плагинов и тем приходилось создавать страницы настроек с нуля, используя самодельные запросы к базе данных и написанные вручную HTML-формы. Не существовало стандартизированного способа создания страниц административной конфигурации, что приводило к совершенно разному пользовательскому опыту между плагинами и распространению уязвимостей безопасности в коде обработки форм.
Settings API был спроектирован для решения трёх конкретных проблем. Во-первых, он стандартизировал внешний вид страниц административных настроек, чтобы конфигурация каждого плагина выглядела как часть WordPress. Во-вторых, он централизовал вопросы безопасности — генерацию nonce, ведение белого списка опций, очистку — в единый API, чтобы отдельным разработчикам не приходилось реализовывать их заново. В-третьих, он обеспечил фундамент, ориентированный на будущее: по мере развития WordPress улучшения Settings API автоматически приносили пользу каждому плагину и теме, использующим его правильно.
| Версия WordPress | Год выпуска | Веха Settings API |
|---|---|---|
| 2.7 | 2008 | Начальный Settings API с register_setting(), add_settings_section(), add_settings_field() |
| 2.8 | 2009 | Улучшения обработки колбэков очистки и сообщений об ошибках |
| 3.0 | 2010 | Поддержка мультисайта: register_setting() получает поведение с учётом сети |
| 3.4 | 2012 | Представлен Theme Customization API, построенный на фундаменте Settings API |
| 4.7 | 2016 | Конечная точка REST API settings предоставляет зарегистрированные настройки через JSON |
| 5.0+ | 2018+ | Эра Gutenberg/Block Editor: Settings API остаётся стандартом для конфигурации плагинов |
Settings API стабилен уже более 15 лет. Основные функции сохранили обратную совместимость во всех крупных выпусках WordPress. Код, написанный для WordPress 2.7 с использованием Settings API, будет работать на WordPress 6.x без изменений. Эта стабильность — осознанное решение команды ядра WordPress: страницы настроек — это инфраструктура, а инфраструктура не должна ломаться.
Преимущества безопасности Settings API
Безопасность — это не функция, которую вы добавляете на страницу настроек после её создания. Это свойство, которое должно быть заложено в архитектуру с самого начала. Settings API предоставляет несколько механизмов безопасности, которые сложно или утомительно реализовать правильно в самодельном коде:
Белый список опций
При вызове register_setting() WordPress добавляет имя вашей опции в глобальный белый список. При отправке формы в options.php WordPress проверяет этот список. Если имя отправленной опции отсутствует в белом списке, запрос отклоняется с ошибкой «у вас недостаточно прав». Это предотвращает атаки, при которых злоумышленник создаёт POST-запросы, изменяющие произвольные опции WordPress — можно изменить только опции, явно зарегистрированные плагином или темой.
Проверка nonce
Функция settings_fields() автоматически генерирует WordPress nonce — криптографический токен, доказывающий, что отправка формы произошла с вашей административной страницы, а не в результате атаки межсайтовой подделки запроса (CSRF). Без этого злоумышленник мог бы заставить залогиненного администратора посетить вредоносную страницу, которая отправляет форму вашему обработчику настроек. Settings API отклоняет любую отправку формы с недействительным или просроченным nonce.
Конвейер очистки
Колбэк очистки, который вы предоставляете в register_setting(), вызывается автоматически для каждой отправки формы. Вы не можете забыть очистить поле, потому что один и тот же колбэк обрабатывает все поля. Это эшелонированная защита: даже если в коде отрисовки формы есть ошибка, колбэк очистки обеспечивает второй слой защиты, очищающий данные до их попадания в базу данных.
Контроль доступа на основе прав
Параметр capability в add_menu_page() и проверка прав в register_setting() работают вместе, создавая эшелонированную защиту. Даже если вы случайно зарегистрируете настройки без проверки прав, пользователь должен перейти на административную страницу (что требует права) для доступа к форме. А если он каким-то образом получит доступ к форме, проверка nonce и верификация белого списка добавляют дополнительные барьеры.
Обзор серии руководств
Эта серия ведёт вас от нуля до готового к работе владения Settings API. Каждый урок строится на предыдущем, вводя новые концепции только после закрепления фундамента. Вот что вы изучите в рамках всей серии:
- Введение и основные концепции — Что такое Settings API, зачем он существует, как взаимодействует с ядром WordPress (этот урок)
- Создание административных меню — add_menu_page() и add_submenu_page() для построения навигации админ-панели
- Валидация и очистка — Разница между валидацией и очисткой, функции очистки WordPress, создание безопасных колбэков очистки
- Базовые элементы ввода — Текстовые поля, textarea, радиокнопки, чекбоксы и выпадающие списки с полными колбэками отрисовки
- Расширенные элементы ввода — Группы чекбоксов, сгруппированные радиокнопки, выпадающие списки с optgroup и вспомогательные функции checked() / selected()
- Собираем всё вместе — Полная, готовая к использованию страница опций темы, объединяющая все элементы, изученные в серии
Каждый урок включает полные, готовые к копированию примеры кода, объяснения того, почему используется каждая функция, и типичные ошибки, которых следует избегать. Мы не просто показываем код — мы объясняем обоснование каждого решения, чтобы вы могли применять те же принципы в своих проектах, а не просто копировать непонятные строки.
Необходимые знания для этого руководства
Чтобы получить максимум от этой серии, вы должны иметь рабочие знания PHP и базовое знакомство с разработкой на WordPress. В частности, вы должны уверенно владеть:
- Написанием функций PHP и пониманием области видимости переменных
- Работой с темами или плагинами WordPress (понимать, где размещать код)
- Пониманием разницы между functions.php, файлами плагинов и иерархией шаблонов WordPress
- Базовыми элементами HTML-форм: <input>, <select>, <textarea>, <button>, <form>
- Концепцией хуков WordPress (add_action, add_filter) на начальном уровне
Вам НЕ нужен предварительный опыт работы с Settings API — именно этому учит данная серия. Вам НЕ нужна степень по компьютерным наукам или глубокие знания PHP. Если вы создавали хотя бы простую тему или плагин WordPress ранее, у вас достаточно подготовки для освоения материала.
Настройка среды разработки
Все примеры кода в этой серии рассчитаны на работу в локальной среде разработки WordPress. Мы рекомендуем использовать инструмент локальной разработки, такой как Local by Flywheel, DevKinsta или ручную настройку XAMPP/MAMP. Добавляйте код в файл functions.php вашей активной темы или создайте простой плагин для размещения кода. На протяжении примеров функции имеют префикс mytheme_ — замените его на префикс вашей темы или плагина.
Ключевые концепции, которыми вы овладеете
К моменту завершения этой серии вы будете понимать и сможете реализовать:
- Регистрация опций: Как register_setting() создаёт безопасный конвейер данных от формы до базы данных
- Архитектура формы: Как секции и поля организуют страницу настроек в логические группы
- Стратегия очистки: Как выбрать правильную функцию очистки WordPress для каждого типа данных и построить всеобъемлющий колбэк очистки
- Интеграция меню: Как разместить страницу настроек в правильной позиции навигации админ-панели с соответствующими требованиями прав пользователя
- Сохранение состояния: Как checked(), selected() и вспомогательные функции WordPress поддерживают состояние формы при перезагрузке страницы
- Архитектура безопасности: Как nonce, белые списки и проверки прав работают вместе для защиты страниц настроек от распространённых векторов атак
Что дальше
В следующем уроке мы начинаем писать реальный код. Мы начнём с создания административного меню — навигационной инфраструктуры, которая делает вашу страницу настроек доступной. Вы изучите add_menu_page() и add_submenu_page() углублённо, включая часто неправильно понимаемый параметр capability и стратегии позиционирования меню. Затем мы перейдём к обработке данных: валидации, очистке и полному конвейеру от ввода в форму до хранения в базе данных. Каждый следующий урок опирается на материал этого введения, поэтому убедитесь, что вы хорошо усвоили фундаментальные концепции перед переходом к практическим примерам.
Каждый урок серии рассчитан примерно на 30-45 минут практического кодирования. Не торопитесь с каждой концепцией. Стройте примеры, изменяйте их, ломайте намеренно и чините снова. Цель не в запоминании сигнатур функций, а в построении ментальной модели работы Settings API, чтобы вы могли свободно использовать его в своих проектах.
Практические навыки формируются только через многократное повторение и осознанную работу с кодом, поэтому не пропускайте практические задания и не копируйте код без понимания логики его работы.
Далее: Создание административных меню и подменюЧасто задаваемые вопросы
Что именно такое WordPress Settings API?
Settings API — это стандартизированный фреймворк для создания страниц административной конфигурации в WordPress. Он предоставляет функции register_setting(), add_settings_section() и add_settings_field(), обрабатывающие отрисовку форм, проверку безопасности и очистку данных. Это та же система, которая используется встроенными страницами настроек WordPress (Общие, Написание, Чтение, Обсуждение, Медиафайлы, Постоянные ссылки), и она является частью ядра WordPress с версии 2.7, выпущенной в 2008 году.
Зачем использовать Settings API вместо создания своей формы настроек?
Settings API предоставляет встроенные механизмы безопасности — проверку nonce, белый список опций и конвейер очистки — которые вам пришлось бы реализовывать с нуля в самодельном коде. Он стандартизирует внешний вид административных страниц, обеспечивает совместимость с обновлениями WordPress и экономит значительное время разработки. Самодельные формы настроек часто содержат уязвимости безопасности в обработке nonce или логике очистки.
Актуален ли Settings API в эру Gutenberg/Block Editor?
Да. Settings API — стандарт для страниц конфигурации плагинов и тем, которые отделены от опыта редактирования контента. Gutenberg изменил способ создания и редактирования контента, но не изменил способ хранения и управления настройками плагинов. Settings API остаётся правильным инструментом для создания страниц конфигурации в админ-панели WordPress.
Какие хуки задействованы в Settings API?
Три основных хука: admin_init для регистрации настроек, секций и полей; admin_menu для создания пунктов меню, ведущих на страницу настроек; и фильтр sanitize_option_{имя_опции}, где выполняется ваш колбэк очистки при отправке формы. Понимание этих хуков и порядка их выполнения необходимо для отладки проблем, связанных с настройками.
В какой версии WordPress появился Settings API?
WordPress 2.7, декабрь 2008 года. Settings API стал частью капитального редизайна интерфейса администратора, стандартизировавшего создание страниц настроек. До 2.7 разработчики плагинов создавали формы настроек с нуля, что приводило к несогласованным интерфейсам и частым проблемам безопасности в коде обработки форм.
Как Settings API взаимодействует с базой данных WordPress?
Settings API не взаимодействует с базой данных напрямую. Он использует Options API (get_option(), update_option()) для хранения данных. При отправке формы WordPress передаёт данные через ваш колбэк очистки, затем вызывает update_option() для сохранения очищенных значений в таблице wp_options. Settings API обрабатывает слои формы и безопасности; Options API — слой хранения.
Какие навыки нужны перед началом этой серии уроков?
Средний уровень PHP — функции, массивы, область видимости переменных. Базовый опыт разработки на WordPress — понимание, где размещать код (functions.php против плагинов). Начальный уровень понимания хуков WordPress (add_action, add_filter). Знакомство с HTML-формами. Предварительный опыт работы с Settings API не требуется.
Можно ли использовать Settings API в сети WordPress Multisite?
Да. Settings API поддерживает сетевые настройки через параметр $network_only функции register_setting(), хук network_admin_menu для регистрации меню сетевого уровня и get_site_option() / update_site_option() для хранения на уровне сети. Те же функции API работают как для одиночных сайтов, так и для сетей мультисайта с соответствующими параметрами.
