Подключение сторонних PHP библиотек в Joomla

PHP библиотеки удобны тем, что к ним можно обращаться из любого места Приложения: из плагина, модели компонента, модуля и т.д. В случае, если подобную задачу кто-то уже решал и оформил в виде библиотеки (и даже обновляет её) - имеет смысл подключить в свою Joomla эту библиотеку. Например, вам для разработки способа оплаты интернет-магазина нужна официальная библиотека платёжного агрегатора. Или вас устраивает официальный PHP SDK какой-нибудь CRM.

Joomla не поддерживает работу с Composer напрямую. Для того, чтобы использовать библиотеку в своей работе её нужно "обернуть" в расширение Joomla типа library и установить. В серьёзных проектах принят подход фиксации версий всех составляющих проекта: код проверен не один раз, протестирован и допущен до работы в проде.

Вы создаете пакет с вашей библиотекой, устанавливаете везде, где нужно. По мере выхода новых версий библиотеки - вы обновляете свою обёртку и получаете все преимущества работы с расширениями Joomla: обновление расширений стандартным способом, в том числе через CLI. Просмотр Changelog расширения в админке ДО обновления и т.д.

Joomla соответствует стандартам PSR, поэтому в этом плане с ней удобно работать. В ядро Joomla включены некоторые пакеты Symfony (console, string, var-dumper, yaml, error-handler и другие), поэтому, если вдруг вы захотите добавить ещё - они встанут как влитые и будут хорошо работать. Посмотреть что ещё стоит в Joomla кроме компонентов Symfony можно в libraries/vendor.

Ничего сложного. Файлы библиотеки как правило находятся в папке src. Рядом с этой папкой нужно создать XML-манифест расширения Joomla согласно документации (manual.joomla.org). Затем пакуем всё в zip-архив и готово! Можно устанавливать.

Если для работы библиотеки нужны свои таблицы в базе данных - при установке или обновлении нужно добавить нужные файлы c SQL-запросами. Поскольку Joomla 4+ работает с namespaces, важно указать для расширения этот namespace в XML-манифесте. Приведу сокращенный пример XML-манифеста для библиотеки Joomla.

<?xml version="1.0" encoding="UTF-8" ?> <extension type="library" method="upgrade"> <name>WebTolk AmoCRM library</name> <libraryname>Webtolk/Amocrm</libraryname> <version>1.2.1</version> ... <namespace path="src">Webtolk\Amocrm</namespace> <files> <folder>src</folder> <filename>amocrm.xml</filename> </files> </extension>

Тег <libraryname> означает, что папка src из нашего архива будет скопирована в JPATH_SITE/libraries/Webtolk/Amocrm. В секции мы указываем что из архива туда нужно положить. А <namespace path="src">Webtolk\Amocrm</namespace> говорит, что для папки src в JPATH_SITE/libraries/Webtolk/Amocrm необходимо зарегистрировать namespace Webtolk\Amocrm.

До Joomla 4.2.7 по сути тег из XML манифеста не работал. Поэтому нужно было в комплект библиотеки добавлять системный плагин, который бы регистрировал неймспейс на событии (Event Dispatcher) onAfterInitialise c помощью JLoader. Соответственно, собирать нужно было пакет из библиотеки и плагина. Начиная с Joomla 4.2.7 его починили и можно обходиться без плагина.
Пока что обновление библиотеки = переустановке. То есть расширение удаляется и устанавливается. Такое решение было принято где-то в недрах версий Joomla 3.x. Почему? - скрыто под горами PR. Нужно искать. Почему это важно? Потому что при установке любого расширения создается запись в "реестре" расширений - в базе данных в таблице #__extensions. В этой таблице есть 2 столбца типа TEXT - params и custom_data. А это, согласитесь, немалый объём данных. Если вы храните какие-то параметры библиотеки в базе данных с помощью Joomla\CMS\Helper\LibraryHelper, то нужно учитывать это поведение инсталлера и при обновлении библиотеки предварительно сохранять, а потом добавлять обратно сохранённые параметры в installer script расширения.

<?php use Joomla\CMS\Helper\LibraryHelper; use Joomla\CMS\Cache\Cache; /** * Function called before extension installation/update/removal procedure commences. * * @param string $type The type of change (install or discover_install, update, uninstall) * @param InstallerAdapter $adapter The adapter calling this method * * @return boolean True on success * * @since 1.0.0 */ public function preflight(string $type, InstallerAdapter $adapter): bool { if ($type == 'uninstall') { return true; } /** * * Joomla при обновлении расширений типа library по факту удаляет их (вместе с данными в базе), * а потом устанавливает заново. * Дабы избежать потерь данных библиотеки из базы пишем этот костыль. * * @see https://github.com/joomla/joomla-cms/issues/39360 * */ if ($type == 'update') { $lib_params = LibraryHelper::getParams('Webtolk/Amocrm'); $jconfig = $this->app->getConfig(); $options = array( 'defaultgroup' => 'wt_amo_crm_temp', 'caching' => true, 'cachebase' => $jconfig->get('cache_path'), 'storage' => $jconfig->get('cache_handler'), ); $cache = Cache::getInstance('', $options); $cache->store($lib_params, 'wt_amo_crm_temp'); } return true; }

А в методе postflight() соответственно помещаем спасённые параметры обратно с помощью LibraryHelper::saveParams('Webtolk/Amocrm', $lib_params);.

Чтобы библиотека работала - она должна быть включена в менеджере расширений (Меню - Система - Управление - Расширения).
Нередко для работы библиотеки нужны некие параметры (API ключи, токены и прочее), что должно указываться людьми в админке Joomla. Для этих целей удобно писать плагин (своего интерфейса для настройки параметров расширение типа library не имеет). Либо системный, либо своей кастомной группы - не важно. Внутри своей библиотеки получать параметры плагина довольно быстро можно так:

<?php use Joomla\CMS\Plugin\PluginHelper; use Joomla\Registry\Registry; if (PluginHelper::isEnabled('system', 'wt_amocrm')) { $plugin = PluginHelper::getPlugin('system', 'wt_amocrm'); $params = \json_decode($plugin->params); $param = $params->param; // ИЛИ можно использовать Joomla\Registry\Registry $params = new Registry($plugin->params); $param = $params->get('param', 'defatul value if empty'); }

В заключение хочу поделиться мнением участника Joomla-сообщества, разработчика - Артёма Васильева (@kernUSR на Хабре), которое он высказал в Joomla чате:

Ресурсы сообщества:

Telegram:

Подключение сторонних PHP библиотек в Joomla

Composer

Joomla, PSR, Symfony

Как обернуть PHP библиотеку в расширение Joomla?

Важные моменты!

Полезные ресурсы