Расширение возможностей системных плагинов

Мы добавили новые возможности для более удобной разработки системных плагинов доставки и оплаты:

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

Ознакомительная обновлённая версия фреймворка для разработчиков выгружена на GitHub в ветку dev. Также в ветке dev обновлён и репозиторий Shop-Script.

Контроллеры и экшены

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

waJsonActions
waJsonController
waLongActionController
waSystemPluginActions
waSystemPluginAction

Обращение к собственным контроллерам плагина можно использовать, например, на странице настроек.

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

Готовый URL для выполнения запроса к собственному контроллеру удобно получать с помощью метода основного класса плагина getInteractionUrl($action = 'default', $module = 'backend').

Файлы HTML-шаблонов экшенов должны размещаться в директории templates/actions/[module]/[Module][Action].html.

Произвольные PHP-классы плагина

Для подключения произвольных классов плагина с использованием системного механизма автозагрузки файлы классов должны размещаться в директории lib/classes/ и именоваться по правилу [type][Plugin_id][Class_name].class.php. Имена классов в таких файлах должны именоваться по правилу [type][Plugin_id][Class_name]. Здесь [type] — это обозначение типа плагина: 'payment' или 'shipping', [Plugin_id] — идентификатор плагина, [Class_name] — произвольная часть имени класса на усмотрение разработчика.

База данных

Общие настройки плагина

Общие для всех приложений настройки плагина можно хранить в таблице wa_app_settings. Сохранять и читать такие значения можно с помощью методов:

setGeneralSettings($name, $value)
getGeneralSettings($name = null, $default = '')

Такие настройки сохраняются в таблицу со значениями поля app_id в формате webasyst.[type].[id]. Здесь [type] — это обозначение типа плагина: 'payment' или 'shipping', а [id] — это идентификатор плагина.

В качестве идентификаторов настроек нельзя использовать некоторые зарезервированные значения:

update_time — используется механизмом метаобновлений;
sync_time — используется механизмом выполнения задач по расписанию;
sync_success_time — используется механизмом выполнения задач по расписанию;
sync_failure_time — используется механизмом выполнения задач по расписанию.

Собственные таблицы плагина

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

wa_payment_%plugin_id% — для плагинов оплаты;
wa_shipping_%plugin_id% — для плагинов доставки.

Описывать структуру таблиц нужно в файле lib/config/db.php, как и для приложений и плагинов для них.

Для работы с собственной таблицей в плагине можно использовать класс waSystemPluginModel — дочерний класс waModel. В этом случае можно не оформлять самостоятельные классы моделей для каждой из таблиц плагина. С помощью метода setPlugin(waSystemPlugin $plugin, $table = null) этого класса удобно получить экземпляр waModel с указанием имени таблицы и сразу работать с данными в этой таблице.

Но если вам нужны собственные методы, которых нет в waModel, то этот способ не подойдёт — в этом случае нужно оформлять собственные классы моделей. Свои классы можно наследовать и от waSystemPluginModel.

В основном классе плагина есть метод getModel($table = null). Если в него передать имя таблицы, то он вернёт экземпляр класса для этой таблицы — если такой класс модели есть в плагине — или экземпляр waSystemPluginModel для указанной таблицы. В качестве имени таблицы нужно передать только часть имени после обязательного префикса.

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

Хранение данных в файлах

Системные плагины могут хранить собственные данные в директории wa-data/. Для работы с такими файлами можно использовать новые методы основного класса:

getDataPath($path = null, $public = false, $create = true) — получение пути к файлам;
getDataUrl($path = null, $absolute = false) — получение URL файлов.

Задачи по расписанию

Код для поддержки задач по расписанию разделён на три части:

Контроллер приложения, который вызывает метод runSync() для каждого экземпляра настроек плагина.
«Обвязка» в методе runSync() базового класса waShipping, которая использует методы syncRequired() и handleSync($result), определяющие необходимость выполнения задачи и обрабатывающие результаты её выполнения. При необходимости эти методы можно переопределить.
Метод основного класса плагина sync(), который реализует логику выполняемой задачи.

Информация о выполнении задач отображается на экране настроек плагина. В частности, если приложение не поддерживает запуск задач по расписанию, то показывается соответствующее предупреждение. Если метод получения настроек плагина getSettingsHtml() переопределён, для удобства логика отображения информации о выполнении задач вынесена в метод getNoticeHtml().

Приложение показывает инструкцию пользователю по настройке серверного планировщика для запуска контроллера приложения с рекомендуемым интервалом. Примерный вид команды: php cli.php shop shipping.

Параметры конфигурационных файлов плагина доставки

Описание возможностей плагина в файле plugin.php:
- sync — флаг поддержки обновляемых справочников или кешируемых данных; может быть булевым или содержать рекомендуемый интервал обновления данных.
Описание поддержки функциональности приложением в файле плагина app.php:
- sync — запуск обновления данных плагинов доставки и статусов отправлений по расписанию.
- rights — требуемый вид прав пользователя для взаимодействия с плагином через его контроллеры. Если поле пустое или отсутствует, то требуются административные права к приложению. Для приложения shop необходим идентификатор прав доступа settings, который даёт пользователю доступ к настройкам приложения и плагинов оплаты и доставки.
Описания адресов (URL) для callback-уведомлений плагинов доставки размещаются в файле guide.php.