PHP плагины могут быть только общими и добавляются только администраторами платформы из-за доступа к базе данных и другим ботам. Это мера предосторожности для обеспечения безопасности.
1\. Создайте новый плагин, если необходимо. В этом уроке мы назвали плагин PluginBoilerplate. [](https://docs.metabot24.ru/uploads/images/gallery/2024-02/AoA3OqeFiQi4NTyR-image.png) 2\. В плагине создайте скрипт с расширением PHP (ОБЕРТКА ДЛЯ V8). [](https://docs.metabot24.ru/uploads/images/gallery/2024-02/WVimXy8ZLTW1aOig-image.png)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 _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(); } // Проверка на наличие и корректность объекта бота, который запустил плагин // Используется, например, когда: // нужно запустить скрипт в одном боте (_runFromBot), // а получить тикет/др. сущности по другому боту (_bot). // _bot и _runFromBot запоминают, что к чему принадлежит и откуда получено. if (empty($this->_runFromBot) || !($this->_runFromBot instanceof Bot)) { throw new UnauthotizedV8Exception(); } // Проверка на на принадлежность бота, указанному бизнесу if (!empty($this->_bot) && $this->_bot->business_id != $this->_business->id) { throw new UnauthotizedV8Exception(); } // Здесь могут быть добавлены дополнительные условия безопасности } // Метод для проверки работоспособности плагина public function itWorks() { $this->checkPolicy(); return "Plugin works!"; // Возвращаем подтверждающее сообщение } } ```Создание PHP плагинов - ответственный процесс, требующий строгого контроля безопасности. Подробнее о `checkPolicy()` смотрите ниже.
4\. Важно правильно указать `namespace`, иначе ваш плагин не подключится. Замените ИмяПлагина на название вашего плагина. В нашем примере это PluginBoilerplate. ```PHP namespace Plugins\Dynamic\Common\ИмяПлагина\V8Wrapper; ```Указывайте имя плагина с учетом регистра. PluginBoilerplate и pluginBoilerplate это разные плагины!
5\. Важно правильно указать имя класса в соответствии с названием скрипта плагина. Вместо ИмяКласса укажите название вашего класса. ```PHP class ИмяКласса extends ScriptBase { ``` [](https://docs.metabot24.ru/uploads/images/gallery/2024-02/hYHT8IrkuIgKRKm9-image.png)Название класса должно совпадать с названием скрипта PHP обертки! В противном случае ваш плагин не будет работать!
6\. Создайте JS скрипт в плагине. Выберите созданную ранее PHP обертку. Название может быть любое, но мы рекомендуем JS скрипт называть также как PHP скрипт, это поможет вам избежать путаницы в дальнейшем. [](https://docs.metabot24.ru/uploads/images/gallery/2024-02/0mI9O18m0ltWNWgf-image.png) В итоге, у вас должен получиться плагин с двумя скриптами: [](https://docs.metabot24.ru/uploads/images/gallery/2024-02/SiToshkrv4w7s7Y2-image.png) ##### Дополнение: Важность методов `initializeJs` и `checkPolicy` В создании PHP плагинов для Metabot, особое внимание следует уделить методам `initializeJs` и `checkPolicy`. Эти методы играют ключевую роль в обеспечении безопасности и правильной инициализации плагина. Правильная реализация методов `initializeJs` и `checkPolicy` гарантирует, что ваш PHP плагин будет не только функциональным, но и безопасным для использования в рамках платформы Metabot. Это обеспечит стабильность и надежность ваших решений на платформе.| **Метод** | **Описание** |
| **`initializeJs`** | Этот метод отвечает за инициализацию JavaScript обёртки, которая является мостом между PHP кодом плагина и его использованием в JavaScript. При вызове этого метода передаются необходимые параметры из контекста бота, такие как информация о бизнесе, боте и пользователе (лиде). **Особенности `initializeJs`:** - **Передача контекстных данных:** Включает в себя данные о бизнесе, боте, и пользователе. - **Инициализация состояния:** Устанавливает начальное состояние для работы плагина. |
| **`checkPolicy`** | Метод `checkPolicy` выполняет проверку прав доступа и политик безопасности. Это критически важно, поскольку плагины PHP могут взаимодействовать с базой данных, с другими ботами и компонентами системы. Проверка обеспечивает, что плагин используется только в разрешенных и безопасных контекстах. **Значимость `checkPolicy`:** - **Проверка доступа:** Удостоверяется, что запросы к плагину исходят из авторизованных источников. - **Защита от несанкционированного доступа**: Предотвращает использование плагина вне предполагаемого бизнес-контекста. |
Обратите внимание, это название JS скрипта, который связан с PHP скрипом! Это не название PHP скрипта!
Регистр важен!
Не используйте `let plugin = require("Common.PluginBoilerplate.PhpPlugin")` синтаксис для подключения PHP. Используйте точный синтаксис `require` без присваивания переменной,
2\. Обращение к PHP плагину. После вызова require, вы можете обращаться к экземпляру PHP класса. Платформа автоматически создает экземпляр. Название формируется путём объединения названий уровня доступа ('Common'), названия плагина ('PluginBoilerplate') и самого класса PHP ('PhpPlugin'). ```JavaScript let result = CommonPluginBoilerplatePhpPlugin.itWorks() ``` Либо вы можете присвоить экземпляр в более короткую переменную: ```JavaScript let plugin = CommonPluginBoilerplatePhpPlugin let result = plugin.itWorks() ``` 3\. Базовая заготовка PHP Plugin Boilerplate содержит метод `itWorks()`, который возвращает сообщение о корректной работе плагина. Если всё выполнено правильно, вы увидите сообщение "It works!" в вашем боте. ##### Дополнение: Кэширование PHP плагинов и перезапуск очереди При работе с PHP плагинами на платформе Metabot важно помнить о механизме кэширования, который может влиять на процесс разработки и отладки. PHP плагины кэшируются на уровне языка, что означает, что изменения, внесенные в код плагина, не будут немедленно отражены в работе бота. Когда вы вносите изменения в PHP код плагина, для того чтобы они вступили в силу, необходимо перезапустить очередь на платформе Metabot. Это можно сделать следующим образом: 1. **Переход в Настройки Платформы:** - Откройте раздел настроек платформы Metabot. Это центральное место, где управляются основные параметры вашего бота и платформы в целом. 2. **Отключение и Включение Cron Scheduler:** - Найдите опцию или раздел, относящийся к Cron Scheduler (планировщику заданий). - Сначала отключите Cron Scheduler. Это остановит текущую очередь заданий, включая выполнение задач связанных с PHP плагинами. - Затем включите Cron Scheduler обратно. Это инициирует новую сессию очереди, при этом кэш PHP плагинов будет очищен и ваши изменения начнут действовать. #### 3. Отладка PHP плагина Отладка - это важный элемент разработки, который требует терпения и внимания к деталям. Следуйте этим шагам, чтобы эффективно находить и устранять проблемы с вашими PHP плагинами в Metabot. ##### 1: Проверка логов платформы - **Доступ к Логам:** Обычно почти все ошибки можно получить через отладку бота(смотрите ниже). Однако, можно допустить ошибку, которая приведет к тому, что PHP на платформе не соберется и до уведомления в боте платформа просто не дойдет. В этом случае, запросите доступ к логам платформы Metabot. Обычно они находятся в `/storage/logs`. Логи могут предоставить ценную информацию о внутренних ошибках платформы и вашего плагина. - **Чтение Логов:** Ищите ошибки, связанные с вашим плагином, включая исключения, предупреждения и другие сообщения об ошибках. ##### 2: Режим отладки бота - **Включение Режима Отладки:** Включите режим отладки в настройках вашего бота. Это позволит получать подробные сообщения об ошибках. - **Отладка на Уровне Лида:** Для конкретных лидов, активируйте высший уровень отладки. Это обеспечит детальную информацию об ошибках, возникающих при взаимодействии с вашим плагином. ##### 3: Проверка конфигурации плагина - **Проверка Класса Обертки PHP:** Убедитесь, что класс обёртки PHP правильно спроектирован. Название класса должно соответствовать названию скрипта обёртки. - **Обязательные Методы:** Проверьте, что в вашем классе реализованы методы `initializeJs` и `checkPolicy`. Эти методы критически важны для функционирования плагина. ##### 4: Проверка JavaScript интерфейса - **Создание JS Интерфейса:** Убедитесь, что JavaScript интерфейс для доступа к PHP обёртке создан корректно. - **Синтаксис `require`:** Проверьте, правильно ли вы используете `require` для подключения плагина. Удостоверьтесь, что название плагина и скрипта указаны верно. ##### 5: Проверка интеграции PHP и JavaScript - **Название Класса PHP:** Проверьте, что название PHP класса, которое склеивается из трех компонентов (уровень доступа, название плагина, название класса), указано верно. - **Тестирование Методов:** Попробуйте вызвать различные методы вашего PHP класса через JavaScript, чтобы проверить их работоспособность. ##### 6: Обращение за помощью - **Сообщество и Поддержка:** Если вы столкнулись с трудноуловимыми или сложными проблемами, не стесняйтесь обращаться за помощью к сообществу Metabot или в службу поддержки. - **Документация:** Периодически обращайтесь к официальной документации Metabot, где могут быть ответы на ваши вопросы. #### Заключение Поздравляем! Теперь вы умеете создавать PHP плагины для Metabot и интегрировать их в JS код бота. Это открывает новые возможности для расширения функционала платформы.