Термин WordPress API часто понимается неправильно, потому что означает разные вещи в разных контекстах. По своей сути API означает Application Programming Interface — интерфейс программирования приложений, то есть набор функций, классов и методов, которые WordPress предоставляет разработчикам для расширения и настройки платформы. WordPress не имеет единого монолитного API. Вместо этого он предоставляет коллекцию специализированных API, каждый из которых служит отдельной цели внутри экосистемы. Это руководство описывает каждый основной API WordPress, объясняет, что делает каждый из них, и проясняет, когда следует использовать каждый.
Что именно представляет собой WordPress API?
В контексте WordPress API — это формализованный набор функций, позволяющих взаимодействовать с определённой подсистемой WordPress стандартизированным способом. Вместо написания прямых SQL-запросов или манипуляции внутренними механизмами WordPress напрямую вы используете API-функции. Эти функции поддерживаются командой ядра WordPress, документированы в Кодексе и Справочнике разработчика и тестируются на обратную совместимость между версиями.
Преимущество использования API над прямыми манипуляциями троякое. Во-первых, API предоставляют стабильный контракт: ваш код работает сегодня и продолжит работать после обновлений WordPress, потому что команда ядра поддерживает обратную совместимость. Во-вторых, API обрабатывают краевые случаи и проблемы безопасности, которые вы можете пропустить при написании собственного кода. В-третьих, API производят код, который другие разработчики WordPress понимают сразу, потому что используют знакомые, хорошо документированные шаблоны.
Экосистема API WordPress
API WordPress делятся на две широкие категории: служебные API ядра, обрабатывающие фундаментальные операции, такие как доступ к базе данных и HTTP-запросы, и API расширений, обеспечивающие конкретные типы настройки — темы, плагины и виджеты. Понимание этого разделения помогает ориентироваться в документации и выбирать правильный инструмент для каждой задачи.
| Категория | API в этой категории | Основное назначение |
|---|---|---|
| Служебные ядра | Database API, HTTP API, Filesystem API, File Header API, Metadata API, Options API, Rewrite API | Инфраструктура и операции с данными, лежащие в основе всей функциональности WordPress |
| API расширений | Plugin API, Settings API, Shortcode API, Theme Customization API, Widget API | Создание пользовательских функций, тем, плагинов и настроек на уровне страниц |
1. API консоли (wp-cli)
API консоли, доступный в первую очередь через WP-CLI, предоставляет интерфейс командной строки для управления установками WordPress. Он позволяет разработчикам и системным администраторам выполнять административные задачи без входа в панель управления WordPress. Вы можете устанавливать плагины, обновлять ядро, импортировать данные, управлять пользователями и выполнять операции с базой данных — всё из терминала.
Распространённые сценарии использования включают массовый импорт контента, планирование задач обслуживания, синхронизацию баз данных разработки и продакшена, а также запуск тестовых наборов. WP-CLI особенно ценен для агентств, управляющих несколькими клиентскими сайтами, поскольку позволяет выполнять скриптовые, повторяемые операции, которые заняли бы часы через веб-интерфейс.
2. API базы данных (класс wpdb)
API базы данных, реализованный через класс wpdb, предоставляет безопасный слой абстракции над MySQL. Он управляет подключениями к базе данных, подготовкой запросов и извлечением результатов, автоматически защищая от SQL-инъекций при правильном использовании. Класс wpdb инстанцирован как глобальный объект $wpdb и доступен в любом контексте WordPress.
Самая важная функция безопасности wpdb — поддержка подготовленных выражений через метод prepare(). Всегда используйте $wpdb->prepare() при построении запросов с пользовательскими данными. Метод экранирует значения и заменяет заполнители правильно экранированными строками, предотвращая самую распространённую уязвимость в пользовательском коде баз данных WordPress.
3. HTTP API
HTTP API предоставляет унифицированный интерфейс для выполнения HTTP-запросов из WordPress. Он абстрагирует лежащий в основе транспортный механизм — cURL, file_get_contents с контекстами потоков или сокеты PHP — и предоставляет согласованный набор функций. Основные функции: wp_remote_get(), wp_remote_post() и wp_remote_request().
Этот API необходим для интеграции с внешними сервисами: REST API, платёжными шлюзами, платформами социальных сетей, службами доставки почты и аналитическими провайдерами. Он автоматически обрабатывает проверку SSL, перенаправления, тайм-ауты и управление cookie. После выполнения запроса используйте вспомогательные функции — wp_remote_retrieve_body() и wp_remote_retrieve_response_code() — для безопасного извлечения данных ответа.
4. File Header API (API заголовков файлов)
API заголовков файлов читает метаданные из заголовочных комментариев плагинов и тем. Каждый файл плагина начинается со стандартизированного блока комментариев, содержащего название плагина, описание, версию, автора и другие метаданные. Файл style.css темы содержит аналогичную информацию. Функции get_plugin_data() и wp_get_theme() используют этот API для извлечения метаданных для отображения в панели администратора.
Этот API в основном используется WordPress внутренне для заполнения экранов администрирования «Плагины» и «Темы». Разработчики плагинов редко взаимодействуют с ним напрямую, но его понимание помогает при отладке случаев, когда плагин не появляется в списке администратора — отсутствующий заголовок Plugin Name является самой частой причиной.
5. Filesystem API (API файловой системы)
API файловой системы предоставляет безопасный слой абстракции для файловых операций. Он был введён для обработки распространённой ситуации, когда веб-сервер не имеет прямого доступа на запись к файловой системе. API отображает форму учётных данных, когда требуются повышенные привилегии, и поддерживает несколько транспортных методов: прямой доступ к файловой системе, FTP, FTPS (FTP через SSL) и SSH2.
Функции вроде $wp_filesystem->put_contents() и $wp_filesystem->get_contents() должны использоваться вместо нативных функций PHP для работы с файлами, когда вашему коду требуется запись файлов на сервер. Это обеспечивает совместимость в средах хостинга, где владелец файлов отличается от пользователя процесса PHP. Обновлятор WordPress, установщик плагинов и установщик тем — все используют API файловой системы.
6. Metadata API (API метаданных)
API метаданных предоставляет функции для хранения, извлечения, обновления и удаления метаданных, связанных с объектами WordPress: записями, пользователями, комментариями и терминами. Основные функции — add_metadata(), get_metadata(), update_metadata() и delete_metadata() — работают единообразно для всех типов объектов, с удобными обёртками вроде get_post_meta() и get_user_meta() для конкретных контекстов.
API метаданных — один из самых мощных и гибких API в WordPress. Он позволяет прикреплять произвольные пары ключ-значение к любому объекту WordPress без изменения схемы. Произвольные поля записей, расширения профилей пользователей и атрибуты товаров в WooCommerce — все используют API метаданных. Данные хранятся в выделенных мета-таблицах с эффективным индексированием, что делает запросы метаданных производительными даже при больших объёмах данных.
7. Options API (API опций)
API опций сохраняет и извлекает пары ключ-значение из таблицы wp_options. Это основной механизм сохранения настроек плагинов и тем. Основные функции включают get_option(), update_option(), add_option() и delete_option(). Опции автоматически загружаются при каждом запросе при регистрации с флагом autoload, делая часто используемые настройки доступными без дополнительных запросов.
API опций легковесен и повсеместен. Каждое значение конфигурации сайта WordPress — URL сайта, название блога, формат даты, активные плагины, активная тема — хранится через API опций. Для настроек плагинов и тем Settings API (описанный ниже) строится поверх API опций, предоставляя отрисовку форм, проверку nonce и колбэки очистки.
8. Plugin API (система хуков)
Plugin API — это основа расширяемости WordPress. Он предоставляет систему хуков — действий и фильтров — позволяющую плагинам и темам изменять поведение WordPress без редактирования файлов ядра. Действия (Actions) позволяют выполнять код в определённых точках выполнения WordPress. Фильтры (Filters) позволяют изменять данные при их прохождении через WordPress.
Plugin API — это то, что делает WordPress больше, чем просто движок блога. Каждый плагин, каждая тема и даже само ядро WordPress используют действия и фильтры для взаимодействия между компонентами. Понимание порядка выполнения хуков — init, wp_loaded, template_redirect, wp_head, the_content, wp_footer — необходимо для написания кода, выполняющегося в нужное время с доступными нужными данными.
9. Shortcode API (API шорткодов)
API шорткодов позволяет создавать пользовательские макросы, которые редакторы контента могут вставлять в записи и страницы, используя скобочную нотацию, например [мой_шорткод]. Шорткоды обрабатываются во время отрисовки: WordPress сканирует содержимое записи на наличие зарегистрированных шаблонов шорткодов и заменяет их динамически сгенерированным содержимым.
Шорткоды идеальны для встраивания динамического контента — галерей, форм, связанных записей, списков товаров, таблиц цен — внутрь статического содержимого записи. API поддерживает атрибуты, самозакрывающиеся теги и охватывающее содержимое. Зарегистрируйте шорткод через add_shortcode() и определите колбэк, возвращающий заменяющий HTML.
10. Rewrite API (API перезаписи URL)
Rewrite API управляет тем, как WordPress интерпретирует URL и сопоставляет их с переменными запроса. Он отвечает за преобразование читаемых постоянных ссылок вроде /blog/2026/моя-запись во внутренние параметры запроса, которые WordPress использует для определения отображаемого контента. Функция add_rewrite_rule() регистрирует пользовательские шаблоны URL, а класс WP_Rewrite управляет глобальным набором правил перезаписи.
Этот API критически важен при регистрации произвольных типов записей и таксономий. Без правильных правил перезаписи пользовательские типы контента возвращают ошибки 404. Rewrite API также включает расширенные функции — создание конечных точек (добавление /json/ или /amp/ к любому URL) и пользовательские структуры постоянных ссылок, выходящие за рамки стандартных опций WordPress.
11. Settings API (API настроек)
Settings API предоставляет фреймворк для создания стандартизированных страниц настроек в админ-панели WordPress. Он обрабатывает отрисовку форм, проверку nonce для безопасности, очистку опций через зарегистрированные колбэки — страницы «Настройки → Общие», «Написание», «Чтение», «Обсуждение», «Медиафайлы» и «Постоянные ссылки» используют этот API. Для разработчиков тем и плагинов Settings API является правильным способом создания страниц конфигурации.
Основные функции включают register_setting(), add_settings_section(), add_settings_field(), settings_fields() и do_settings_sections(). Вместе они формируют полный конвейер: регистрация опции с её колбэком очистки, определение секций и полей формы, и отрисовка полной формы со встроенными защитами безопасности. Этот API является основным предметом нашей серии руководств.
12. Theme Customization API (Кастомайзер)
Theme Customization API, обычно называемый Кастомайзером, предоставляет интерфейс живого предпросмотра для настроек темы. Пользователи изменяют опции — заголовок сайта, цвета, макеты и размещение виджетов — в боковой панели, видя применение изменений в реальном времени в панели предпросмотра. API использует секции, настройки и элементы управления для организации интерфейса настройки.
Кастомайзер отличается от Settings API тем, что приоритетом является визуальная обратная связь. Палитра цветов в Кастомайзере немедленно показывает изменение цвета на просматриваемой странице. Страница настроек требует сохранения и последующего перехода на фронтенд для просмотра результата. Для опций темы, влияющих на внешний вид, Кастомайзер — лучший выбор. Для конфигурации плагина без визуального компонента Settings API более уместен.
13. Widget API (API виджетов)
Widget API позволяет разработчикам создавать переиспользуемые блоки контента, которые администраторы сайта могут перетаскивать в области виджетов — обычно боковые панели, подвалы и другие обозначенные темой регионы. Каждый виджет расширяет базовый класс WP_Widget и реализует методы для отрисовки виджета, отображения формы конфигурации в админ-панели и обновления сохранённых настроек.
Виджеты остаются фундаментальной частью WordPress, несмотря на рост блочного редактирования. Они отображаются на экране «Внешний вид → Виджеты» и, в блочных темах, как устаревшие виджеты внутри редактора блоков. Создание виджета включает расширение WP_Widget, реализацию widget() для вывода на фронтенде, form() для формы конфигурации в админ-панели и update() для сохранения настроек.
Руководство по выбору API: какой API когда использовать
| Вы хотите | Используйте этот API | Почему |
|---|---|---|
| Сохранить конфигурацию плагина | Options API / Settings API | Постоянное хранение ключ-значение с поддержкой автозагрузки, плюс безопасные админ-формы |
| Добавить пользовательские данные к записям | Metadata API | Эффективное хранение в мета-таблицах с автоматическим кэшированием и поддержкой запросов |
| Вызвать внешний REST-сервис | HTTP API | Транспортно-независимые запросы со встроенной обработкой SSL, редиректов и ошибок |
| Выполнить пользовательский запрос к БД | Database API (wpdb) | Безопасные подготовленные выражения, предотвращающие SQL-инъекции |
| Создать страницу опций темы | Settings API | Стандартизированные админ-страницы с проверкой nonce и колбэками очистки |
| Дать пользователям настраивать внешний вид | Theme Customization API | Интерфейс живого предпросмотра с немедленной визуальной обратной связью |
| Вставить динамический контент в записи | Shortcode API | Удобный для редактора синтаксис скобок с обработкой во время отрисовки |
| Написать переиспользуемый блок контента | Widget API | Блоки drag-and-drop для боковых панелей и областей виджетов |
| Настроить структуру URL | Rewrite API | Чистые постоянные ссылки с пользовательскими правилами перезаписи и конечными точками |
| Изменить поведение WordPress | Plugin API (хуки) | Действия и фильтры для внедрения кода в конкретные точки выполнения |
Как API связаны друг с другом
API WordPress не существуют изолированно. Они образуют слои, построенные друг на друге. Database API — это фундамент: каждый другой API, хранящий постоянные данные — Options, Metadata, Settings — использует wpdb. Plugin API пронизывает всё: хуки срабатывают во время операций API, позволяя другому коду перехватывать и изменять поведение. Settings API строится на Options API, добавляя отрисовку форм и проверку nonce. Theme Customization API строится на Settings API и Options API для своего хранилища конфигурации и конвейера отрисовки.
Понимание этих зависимостей помогает отлаживать проблемы. Если страница настроек не сохраняется, проблема может быть в Settings API (отсутствует колбэк очистки), Options API (несовпадение имени опции) или Database API (права на запись). Следование по цепочке вызовов от API верхнего уровня вниз через его зависимости — самая эффективная стратегия отладки.
Часто задаваемые вопросы
Что именно означает API в контексте WordPress?
В WordPress API означает набор функций, классов и методов, предоставляемых ядром для разработчиков. В отличие от внешних REST API, API WordPress — это внутренние PHP-интерфейсы. Они предоставляют стабильный, документированный способ взаимодействия с подсистемами WordPress — базой данных, файловой системой, HTTP, настройками — не затрагивая внутренние механизмы, которые могут меняться между версиями. Использование API гарантирует совместимость вашего кода с будущими обновлениями WordPress.
В чём разница между Options API и Settings API?
Options API (get_option(), update_option()) — низкоуровневый механизм хранения. Он записывает пары ключ-значение в таблицу wp_options. Settings API (register_setting(), add_settings_field()) строится поверх Options API, предоставляя отрисовку админ-форм, проверку nonce для безопасности и колбэки очистки данных. Используйте Options API напрямую для программного хранения данных. Используйте Settings API для страниц конфигурации в админ-панели.
Когда использовать Кастомайзер против Settings API для опций темы?
Используйте Кастомайзер для опций, влияющих на внешний вид и выигрывающих от живого предпросмотра: цвета, шрифты, варианты макета, изображения шапки. Используйте Settings API для невизуальной конфигурации: ключи API, ID аналитики, URL соцсетей, настройки производительности без немедленного визуального эффекта. Кастомайзер даёт мгновенную визуальную обратную связь; Settings API даёт структурированные админ-страницы.
Чем Plugin API (хуки) отличается от всех остальных API?
Plugin API — единственный API, который изменяет работу самого WordPress, а не предоставляет доступ к конкретной подсистеме. Действия позволяют вставлять код в определённые точки выполнения. Фильтры позволяют изменять данные при их прохождении через WordPress. Все остальные API предоставляют функции, которые вы вызываете. Plugin API предоставляет точки, в которых вызываются ваши функции. Это событийная система и конвейер данных WordPress.
Обязательно ли использовать Database API ($wpdb) или можно писать прямой SQL?
Всегда используйте $wpdb. Прямой SQL обходит защиту WordPress, нарушает совместимость с настройкой префикса таблиц и не проходит код-ревью и проверки каталога плагинов. $wpdb->prepare() предотвращает SQL-инъекции. $wpdb->prefix обрабатывает вариации префиксов таблиц. Использование $wpdb гарантирует работу запросов на любой установке WordPress.
Что такое Metadata API и почему он так важен?
Metadata API хранит произвольные пары ключ-значение, прикреплённые к объектам WordPress — записям, пользователям, комментариям, терминам. Это механизм, стоящий за произвольными полями, расширениями профилей пользователей, атрибутами товаров WooCommerce и SEO-метаданными Yoast. Он важен, потому что расширяет объекты WordPress без изменения схемы базы данных. Одна запись может иметь неограниченное количество записей метаданных.
Как Rewrite API и произвольные типы записей работают вместе?
При регистрации произвольного типа записей через register_post_type() WordPress автоматически генерирует правила перезаписи для постоянных ссылок этого типа. Rewrite API обрабатывает входящие URL, сопоставляет их с зарегистрированными шаблонами и преобразует во внутренние переменные запроса, понятные WP_Query. Без правильных правил перезаписи CPT возвращают 404. Сброс правил перезаписи обязателен — вызывайте flush_rewrite_rules() один раз при активации плагина.
Является ли WordPress REST API частью внутренних API?
Нет. REST API — это обращённый наружу HTTP API для взаимодействия внешних приложений с контентом WordPress через JSON-конечные точки. API, обсуждаемые здесь, — внутренние PHP-интерфейсы для разработчиков тем и плагинов. Однако REST API широко использует внутренние API: WP_Query для извлечения контента, Metadata API для произвольных полей, Options API для конфигурации.
Нажмите для реакции
