Engel Side

В процессе работы над сайтом на WordPress мне понадобилось написать плагин. Документации на русском языке я нигде не нашла, поэтому пришлось читать на английском – официальную статью Writing a plugin. По ходу дела и перевела.

Так как это мой первый опыт перевода больших технических текстов, ляпы имеются. Любые исправления будут приняты с радостью ;)

Перевод под катом.

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

Введение

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

Плагин WordPress

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

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

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

Ресурсы

Plugin Resources — всеобъемлющий список статей и средств для разработчиков плагинов, включающий в себя развернутые статьи по написанию плагинов, и статьи на специфические «узкие» темы.

Другой хороший путь изучить устройство плагинов — это смотреть в исходные PHP-коды хорошо написанных плагинов, таких как Hello Dolly, плагин, входящий в базовую поставку WordPress.

Если вы написали плагин к WordPress, прочитайте Plugin Submission and Promotion, чтобы узнать, как распространить ваш плагин.

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

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

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

Имя плагина

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

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

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

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

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

Файл «Прочитай меня» (Read me)

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

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

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

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

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

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

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

<?php
/*
Plugin Name: Название вашего плагина
Plugin URI: http://URI_страницы_которая_описывает_ваш_плагин
Description: небольшое описание плагина.
Version: номер версии
Author: имя автора
Author URI: http://URI_автора
*/
?>

(естественно, все должно быть по-английски — прим. переводчика)

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

Лицензия

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

<?php
/* Copyright YEAR PLUGIN_AUTHOR_NAME (email : PLUGIN AUTHOR EMAIL)
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
?>


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

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

«Ловушки» (Hooks) плагина

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

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

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

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

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

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

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

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

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

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

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

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

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

add_option($name, $value, $description, $autoload);

Создает новую настройку; не делает ничего, если опция уже существует.

• $name — обязательный (строка). Имя настройки.
• $value — необязательный (строка), по умолчанию пустая строка. Значение настройки.
• $description – необязательный (строка), по умолчанию пустая строка. Описание настройки, которое находится в базе, чтобы кто-либо, просматривающий базу, понимал, что это за настройка.
• $autoload – необязательный, по умолчанию – «да» («да» или «нет»). Если установлено «да», настройки автоматически извлекаются функцией get_alloptions.

get_option($option);

Извлекает значение настройки из базы.

• $option — обязательный (строка). Имя настройки, значение которой нужно получить.

update_option($option_name, $newvalue);

Обновляет или создает значение настройки в базе (примечание: add_option не может быть вызвана без использования $description или $autoload параметров).

• $option_name — обязательный (строка). Имя настройки для обновления.
• $newvalue — обязательный. Новое значение настройки.

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

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

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

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

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

• Выберите имя для пространства перевода вашего плагина. Обычно оно такое же, как имя главного файла вашего плагина (только без .php). Имя должно быть уникальным.
• Везде, где ваш плагин использует строки текста, которые будут показаны пользователю (известны как «сообщения»), заключите их в одну из двух gettext-функция WordPress. Заметьте, что в вашем плагине вы должны использовать второй аргумент – имя пространства перевода, которое вы выбрали (в ядре WordPress этот аргумент остается пустым).

__($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, 'wp-content/plugins');
}


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

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

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

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