Создание PHP Плагина для Metabot и Использование его в JS Коде Бота

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

Урок состоит из двух частей. Сперва вы создаете условно бэк - сам PHP плагин. Затем вы подключаете его на фронте, в боте, для доступа к PHP через JS Low-Code.

Создание и Использование PHP Плагина

Шаг 1. Создание PHP Плагинаплагина

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

1. Создайте новый плагин, если необходимо. В этом уроке мы назвали плагин PluginBoilerplate.

2. В плагине создайте скрипт с расширением PHP (ОБЕРТКА ДЛЯ V8).

Metabot поддерживает три вида скриптов в плагине: JavaScript, PHP, PHP (ОБЕРТКА для V8). JavaScript — это обычный Low-Code, как и скриптах самого бота, в который вы можете вынести код для повторного использования в разных скриптах в боте или в других JS плагинах. PHP — это модуль PHP, который используется в других PHP модулях или в PHP обертках. PHP Wrapper for V8 или PHP (Обертка для V8)   —  это специальный модуль PHP, который доступен через JS на уровне бота, т.е. это некий промежуточный слой на PHP для которого можно определить JS интерфейс.

3. Скопируйте эту заготовку кода в скрипт вашей PHP обертки.

<?php
namespace Plugins\Dynamic\Common\PluginBoilerplate\V8Wrapper

use App\Bot
use App\Lead
use App\Business
use App\Modules\V8\Exception\UnauthotizedV8Exception
use App\Modules\V8\ScriptBase

class PhpPlugin extends ScriptBase {
    /** @var Business|null */
    protected $_business = null

    /** @var Bot */
    protected $_runFromBot = null

    /** @var Bot */
    protected $_bot = null
    
    /** @var Lead */
    protected $_lead
    
    protected HttpClient $httpClient

    public function __construct()
    {

    }    
    
    /**
     * @param array $params
     *
     * @throws UnauthotizedV8Exception
     */
    public function initializeJs($params)
    {
        $this->_business = $params['business'] ?? null
        $this->_runFromBot = $params['bot'] ?? null
        $this->_lead = $params['lead'] ?? null
        if ($this->_lead && $this->_lead->bot) {
            $this->_bot = $this->_lead->bot
        }

        $this->checkPolicy()
    }    
    
    protected function checkPolicy()
    {
        // Проверка наличия бизнеса
        if (empty($this->_business) || !($this->_business instanceof Business)) {
            throw new UnauthotizedV8Exception()
        }
        // Проверка наличия бота
        if (empty($this->_bot) || !($this->_bot instanceof Bot)) {
            throw new UnauthotizedV8Exception()
        }
        // Проверка наличия лида
        if (empty($this->_lead) || !($this->_lead instanceof Lead)) {
            throw new UnauthotizedV8Exception()
        }
        // Дополнительные условия безопасности
    } 
    
    public function itWorks() {
        return "Plugin works!"
    }    
}

Создание PHP плагинов - ответственный процесс, требующий строгого контроля безопасности. Подробнее о checkPolicy() смотрите ниже.

4. Важно правильно указать namespace, иначе ваш плагин не подключится. Замените ИмяПлагина на название вашего плагина. В нашем примере это PluginBoilerplate.

namespace Plugins\Dynamic\Common\ИмяПлагина\V8Wrapper;

Указывайте имя плагина с учетом регистра. PluginBoilerplate и pluginBoilerplate это разные плагины!

5. Важно правильно указать имя класса в соответствии с названием скрипта плагина. 

Вместо ИмяКласса укажите название вашего класса.

class ИмяКласса extends ScriptBase {

Название класса должно совпадать с названием скрипта PHP обертки! В противном случае ваш плагин не будет работать!

6. Создайте JS скрипт в плагине. Выберите созданную ранее PHP обертку. Название может быть любое, но мы рекомендуем JS скрипт называть также как PHP скрипт, это поможет вам избежать путаницы в дальнейшем.

В итоге, у вас должен получиться плагин с двумя скриптами:

Дополнение: Важность Методовметодов initializeJs и checkPolicy

В создании PHP плагинов для Metabot, особое внимание следует уделить методам initializeJs и checkPolicy. Эти методы играют ключевую роль в обеспечении безопасности и правильной инициализации плагина.

Правильная реализация методов initializeJs и checkPolicy гарантирует, что ваш PHP плагин будет не только функциональным, но и безопасным для использования в рамках платформы Metabot. Это обеспечит стабильность и надежность ваших решений на платформе.

Метод	Описание
initializeJs	Этот метод отвечает за инициализацию JavaScript обёртки, которая является мостом между PHP кодом плагина и его использованием в JavaScript. При вызове этого метода передаются необходимые параметры из контекста бота, такие как информация о бизнесе, боте и пользователе (лиде). Особенности initializeJs: Передача контекстных данных: Включает в себя данные о бизнесе, боте, и пользователе. Инициализация состояния: Устанавливает начальное состояние для работы плагина.
checkPolicy	Метод checkPolicy выполняет проверку прав доступа и политик безопасности. Это критически важно, поскольку плагины PHP могут взаимодействовать с базой данных, с другими ботами и компонентами системы. Проверка обеспечивает, что плагин используется только в разрешенных и безопасных контекстах. Значимость checkPolicy: Проверка доступа: Удостоверяется, что запросы к плагину исходят из авторизованных источников. Защита от несанкционированного доступа: Предотвращает использование плагина вне предполагаемого бизнес-контекста.

Шаг 2. Использование PHP плагина

Теперь подключим созданный PHP скрипт в диалоговом сценарии нашего чат-бота. 

1. Создайте команды Вызвать JavaScript и разместите в ней следующий код.

// Подключаем PHP плагин. Эта команда загружает JavaScript обёртку для PHP плагина.
require("Common.PluginBoilerplate.PhpPlugin")

// Создаём переменную 'plugin', которая ссылается на экземпляр класса PHP плагина.
let plugin = CommonPluginBoilerplatePhpPlugin

// Вызываем метод 'itWorks()' у объекта плагина. 
let result = plugin.itWorks()

// Используем функцию 'debug' для вывода результата работы метода в отладочную консоль.
debug(result)

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

1. Подключение JS Плагина.

require("Common.PluginBoilerplate.PhpPlugin")

Common.PluginBoilerplate.PhpPlugin — это идентификатор JS скрипта из нашего плагина в системе Metabot.

Обратите внимание, это название JS скрипта, который связан с PHP скрипом! Это не название PHP скрипта!

Регистр важен!

Warning:Не используйте `let plugin = require("Common.PluginBoilerplate.PhpPlugin")` синтаксис для подключения PHP. Используйте точный синтаксис require без присваивания переменной.переменной, 

2. Обращение к PHP плагину.

После вызова require, вы можете обращаться к экземпляру PHP класса.

Платформа автоматически создает экземпляр. Название формируется путём объединения названий уровня доступа ('Common'), названия плагина ('PluginBoilerplate') и самого класса PHP ('PhpPlugin').

let result = CommonPluginBoilerplatePhpPlugin.itWorks()

Либо вы можете присвоить экземпляр в более короткую переменную:

let plugin = CommonPluginBoilerplatePhpPlugin
let result = plugin.itWorks()

3. Базовая заготовка PHP Plugin Boilerplate содержит метод itWorks(), который возвращает сообщение о корректной работе плагина.

Важно:

Создавайте скрипт типа "PHP Wrapper for V8" для интеграции с JS Low-Code. Укажите правильное namespace и название класса, соответствующее названию скрипта плагина.

Пример Кода PHP Плагина:

Шаг 3: Создание JavaScript Скрипта

Создайте JavaScript скрипт с тем же названием, что и PHP скрипт. Выберите созданную ранее PHP Plugin обёртку.

Подключение Плагина в Боте

Часть 1: Добавление Кода в Бота

Подключение JS Плагина:

Warning: Используйте точный синтаксис require без присваивания переменной.

Работа с Экземпляром Класса:

Если всё выполнено правильно, вы увидите сообщение "It works!" в вашем боте.

Отладка

Дополнение: Кэширование PHP плагинов и перезапуск очереди

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

Когда вы вносите изменения в PHP код плагина, для того чтобы они вступили в силу, необходимо перезапустить очередь на платформе Metabot. Это можно сделать следующим образом:

Переход в Настройки Платформы:

Откройте раздел настроек платформы Metabot. Это центральное место, где управляются основные параметры вашего бота и платформы в целом.

Отключение и Включение Cron Scheduler:

Найдите опцию или раздел, относящийся к Cron Scheduler (планировщику заданий). Сначала отключите Cron Scheduler. Это остановит текущую очередь заданий, включая выполнение задач связанных с PHP плагинами. Затем включите Cron Scheduler обратно. Это инициирует новую сессию очереди, при этом кэш PHP плагинов будет очищен и ваши изменения начнут действовать.

Отладка PHP плагина

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

Шаг 1: Проверка логов платформы

• Доступ к Логам: ЗапроситеОбычно упочти IT-администратороввсе ошибки можно получить через отладку бота(смотрите ниже). Однако, можно допустить ошибку, которая приведет к тому, что PHP на платформе не соберется и до уведомления в боте платформа просто не дойдет. В этом случае, запросите доступ к логам платформы Metabot. Обычно они находятся в /storage/logs. Логи могут предоставить ценную информацию о внутренних ошибках платформы и вашего плагина. 
• Чтение Логов: Ищите ошибки, связанные с вашим плагином, включая исключения, предупреждения и другие сообщения об ошибках.

Шаг 2: Режим отладки бота

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

Шаг 3: Проверка конфигурации плагина

• Проверка Класса ОбёрткиОбертки PHP: Убедитесь, что класс названобёртки PHP правильно испроектирован. содержитНазвание класса должно соответствовать названию скрипта обёртки.

Обязательные Методы: Проверьте, что в вашем классе реализованы методы initializeJs и checkPolicy. Эти методы критически важны для функционирования плагина.

Шаг 4: Проверка JavaScript интерфейса

• ПроверкаСоздание JS Интерфейса: Удостоверьтесь,Убедитесь, что JSJavaScript интерфейс для доступа к PHP обёртке создан корректно.
• ПроверкаСинтаксис require: Проверьте, правильно ли вы используете require идля Названияподключения Плагина:плагина. Убедитесь,Удостоверьтесь, что синтаксис require и названияназвание плагина и скрипта указаны верно.

Шаг 5: Проверка Названияинтеграции PHP Класса:и JavaScript

Название Класса PHP: Убедитесь,Проверьте, что название классаPHP PHP,класса, состоящеекоторое склеивается из трех компонентов,компонентов (уровень доступа, название плагина, название класса), указано верно. Тестирование Методов: Попробуйте вызвать различные методы вашего PHP класса через JavaScript, чтобы проверить их работоспособность.

Шаг 6: Обращение за помощью

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

Заключение

Поздравляем! Теперь вы умеете создавать PHP плагины для Metabot и интегрировать их в JS код бота. Это открывает новые возможности для расширения функционала платформы.

 

Про выключение очереди задач сказать!! PHP плагин кэшируется