Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Написание плагина

Введение

Вплоть до версии WordPress 1.2 возможность изменения его функционала «под свои потребности» или расширение возможностей достигались путем редактирования исходного кода ядра платформы Wordpress (грубо говоря, «хакинга» ядра). Но это создавало различные неудобства (например, при обновлении версий), и от такой практики вскоре отказались. Разработчики внедрили достаточно удобную, понятную и легкую в использовании программистами систему расширения функционала с помощью «плагинов». Основная идея использования новой системы расширения возможностей состояла в том, чтобы сохранять ядро целостным и неизменяемым и в то же время дать PHP-программистам возможность изменять его поведение с помощью специальных легко подключаемых (и отключаемых) скриптов-плагинов. Итак, что такое плагин Wordpress?

Плагин WordPress 
Плагин WordPress — это программа или набор функций, написанных на PHP, добавляющих определенный набор возможностей или сервисов к блогу на WordPress, которые легко объединяются с системой управления и функционалом WordPress при помощи Plugin Application Program Interface (API).

Если вы хотите добавить или изменить какую-либо функциональность Wordpress, первое, что вам нужно сделать, это поискать уже готовые решения в разнообразных хранилищах плагинов (которые вы найдете в статье «Плагины») — может быть, кто-нибудь уже создал плагин, который удовлетворит ваши потребности. Если же вы ничего не нашли, эта статья поможет вам понять процесс создания собственных плагинов.

Эта статья подразумевает, что вы уже знакомы с основами функциональности WordPress, а также с языком программирования PHP.

Ресурсы

  • Plugin Resources — всеобъемлющий список статей и средств для разработчиков плагинов, включающий в себя развернутые статьи по написанию плагинов и статьи на специфические «узкие» темы.
  • Другой хороший путь изучить устройство плагинов — смотреть в исходные PHP-коды хорошо написанных плагинов, таких как Hello Dolly (плагин, входящий в базовую поставку WordPress).
  • Если вы написали плагин к WordPress, прочитайте Plugin Submission and Promotion, чтобы узнать, как распространить ваш плагин.

Создание плагина

Эта часть статьи даст вам понять, какие шаги вы должны предпринять для создания хорошего плагина.

Имена, файлы и местоположения

Имя плагина

Первая задача при создании плагина — подумать, что плагин будет делать, и придумать для него имя (желательно уникальное). Проверьте «Плагины» и другие хранилища, чтобы убедиться в том, что придуманное вами имя — уникальное; вы можете также погуглить по выбранному вами имени. Большинство разработчиков плагинов выбирают имена, которые отражают функциональность их плагина; например, плагин для отображения погоды может иметь в названии слово «погода». Название может состоять из нескольких слов.

Файлы плагина

Следующий шаг — создание файла PHP с именем, производным от названия плагина. Например, если ваш плагин будет называться Fabulous Functionality, вы можете назвать ваш файл fabfunc.php. Опять же, попробуйте создать уникальное имя. Люди, которые установят ваш плагин, положат этот файл в свою директорию для плагинов, wp-content/plugins/, и никакая пара используемых плагинов не должна иметь одинаковое имя файла.

Другой вариант — разбить ваш плагин на несколько файлов. Ваш плагин должен иметь как минимум один файл PHP; он также может содержать файлы JavaScript, CSS, изображения, языковые файлы и т.п. Если ваш плагин состоит из нескольких файлов, задайте уникальное имя для директории, в которой они лежат, и для главного файла PHP, такие как fabfunc и fabfunc.php в нашем примере, положите ваши файлы в эту директорию и дайте пользователям возможность устанавливать целую директорию в wp-content/plugins/.

В этой статье «PHP-файл плагина» означает главный PHP-файл, который находится в директории wp-content/plugins/ или в ее поддиректории.

Файл Readme

Если вы хотите разместить ваш плагин на http://wordpress.org/extend/plugins/, вам необходимо создать файл readme.txt в стандартном формате и включить его в свой плагин. Смотрите http://wordpress.org/extend/plugins/about/readme.txt для получения разъяснений по формату.

Домашняя страница

Также очень удобно создать веб-страницу, играющую роль «домашней страницы» вашего плагина. Эта страница должна объяснять, как установить плагин, что он делает, с какими версиями WordPress совместим, что менялось от версии к версии вашего плагина, и как его использовать.

Заголовки файла

Самое время внести некоторую информацию в ваш главный файл PHP.

Стандартная информация о плагине

Начало вашего файла должно содержать стандартный информационный заголовок. Этот заголовок позволяет WordPress понять, что ваш плагин существует, добавить его в панель управления плагинами, где он может быть активирован, загрузить его и запустить его функции; без заголовка ваш плагин никогда не будет активирован и запущен. Вот формат заголовка:

<?php
/*
Plugin Name: Название плагина
Plugin URI: http://страница_с_описанием_плагина_и_его_обновлений
Description: Краткое описание плагина.
Version: Номер версии плагина, например: 1.0
Author: Имя автора плагина
Author URI: http://страница_автора_плагина
*/
?>

Минимальная информация, которая нужна WordPress, чтобы обнаружить ваш плагин — его название (Plugin Name). Остальная информация (если она есть) используется для создания таблицы плагинов на странице управления плагинами. Порядок строк неважен.

Лицензия

За стандартным заголовком обычно следует информация о лицензии на плагин. Большинство плагинов используют лицензию GPL или лицензию, совместимую с GPL. Для указания лицензии GPL добавьте следующие строки в файл вашего плагина:

<?php
/*  Copyright ГОД  ИМЯ_АВТОРА_ПЛАГИНА  (email: E-MAIL_АВТОРА)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>

Программирование плагина

Теперь пришло время заставить ваш плагин что-то делать. Эта часть статьи содержит несколько основных идей разработки плагинов, и объясняет, как довести до совершенства несколько задач, которые ваш плагин будет делать.

Зацепки (Hook) плагина

Итак, как же взаимодействуют компоненты системы плагин + ядро Wordpress? Для того, чтобы плагины имели возможность влиять на работу ядра Wordpress или на конечный результат его действий, была придумана система так называемых зацепок (часто их без перевода так и называют «хуками» от англ. hook — крючок, зацепка). Принцип ее действия состоит в том, что каждая более или менее важная элементарная функция в ядре Wordpress перед тем как вернуть какой-то результат своей работы или совершить какое-то важное действие (например вывести содержимое записи на странице, или произвести запрос к базе данных) «пытается» исполнить дополнительные инструкции (строки кода), предназначенные именно для нее в файлах плагина. Такую попытку она делает с помощью зацепок, которые прописаны в теле этой функции. Вот пример вызова зацепок плагинов из ядра Wordpress:

<?php
function get_the_title( $id = 0 ) {
…
…
 return apply_filters( 'the_title', $title, $post->ID ); //Пример зацепки для функции get_the_title();
}
?>

Если в плагине существует код, предназначенный изменить поведение одной из стандартных функций ядра, то он будет исполнен той функцией, для которой назначался. Если нет — функция ядра сработает как обычно.

Например, перед тем как WordPress добавляет заголовок к записи, он сначала проверяет, имеет ли какой-либо плагин зарегистрированные функции для зацепки под названием «the_title».

<?php
…
 add_filter( 'the_title', 'my_own_function_for_title' ); //Так выглядит регистрация в файле плагина новой функции my_own_function_for_title(); с дополнительным инструкциями для зацепки 'the_title'.
…
?>

Если имеет, текст заголовка «пропускается» через каждую такую зарегистрированную функцию, и выводится конечный результат.

<?php
…
/* Так в плагине может выглядеть функция, изменяющая заголовки Wordpress. В данном случае она заставляет выводить каждое слово заголовка с большой буквы. 
*/
 my_own_function_for_title( $title ){
      $title = ucwords($title);
      return $title;
} 
…
?>

Таким образом, если ваш плагин должен добавлять некую информацию к заголовку записи или изменять ее, в нем должна быть зарегистрирована зацепка-фильтр для «the_title» и в нем должна быть фукнция, которая делает все нужные изменения с заголовками.

Другой пример — существует зацепка под названием «wp_footer». Перед концом HTML-страницы, которую генерирует WordPress, он проверяет, имеют ли какие-нибудь плагины зарегистрированную функцию для «wp_footer», и запускает ее в случае обнаружения таковой.

Все зацепки в Wordpress делятся на две категории — Фильтры и Действия. (filters и actions соответственно). Фильтры (filters) действительно предназначены для «фильтрования» (изменения) любых данных, перед тем как они будут выведены на странице или добавлены для хранения в базу данных. Это фильтрация спама, ошибок или просто ошибочного ввода в формах, откуда, собственно, и произошло английское название. А вторые (действия, actions) предназначены для замены различных действий ядра вашими действиями (например изменения строки запроса к базе данных), в программировании такое изменение действий базового функционала ещё называют перегрузкой.

Вы можете узнать больше о том, как регистрировать функции для Фильтров и Действий, и какие действия ядра можно изменить в WordPress, в Plugin API. Если вы нашли место в коде WordPress, где вы хотели бы иметь Действие или Фильтр, но в WordPress его нет, вы можете предложить новые зацепки (предложения в основном принимаются); как это сделать, вы можете узнать в Reporting Bugs.

Теги шаблонов

Другой путь добавления функциональности с помощью плагина — создание тегов шаблонов. Тот, кто хочет использовать ваш плагин, может добавить эти теги в свою тему, в панель, в секцию содержимого записи, или в другое соответствующее место. Например, плагин, который добавляет географические теги к постам, может определить функцию тега шаблона под названием geotag_list_states() для боковой колонки, который составляет список всех постов, помеченных гео-тегами, со ссылкой на архив страниц плагина.

Чтобы объявить тег шаблона, просто напишите функцию PHP, и задокументируйте ее для пользователей плагина на вашей странице, посвященной плагину и/или в главном файле плагина. Хорошая идея, документируя функцию, приводить пример выполнения, содержащий <?php и ?>, который нужно добавить в тему для получения результата..

Сохранение данных плагина в базе

Большинство плагинов получают некую информацию от владельца блога или от его пользователей для использования ее в фильтрах, действиях, и функциях шаблонов, которую нужно хранить между сессиями. Эта информация требует сохранения в базе WordPress на длительное время между сессиями. Вот два основных метода сохранения данных в базу:

  1. Используйте механизм настроек WordPress (о нем рассказывается ниже). Этот метод предназначен для хранения относительно небольшого количества именованной статической информации — данных, которые владелец блога вводит при первом запуске плагина, и затем редко изменяет.
  2. Создайте новую отдельную таблицу в базе данных. Этот метод предназначен для данных, связанных с определенными записями, страницами, приложениями или комментариями — данных, объем которых растет с течением времени, и которые не имеют индивидуальных имен. Смотрите Creating Tables with Plugins для получения информации, как создать таблицу плагина.

Механизм настроек WordPress

Информацию о том, как создать страницу, автоматически сохраняющую ваши настройки, можно получить в статье «Создание страниц настройки».

WordPress имеет механизм для сохранения, обновления и извлечения отдельных именованных данных, хранящихся в базе WordPress. Значения настроек могут быть строками, массивами или объектами PHP (они будут сериализованы или сконвертированы в строку перед записью, и десериализованы перед извлечением). Названия настроек — строки, и они должны быть уникальными, чтобы не конфликтовать с Wordpress или другими плагинами.

Вот главные функции, которые ваш плагин может использовать, чтобы получить доступ к настройкам WordPress:

add_option($name, $value, $deprecated, $autoload);
Создает новую настройку; не делает ничего, если опция уже существует.
$name
Обязательный (строка). Имя настройки.
$value
Необязательный (строка), по умолчанию — пустая строка. Значение настройки.
$deprecated
Необязательный (строка), больше не используется WordPress. Можно передать пустую строку или null, чтобы использовать следующий за ним параметр $autoload.
$autoload
Необязательный, по умолчанию — «да» (enum: «да» или «нет»). Если установлено «да», настройки автоматически извлекаются функцией get_alloptions.
get_option($option);
Извлекает значение настройки из базы.
$option
Обязательный (строка). Имя настройки, значение которой нужно получить. Список настроек по умолчанию, созданных при установке WordPress, можно найти в Option Reference.
update_option($option_name, $newvalue);
Обновляет или создает значение настройки в базе (примечание: можно не вызывать add_option, если вам не нужен параметр $autoload).
$option_name
Обязательный (строка). Имя настройки для обновления.
$newvalue
Обязательный. Новое значение настройки.

Панели администирования

При условии, что ваш плагин имеет некие опции, хранящиеся в базе WordPress (см. раздел выше), вы, вероятно, захотите иметь административную панель, которая позволит пользователям смотреть и редактировать настройки вашего плагина. Методы создания панелей описаны в статье «Добавление административных меню».

Интернационализация плагина

После того, как вы закончили писать ваш плагин, его необходимо интернационализировать (при условии, что вы планируете распространять ваш плагин). Интернационализация — это процесс настройки программного обеспечения под локализацию; локализация — это процесс перевода на различные языки отображаемого программой текста. WordPress используется по всему миру, и интернационализация и локализация встроены в его структуру, в том числе, и локализация плагинов. Подробности использования GNU gettext для локализации WordPress можно узнать в Translating WordPress.

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

  • Выберите имя для пространства перевода вашего плагина. Обычно оно такое же, как имя главного файла вашего плагина (только без .php). Имя должно быть уникальным.
  • Везде, где ваш плагин использует строки текста, которые будут показаны пользователю (известны как «сообщения»), заключите их в одну из двух gettext-функций WordPress. Заметьте, что в вашем плагине вы должны использовать второй аргумент — имя пространства перевода, которое вы выбрали (в ядре WordPress аргумент $domain остается пустым).
__($message, $domain) 
Переводит $message, используя текущую локаль для $domain. Оберните строки, которые собираетесь использовать в расчетах, в эту функцию.
_e($message, $domain) 
Переводит $message, используя текущую локаль для $domain, и выводит на экран. Оберните в эту функцию строки, которые собираетесь показывать пользователю.
  • Создайте для вашего плагина файл POT (каталог переводов для всех переводных сообщений) и распространяйте его вместе с плагином. Пользователям необходимо будет положить MO-файл перевода в директорию вашего плагина и назвать его domain-ll_CC.mo, где ll_CC — имя нужной локали. Для получении информации о файлах POT, MO и локалях см. Translating WordPress.
  • Загружайте перевод для текущей локали и ваше текстовое пространство с помощью функции load_plugin_textdomain до того, как вызываются функции gettext, но настолько поздно, насколько возможно в сессии (потому что некоторые многоязычные плагины меняют локаль при загрузке). Одна из возможных реализаций — объявление функции инициализации, которая вызывается выше всех функций вашего плагина. Например, ваше пространство текста называется «fabfunc»:
$fabfunc_domain = 'fabfunc';
$fabfunc_is_setup = 0;

function fabfunc_setup()
{
   global $fabfunc_domain, $fabfunc_is_setup;

   if($fabfunc_is_setup) {
      return;
   } 

   load_plugin_textdomain($fabfunc_domain, PLUGINDIR.'/'.dirname(plugin_basename(__FILE__)));
}

Если ваш плагин не находится в собственной поддиректории, второй аргумент функции load_plugin_textdomain можно опустить.

Если вы читаете эту секцию, чтобы интернационализировать тему, можно следовать приведенным выше рекомендациям, с некоторыми исключениями:

  • MO-файл нужно скопировать в каталог темы (рядом со style.css).
  • MO-файл нужно назвать ll_CC.mo, где ll_CC — имя локали (т.е. имя пространства не должно быть частью имени файла).
  • Чтобы загрузить имя пространства перевода, вставьте следующий код (с PHP-заголовком, если необходимо) в файл functions.php вашей темы:
load_theme_textdomain('имя_пространства');

Советы по разработке плагина

Это последняя часть статьи, включающая в себя различные советы по разработке плагина.

  • Код плагина должен соответствовать стандартам разработки WordPress. Пожалуйста, примите во внимание также стандарты Inline Documentation.
  • Все функции вашего плагина должны иметь уникальные имена, отличные от имен функций ядра WordPress, других плагинов или тем. По этой причине, хорошая идея — использовать уникальный префикс для имен функций вашего плагина. Другая возможность — объявлять ваши функции внутри класса (который тоже должен иметь уникальное имя).
  • Не используйте явно префикс базы данных WordPress (обычно «wp_») в вашем плагине. Вместо этого используйте переменную $wpdb->prefix.
  • Чтение базы — легкий процесс, а вот запись в базу — сложный. Базы исключительно хороши при сборке данных и их выдаче, эти операции обычно выполняются быстро. Внесение изменений в базу — более комплексный процесс, следовательно более ресурсоемкий. В результате, постарайтесь уменьшить количество записей в базу. Держите все готовым в коде, тогда вы сможете делать только те записи в базу, которые действительно нужны.
  • Выбирайте из базы при помощи SELECT только то, что вам нужно. Даже несмотря на то, что базы извлекают данные достаточно быстро, вы можете уменьшить нагрузку на базу, выбирая только те данные, которые вам нужны. Если вам нужно подсчитать количество строк в таблице, не используйте SELECT * FROM, потому что все данные всех строк будут занимать память. Подобно этому, если вам нужны только post_id и post_author в вашем плагине, выбирайте с помощью SELECT только эти конкретные поля, чтобы уменьшить нагрузку. Помните: сотни других процессов могут обращаться к базе одновременно с вами. База и сервер могут только распределять ресурсы между процессами. Изучите, как минимизировать обращения вашего плагина к базе, чтобы гарантировать, что ваш плагин не злоупотребляет ресурсами.

Внешние ресурсы