Создание и добавление плагина в репозиторий WordPress

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

Оглавление

С чего начинается плагин

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

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

Плагин начинается с основного файла, в начале этого файла необходимо добавить информацию о плагине, которая будет отображаться на странице с плагинами:

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

Этих заголовков вполне достаточно для того, что бы WordPress нашел его и подключил, можно продолжать дальше. Теперь добавим к этому ещё пару строк кода:

if ( ! defined( 'ABSPATH' ) ) {
      exit;
}

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

Информация о лицензии

За стандартными заголовками плагина как правило следует информация о лицении, она

<?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
*/
?>

При копировании не забудьте исправить «ГОД», «ИМЯ_АВТОРА_ПЛАГИНА» и «E-MAIL_АВТОРА» заменив это все своей информацией.

Стандарты «кодирования» PHP

Данные стандарты  необходимы для того, что бы весь программный код, вне зависимости от того ядро это или плагин с темой, имел единый стиль для облегчения работы с кодом при необходимости внесения каких-либо изменений.

Обработка пользовательских данных

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

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

Не важно, записываете вы данные в БД или получив данные из БД, проверяйте их. Для полного понимания советую ознакомится с перечнем функций очистки и валидации данных.

Одинарные и двойные кавычки

Используйте двойные кавычки тогда, когда это необходимо, если в этом нет необходимости, то следует использовать одинарные кавычки.

echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';

При вставке значений атрибутов используйте функцию esc_attr(), это позволит избежать ошибок вызванных наличием кавычки в значении.

Использование отступов

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

Пример:

$foo   = 'somevalue';
$foo2  = 'somevalue2';
$foo34 = 'somevalue3';
$foo5  = 'somevalue4';

Для ассоциативных массивов рекомендуется начинать каждую пару «ключ-значение» начинать с новой строки. Обратите внимание на запятую в конце последней пары, это также является одной из рекомендаций, поскольку при добавлении новой пары или при изменении порядка исключаются ошибки из-за отсутствия запятой.

$my_array = array(
     'foo'   => 'somevalue',
     'foo2'  => 'somevalue2',
     'foo3'  => 'somevalue3',
     'foo34' => 'somevalue3',
);

Использование фигурных скобок

Несмотря на то, что фигурные скобки можно использовать не всегда, разработчики WordPress настоятельно рекомендуют использовать фигурные скобки даже в тех случаях, когда это не обязательно.

Использовать фигурные скобки рекомендуется в следующем стиле:

if ( condition ) {
    action1();
    action2();
} elseif ( condition2 && condition3 ) {
    action3();
    action4();
} else {
    defaultaction();
}

Следует обратить внимание на то, что запрещено использование inline-конструкций.

Запрет на сокращенные PHP-теги

Правильно:

<?php ... ?>
<?php echo $var; ?>

Неправильно:

<? ... ?>
<?= $var ?>

Использование пробелов

Разработчики WordPress настоятельно рекомендуют вставлять пробелы везде где только можно. Благодаря такому подходу код становится более наглядным, а значит и более понятным.

Необходимо всегда ставить пробелы после запятых и по обе стороны логических операторов, сравнений, строк и операторов присваивания.

x == 23
foo && bar
! foo
array( 1, 2, 3 )
$baz . '-5'
$term .= 'X'

Ставьте пробелы по обе стороны открывающих и закрывающих скобок блоков if, elseif, foreach, for, switch.

foreach ( $foo as $bar ) { ...

Определение функции:

function my_function( $param1 = 'foo', $param2 = 'bar' ) { ...

Вызов функции:

my_function( $param1, func_param( $param2 ) );

Выполнение логических сравнений:

if ( ! $foo ) { ...


Приведение типов:


foreach ( (array) $foo as $bar ) { ...
$foo = (boolean) $bar;

При обращении к элементам массива ставьте пробелы вокруг индекса только если он является переменной, например:

$x = $foo['bar']; // правильно
$x = $foo[ 'bar' ]; // неправильно
$x = $foo[0]; // правильно
$x = $foo[ 0 ]; // неправильно
$x = $foo[ $bar ]; // правильно
$x = $foo[$bar]; // неправильно

Соглашение о выборе имен

В именах переменных и функций используйте строчные буквы, а слова разделяйте знаком подчеркивания  «_». Ни в коем случае не сокращайте имен функций и переменных если в этом нет необходимости, это необхлодимо для легкого понимания предназначения переменной или функции.

function some_name( $some_variable ) { [...] }

Имена классов должны состоять из слов начинающихся с прописной буквы, а в качестве разделителя необходимо использовать знак подчеркивания. При сокращении, мена классов должны состоять исключительно из букв верхнего регистра.

class Walker_Category extends Walker { [...] }
class WP_HTTP { [...] }

Имена констант должны состоять из букв верхнего регистра и в качестве разделителя должен использоваться знак подчеркивания.

define( 'DOING_AJAX', true );

Имена файлов должны описывать содержание и состоять из строчных букв, а разделяться дефисами.

my-plugin-name.php

Имена файлов, содержащих классы, должны образовываться на основе имени класса с префиксом class-, знаки подчеркивания в имени класса должны заменяться на дефисы, например WP_Error становится:

class-wp-error.php

Условия Йоды

if ( true == $the_force ) {
      $victorious = you_will( $be );
}

Несмотря на то, что данный пример выглядит совсем непривычно, такой способ логического сравнения избавит вас от ошибки если вы пропустите один знак равенства, точнее ошибка произойдет, но эта ошибка будет критической. Если в условии будет $value = true, то это условие будет всегда верно, поскольку всегда будет возвращать 1. Наверняка вы сталкивались с подобной ошибкой и долго искали в чем проблема. Но если условие будет таким: true = $value, то это вызовет критическую ошибку.

Такой принцип непривычен, но со временем вы к этому привыкнете.

Обратите внимание на то, что это относится к ==, !=, ===, !==. Для <,>, >=, <= подобные условия читать сложнее, по этому в этих случая условия Йоды стоит избегать.

Более подробно обо всем об этом читайте на этой странице: https://codex.wordpress.org/Стандарты_кодирования_PHP

Подготовка плагина к добавлению в репозиторий

Прежде чем инициировать процесс добавления плагина в репозиоорий, есть смысл заранее озадачится  дополнительными составляющими, которые необходимы для полноценного взаимодействия плагина с репозиторием..

Подготовка баннеров для плагина

Прежде чем загрузить плагин в репозиторий, необходимо подготовить баннеры и иконки для вашего плагина. Баннеры и иконки необходимо изготовить в двух экземплярах.

Баннеры

  • banner-772x250.(jpg|png)
  • banner-1544x500.(jpg|png)

Пример отображения:

Иконки

  • icon-128x128.(png|jpg)
  • icon-256x256.(png|jpg)

Подготовили файлики и сохранили бережно исходники. К ним мы ещё вернемся.

Скриншоты

Создаем скриншоты, которые демонстрируют те или иные аспекты плагина, для большего понимания принципа работы или его предназначения. Имена файлов должно быть в формате: Screenshot-1.(jpg|png), где цифра «1» является порядковым номером скриншота и должна меняться. В итоге у вас должен получиться набор файлов:

  • Screenshot-1.(jpg|png)
  • Screenshot-2.(jpg|png)
  • Screenshot-3.(jpg|png)
  • Screenshot-4.(jpg|png)
  • Screenshot-5.(jpg|png)

Заполнение файла readme.txt

Это самое интересное и, на первый взгляд, самое трудное, поскольку у многих с файлом readme.txt возникают трудности. Вот пример файла readme.txt, если у вас нет проблем с английским, то этого файла достаточно что бы понять что для чего в этом файле. для тех, кто не силен в английском, я попробую объяснить по-русски. Итак начнем.

=== Plugin Name ===

Как вы наверняка понимаете, вместо «Plugin Name» необходимо указать имя вашего плагина. Теперь разберемся с остальными пунктами.

  • Contributors. Никнеймы разработчиков. В качестве никнеймов используется логин на сайте wordpress.org. Если вы там не зарегистрированы, то пора бы это сделать.
  • Donate link. Ссылка на страницу, где принимаются пожертвования. Для сбора пожертвований рекомендую мой плагин «попрошайка».
  • Tags. Тут мы перечисляем метки, которые описывают суть плагина для простоты поиска вашего плагина в репозитории.
  • Requires at least. Минимальная версия WordPress с которой ваш плагин будет работать без ошибок.
  • Tested up to. Максимальная версия WordPress с которой был протестирован плагин.
  • Stable tag. Этот пункт сообщает WordPress’у какая версия является стабильной. Обратите внимание на то, что в папке trunk репозитория, куда вы будете загружать свой плагин, как правило лежит разрабатываемая версия программы, а в папке tags лежат стабильные версии плагина. Допустим версия вашего плагина 1.0 и эта версия является стабильной, то для неё в папке tags необходимо создать папку 1.0 и туда загрузить файлы плагина. В данном пункте пишем 1.0. При установке плагина, WordPPress будет брать файлы из tags/1.0. А в папке trunk вы спокойно можете работать над следующей версией плагина. Как только будет готова новая версия, например 1.1, то в папке tags создаете папку 1.1 и в неё копируете файлы из папки trunk. После этого в readme.txt меняете Stable tag на 1.1 (причем в обоих копиях readme.txt в папке trunk и tags/1.1), как только вы смените значение этого пункта, у тех, кто установил ваш плагин появится уведомление о новой версии плагина.
  • License. Тип лицензии. Обычно берут стандартное «GPLv2 or later»
  • License URI. Соответственно ссылка на информацию о лицензии в случае с «GPLv2 or later» указываем «https://www.gnu.org/licenses/gpl-2.0.html»

Затем после блока вышеописанных параметров идет строчка, которая является кратким описанием плагина, которое отображается в списке плагинов. Длина краткого описания не должно превышать 150 символов, но в случае с кирилицей, это ограничение ещё меньше, видимо из-за кодировки. В любом случае созданный файл readme.txt проверяйте валидатором.

== Description ==

Переходим к «Description». Тут нас никто не ограничивает в объемах текста, более того, тут работает разметка Markdown, которая имеет своеобразный синтаксис. О самом синтаксисе мы поговорим чуть позже, а пока о самом файле readme.txt.

== Installation ==

Следующий раздел, который идет после описания, «Installation». Тут необходимо описать процесс установки плагина. Не ограничивайтесь стандартным набором «скачал-распаковал-активировал», уделите внимание ещё и минимальному набору настроек необходимых для запуска плагина.

== Frequently Asked Questions ==

Раздел «Frequently Asked Questions» предназначен для организации FAQ, где необходимо перечислить часто задаваемые вопросы и ответы на них. Если у вас пока нет конкретной информации, то подумайте какие вопросы могут возникнуть у людей, использующих ваш плагин и перечислите их в этом разделе.

= Вопрос =

Ответ

= Вопрос2 =

Ответ2

== Screenshots ==

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

  1. Описание Screenshot-1
  2. Описание Screenshot-2
  3. Описание Screenshot-3
  4. Описание Screenshot-4
  5. Описание Screenshot-5

Обратите внимание на то, что в описании скриншотов так же допускается использование Markdown.

== Changelog ==

Этот раздел предназначен для описания изменений, которые были сделаны в определенных версиях. Принцип несложный и сводится к такому формату:

= 1.0 =
* Добавлен такой-то функционал.
* Исправлены такие-то ошибки.

= 0.5 =
* Добавлен новый функционал.

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

== Upgrade Notice ==

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

= 1.0 =

Эта версия  исправляет ошибку связанную с безопасностью.

= 0.5 =

В уведомлениях об обновлении описывается причина, по которой пользователь должен обновить. Не более 300 символов.

== Произвольный раздел ==

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

Использование разметки Mardown в readne.txt

Данная разметка по своему принципу напоминает BBCode, но использует совсем иной синтаксис, давайте рассмотрим самые часто используемые.

Жирный текст

Для того, что бы выделить слово жирным, необходимо пометить это слово двумя способами:

  1. **жирный текст**
  2. __жирный текст__

Курсив

  1. *курсив*
  2. _курсив_

Гиперссылка

[Текст ссылки](http://example.com «Всплывающая подсказка»)

Маркированный список

Обратите внимание на тот факт, что для того, что бы данная разметка сработала, необходимо начие пустых строк между пунктами списка.

  1. * пункт* пункт* пункт
  2. — пункт- пункт- пункт

Нумерованный список

  1. пункт
  2. пункт
  3. пункт

Заголовки

Данная разметка аналогична разметке тегами h1-h6.

  1. # Заголовок 1
  2. ## Заголовок 2
  3. ### Заголовок 3
  4. #### Заголовок 4 ####
  5. ##### Заголовок 5 #####
  6. ###### Заголовок 6 ######

Аббревиатуры

При использовании этой разметки в качестве результата мы увидим аббревиатуру «ПАО» с всплывающим текстом «Публичное акционерное общество» при наведении курсора.

*[ПАО]: Публичное акционерное общество

Более подробно обо всех методах разметки читайте на этой странице:

Добавление плагина в репозиторий

Данная операция элементарна и не требует особых трудозатрат. Первым делом вам необходимо зарегистрироваться на wordpress.org, если вы этого ещё не сделали. После регистрации необходимо пройти на страницу «Добавить Ваш плагин». Указываем наименование плагина, описание и ссылку на архив с плагином. Обратите внимание на то, что описание плагина необходимо указывать на английском.

Жмем кнопку «Send Post». Готово. Ждем ответа.

Работа с SVN-репозиторием

Дождавшись ответа ревьювера с темой «[WordPress.org Plugins] Request Approved: …» ищем в письме ссылку «https://plugins.svn.wordpress.org/[название вашего плагина]/» и копируем её. Поскольку я фанат линуксов, то соответственно работать с svn я люблю исключительно в командной строке.

Для начала получим копию нашего глобального хранилища выполнив команду:

svn co https://plugins.svn.wordpress.org/[название вашего плагина]

Обратите внимание что я намеренно упустил параметр после url, который определяет имя каталога хранилища, в нашем случае оно будет таким же как название плагина в конце url.

После выполнения команды в появившейся папке мы увидим несколько папок:

  1. assets
  2. branches
  3. tags
  4. trunk

Копируем файлы плагина в папку trunk, затем, если текущая версия плагина является стабильной, то создаем в папке tags папку в качестве имени которой используем текущую версию плагина и копируем файлы туда.

Ранее созданные иконки, баннеры и скриншоты копируем в папку assets. Все готово для публикации плагина в репозиторий. ам осталось всего лишь выполнить несколько команд.

Поскольку файлы мы копировали без ведома svn, то это значит оно не знает о существовании этих файлов, что бы это исправить, нам неободимо добавить их а базу svn, сделать это можно командой add.

svn add trunk/*

Мы добавили содержимое папки trunk, теперь нам необходимо добавить содержимое остальных папок:

svn add tags/*
svn add assets/*

Вот и все, теперь нам осталось загрузить это все в глобальное хранилище, для этого выполняем команду ci.

svn ci -m "Комментарий описывающий изменения"

В нашем случае можно написать «Публикация плагина». Несмотря на то, что многие пишут комментарии на английском, я предпочитаю родной язык. В конце концов пора учить и Русский язык, а не только английский.

Для получения остальных команд, выполните команду help.

svn help

Вот собственно и все, этого вполне достаточно для начала работы с репозиторием WordPress..

Оценка статьи

Полная фигняУзнал немного новогоНормальная статьяХорошая статьяСупер! (2 оценок, среднее: 5,00 из 5)
Загрузка...

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

Подпишитесь на рассылку и получайте новые статьи на почту