Как опубликовать свой плагин в репозиторий WordPress.org

Обзор

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

Часть 1. Создание плагина

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

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

Для тех кто абсолютно не знаком, расскажу вкратце - WordPress плагины вашего сайта находятся в директории /wp-content/plugins и каждый плагин имеет там свою папку. Для создания плагина вам необходимо проделать еще меньше действий, чем при создании темы, вам необходимо всего лишь создать новую папку в директории /wp-content/plugins и один файл в ней (обычно имя файла совпадает с именем папки). В нашем примере это будет acf-views/acf-views.php.

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

<?php
/*
Plugin Name: ACF Views
Description: The simplest way to display values from custom post fields anywhere on your site using shortcodes.
Version: 1.0.0
Author: WPLake
*/

(Каждая строка идет в формате  “Имя: Значение”, если копируете, не забудьте поменять значения на ваши). Список всех опций смотрите здесь.

Вот и все.

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

Часть 2. Подготовка плагина к публикации

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

1. Проверьте имя плагина

Вам необходимо подобрать уникальное имя, которые не используется другими плагинами. Чтобы проверить свободно ли имя, подставьте его в ссылку https://wordpress.org/plugins/search/my-plugin/ (вместо my-plugin) - если отобразится страница с результатами поиска (как в случае с my-plugin) - порядок, имя свободно. Если откроется страница плагина, как в случае с ACF Views - вам необходимо подобрать новое имя.

2. Заполните заголовки вашего главного файла

Заполните заголовки вашего главного файла по максимуму, требуемый минимум это : Имя плагина, Версия, и Автор. Список всех опций здесь.

<?php
/*
Plugin Name: ACF Views
Plugin URI: https://wplake.org/acf-views/
Description: The simplest way to display values from custom post fields anywhere on your site using shortcodes.
Version: 1.0.8
Author: WPLake
Author URI: https://wplake.org
*/

3. Создайте файл readme.txt

Этот файл - ваш главный способ предоставления информации о плагине людям. Данный файл будет парсится WordPress и именно его содержимое отображается на странице плагина (именно автоматический парсинг, у вас не будет панельки в wordpress.org где вы сможете править описание), т.е. все что вы запишите тут, будет отображаться на странице плагина, смотрите ACF к примеру.

Ниже пример readme.txt файла моего плагина, обязательные секции тут  :

главная (с именем вашего плагина и данными про него), description (описание плагина) и changelog (краткое описание всех обновлений, для начала будет лишь одна строка)

=== ACF Views ===
Contributors: wplake
Tags: acf, display custom fields, acf views, shortcode, widget, custom fields in frontend, show acf fields, get field values, post, page, custom page, custom post
Requires at least: 5.5
Tested up to: 6.0
Requires PHP: 7.4
Stable tag: 1.0.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The simplest way to display values from custom post fields anywhere on your site using shortcodes. Don't need to write PHP code to get field values.

== Description ==

ACF Views is the simplest way to display values from custom post fields anywhere on your site using shortcodes. This means you don't need to write PHP code to get field values, and you don't need to read documentation about field's return formats.

The views are reusable and shortcodes can be pasted ANYWHERE that supports shortcodes (e.g. Gutenberg shortcode block) with ANY THEME and ANY PAGE BUILDER.

**Important!** ACF Views plugin requires an active Advanced Custom Fields PRO plugin.

== Changelog ==

= 1.0.1 (2021-06-09): =
- Screenshots, plugin's version

Список всех доступных опций для readme.txt здесь.

С основными пунктами мы разобрались, а теперь поговорим про сам код.

Требовани к коду плагина

Здесь вы можете найти список всех требований, их около 2х десятков, однако самых важных по факту гораздо меньше :

Лицензия

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

Качество кода

Ваш код должен быть читабельным. Помните о том, что ваш код [вероятно] будут смотреть другие люди (как минимум чтобы понять как он работает, уточнить что-то или расширить его). Не используйте бессмысленные имена переменных, функций и классов, как $asdre или function werlsdf(). И в целом, будьте хорошим человеком кодером, пишите такой код, который хотели бы видеть в других плагинах. 

Используйте безопасный вывод (echo)

Это очень важный момент, WordPress от плагинов требует ‘поздней’ очистки данных.

Что это значит на деле : допустим у нас есть $_GET переменная email, которую мы хотим вывести на странице. Вы вероятно сделаете так :

$email = sanitize_text_field($_GET['email']??'');
// ...
echo "<h3>Hi, {$email}</h3>";

и это будет ошибкой. По правилам WordPress для плагинов (которые созданы чтобы уменьшить количество плагинов с уязвимостями, благодаря которым так часто взламывают сайты на WP) независимо от того, очистили ли вы переменную до вывода, или нет, вы ОБЯЗАНЫ ‘очищать’ переменную также и в самом выводе. Т.е. использовать функции esc_attr, esc_html, и в данном случае код вывода должен быть:

echo sprintf("<h3>Hi, %s</h3>", esc_html($email));

Не ленитесь, сделайте поиск по ‘echo’ и проверьте весь ваш вывод, на стадии рассмотрения плагина это действительно проверяют, и если вы упустили данный момент, то вам об этом напишут, и рассмотрение будет приостановлено до того момента, пока вы не исправите это.

Composer пакеты

И еще одно правило, от меня лично. К сожалению WordPress на данный момент не предоставляет решения для общего использования composer зависимостей плагинами, таким образом один плагин может использовать одну версию какой-либо библиотеки, а второй плагин другую версию этой же библиотеки (и поверьте, это встречается чаще, чем вы могли бы предположить). В таком случае у пользователя будет критическая ошибка и сайт ляжет. Если вы используете composer пакеты в вашем плагине, то чтобы сделать использование вашего плагина неконфликтным, используйте PHP-Scoper.

Если вкратце, то это утилита которая добавит ваше пространство имен во все файлы ваших зависимостей, и вместо namespace Dependency\Folder; будет namespace YourNamespace\Dependency\Folder; Таким образом возможный конфликт исключается, и одна и та же библиотека может находится в разных плагинах даже с разными версиями. PHP Scoper делает все это за вас автоматически, его установка и настройка не составят большого труда. Подробнее об использовании данной утилиты для WordPress плагина вы можете почитать здесь.

Часть 3. Отправка заявки

Наконец-то мы добрались до самого торжественного и волнующего момента. Время штурмовать репозиторий WP отправлять заявку на размещение вашего плагина в WordPress.org. Это абсолютно бесплатно и довольно просто. 

Во первых вам необходимо зарегистрироваться на WordPress.org (если у вас еще нет аккаунта там), подтвердить email и после этого перейти на страницу отправки заявки.

Тут вы загружаете архив с вашим плагином (обычный архив, но с папкой вашего плагина, а не просто файлы плагина без общей папки), WordPress сделает парсинг архива и выведет имя вашего плагина, которое плагин будет иметь в репозитории, (в моем случае acf-views) и выдаст предупреждение, что имя вашего плагина с момента одобрения НИКОГДА не может быть изменено. Поэтому подумайте дважды прежде чем нажимать кнопку submit.

После отправки плагин пройдет ручную модерацию (обычно в течении 1-5 рабочих дней) и вы будете уведомлены про одобрение/отклонения вашей заявки. На деле если ваш плагин не вредоносный, и качество кода не выходит за рамки приличия, то отклонение вам не грозит.

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

Часть 4. Первый коммит

Вы отправили заявку, прошло несколько долгих рабочих дней (для вас они вероятно будут долгими) и вот вы наконец-то получили письмо, приглашение в Хогвартс сообщение которое говорит о том, что ваша заявка одобрена.

Congratulations, the plugin hosting request for ACF Views has been approved.

Within one (1) hour your account (X) will be granted commit access to your Subversion (SVN) repository.

* SVN URL: https://plugins.svn.wordpress.org/acf-views
* Public URL: https://wordpress.org/plugins/acf-views

Once your account access has been activated, you may upload your code using a SVN client of your choice. If you are new to SVN (or the Plugin Directory) make sure to review all the links in this email.

To answer some common questions:

* You must use SVN to upload your code -- we are unable to do that for you
* Your SVN username is X and your password is the same as you use to log in to WordPress.org
* Your username is case sensitive
* SVN will not accept your email address as a username
* Due to the size of the directory, it may take 72 hours before all search results are properly updated

To help you get started, here are some links:

Using Subversion with the WordPress Plugin Directory:
https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/

FAQ about the WordPress Plugin Directory:
https://developer.wordpress.org/plugins/wordpress-org/plugin-developer-faq/

WordPress Plugin Directory readme.txt standard:
https://wordpress.org/plugins/developers/#readme

A readme.txt validator:
https://wordpress.org/plugins/developers/readme-validator/

Plugin Assets (header images, etc):
https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/

WordPress Plugin Directory Guidelines:
https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/

Block Specific Plugin Guidelines:
https://developer.wordpress.org/plugins/wordpress-org/block-specific-plugin-guidelines/

If you have issues or questions, please reply to this email and let us know.

Enjoy!

--
The WordPress Plugin Directory Team
https://make.wordpress.org/plugins

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

https://plugins.svn.wordpress.org/PLUGIN-NAME 
https://wordpress.org/plugins/PLUGIN-NAME

Ну а имя вашей первой любви вашего первого плагина я убежден вы запомните на всю жизнь. 

Итак, время открыть плагин общественности и сделать первый коммит. (Это делаете именно вы, а не команда WP.org, ваш плагин станет доступный для всех только после вашего первого коммита).

Итак, создаем папку и клонируем репозиторий (svn должен быть установлен) :

svn co http://plugins.svn.wordpress.org/YOUR_PLUGIN_NAME_HERE

Далее:

1. Скопируйте файлы

Скопируйте файлы вашего плагина (без папки) в директорию trunk , создайте папку с вашей версией (вероятно 1.0.0) в директории tags и добавьте файлы вашего плагина туда.

2. Выберите банер и иконку

Время задуматься про баннер (который отображается вверху страницы вашего плагина на WP.org) и иконку плагина (которая отображается в поиске WP.org возле имени вашего плагина). Это может быть любое изображение, на ваше усмотрение (в рамках приличия опять таки), вы можете добавить баннер в двух поддерживаемых разрешениях (772x250 и 1544x500) в папку assets с именем banner.

Это будут banner-772x250.png и banner-1544x500.png (или jpg). Иконка будет icon-128x128.png и icon-256x256.png (или jpg, svg).

3. Добавьте файлы в svn

Добавляем файлы в svn командами :

svn add trunk/* 
svn add tags/YOUR_VERSION_HERE
svn add assets/*

5. Сделайте коммит

svn ci -m "v 1.0.0"

(Тут консоль спросит имя пользователя и пароль вашего WP.org аккаунта, введите чтобы авторизовать). Коммит займет некоторое время (svn не так быстр как git), поэтому придется немного подождать завершения команды.

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

Дополнительно. Обновление плагина

Через некоторое время вы [вероятно] захотите добавить фичи / сделать правки в ваш плагин. Для этого необходимо выпустить новую версию. 

Итак, для выпуска новой версии необходимо:

1. Обновить файлы плагина

Обновите версию на новую в шапке вашего главного файла (“Version: X”) и обновите “Stable tag: YOUR_VERSION_HERE” в readme.txt на новую версию.

2. Обновить файлы в svn репозитории

Обновите файлы плагина в папке trunk, создайте новую папку с номером вашей версии в папке tags (1.0.1 вероятно) и скопируйте файлы плагина также туда.

3. Сделать коммит

Давайте сообщим svn про новые файлы и сделаем коммит:

// это команда должна быть выполнена до обновления trunk директории
svn delete trunk/* --force
// эти команды должны быть выполнены после обновления всех файлов
svn add trunk/*
svn add tags/{YOUR_VERSION_HERE}
svn ci -m "v YOUR_VERSION_HERE"

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

Суммирую - в репозитории вы должны обновить директорию trunk (там всегда хранится последняя версия плагина) и добавить новую папку (с номером версии в качестве имени и файлами плагина внутри) в директорию tags.

В случае если вы хотите просто обновить информацию на странице плагина, новую версию можно не выпускать, а просто обновить readme.txt файл в trunk папке и сделать коммит. 

Как вы заметили, svn репозиторий WordPress используется ТОЛЬКО для выпуска новых версий (т.е. является релиз репозиторием). Коммитить в него каждое ваше изменение, как в обычный git репозиторий нельзя! Подробнее про использование репозитория. Это приведет к тому, что ваш репозиторий станет очень медленным, и будет занимать много места на WP.org. Для разработки вашего плагина создайте свой личный git репозиторий, где сможете вести разработку и коммитить сколь угодно часто, а svn репозиторий мы используем только для выпуска новых версий. 

Надеюсь данная статья была полезной для вас, и развеяла мнение о том, что публикация своего плагина в WordPress это трудоемкий и долгий процесс. Самое время сделать этот мир чуточку лучше и опубликовать свой плагин!

Вместо P.S.

В данной статье в качестве примера я использовал свой плагин ACF Views. Если кому-то интересно, продожайте чтение, ниже я вкратце расскажу про сам плагин. Это плагин-дополнение к Advanced Custom Fields (PRO версия ACF обязательна). 

Вначале про проблемы, которые он решает.

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

Обычно это решается вручную (например в теме) - создается шорткод, который вставляет необходимые поля в разметку и выводит ее, и далее этот шорткод устанавливается на страницу/в CPT шаблон и все это стилизуется.

Однако есть ряд нюансов, таких как :

• каждый раз необходимо вручную править тему (обычно дочернюю)

• типов полей в ACF десятки, и каждый тип имеет различный return-format (который кроме типа поля еще зависит и от настроек конкретного поля, например изображение в зависимости от настроек вернет ID или массив с информацией про изображение), при создании разметки каждый тип необходимо правильно обработать, и это заставляет каждый раз смотреть оф. документацию чтобы уточнить формат конкретного поля...

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

ACF Views упрощает жизнь и выводит ACF поля на фронт сам. После создания группы, вы создаете новое View, и выбираете какие поля вы хотите вывести, сохраняете View и получаете шорткод. Вставляете шорткод на страницу/CPT шаблон и вуаля, вывод готов.

Плагин автоматически генерирует разметку в зависимости от типа поля и его настроек (поддерживает множество типов и все return-форматы). Чтобы стилизовать вывод вы можете добавить стили прямо во View (есть специальное поле), эти стили будут выведены только на страницах, где есть данная View (не глобально), и разметка уже имеет классы по умолчанию (в BEM стиле), вы можете использовать их и даже не назначать свои классы (хотя такая опция тоже есть). Есть PRO версия, которая позволяет редактировать разметку (по прежнему не заботясь про типы полей и форматы), использовать repeater и создавать Gutenberg блоки c помощью View абсолютно без кодинга. (Держите промокод, специально для читателей хабра - habr9, по нему вы получите 20% скидку)

Переведено с разрешения правообладателя, оригинал на английском здесь.