When developing websites or extensions for Joomla, sometimes tasks arise that have already been solved by someone. In the development world, such solutions are designed as libraries - sets of files and classes that make it possible to simply plug them into your script and use code written and well-tested by other developers. These can be php libraries for image processing, working with PDF, connecting to third-party services via the REST API, and much, much more.

PHP libraries are convenient because they can be accessed from anywhere in the Application: from a plugin, component model, module, etc. This article explains how to properly connect a third-party PHP SDK to your project.

Composer

Joomla does not support working with Composer directly. In order to use the library in your work, you need to "wrap" it in a Joomla extension type library and install it. In serious projects, the approach of fixing versions of all components of the project is adopted: the code has been checked more than once, tested and allowed to work in the production.

You create a package with your library, install it wherever you need it. As new versions of the library are released, you update your wrapper and get all the advantages of working with Joomla extensions: updating extensions in the standard way, including through the CLI. View the Changelog of the extension in the admin area BEFORE updating, etc.

Joomla, PSR, Symfony

Joomla complies with PSR standards, so it is convenient to work with it in this regard. Some Symfony packages are included in the Joomla core (console, string, vardumper, yaml, error-handler and others), so if you suddenly want to add more, they will fit in and work well. You can see what else is worth in Joomla besides Symfony components in libraries/vendor.

How to wrap a 3rd-party PHP library in a Joomla extension?

Nothing complicated. The library files are usually located in the src folder. Next to this folder, you need to create an XML manifest of the Joomla extension according to the documentation (manual.joomla.org). Then we pack everything into a zip archive and that's it! It can be installed.

If you need your own tables in the database for the library to work, you need to add the necessary files with SQL queries during installation or update. Since Joomla 4+ works with namespaces, it is important to specify this namespace in the XML manifest for the extension. Here is an abbreviated example of an XML manifest for the Joomla library.

<?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>

The <libraryname> tag means that the src folder from our archive will be copied to JPATH_SITE/libraries/Webtolk/Amocrm. In the <files> section, we indicate what needs to be filled in from the archive. And <namespace path="src">Webtolk\Amocrm</namespace> says that the namespace Webtolk\Amocrm must be registered for the src folder in JPATH_SITE/libraries/Webtolk/Amocrm.

Important notes!

Before Joomla 4.2.7, in fact, the tag <namespace> from the XML manifest did not work. Therefore, it was necessary to add a system plugin to the library package that would register the namespace on the onAfterInitialize event (Event Dispatcher) using JLoader class. Accordingly, it was necessary to build a package from the library and the plugin. Starting with Joomla 4.2.7, it has been fixed and you can do without the plugin.

So far, updating the library = reinstalling. That is, the extension is removed and installed. This decision was made somewhere in the depths of the versions of Joomla 3.x. Why? - hidden under the mountains of PR. Additional searches are needed to find out the reasons for making such a decision. Why is this important? Because when installing any extension, an entry is created in the "registry" of extensions - in the database in the #__extensions table. This table has 2 columns of type TEXT - params and custom_data. And this, you must admit, is a considerable amount of data. If you store some library parameters in a database using Joomla\CMS\Helper\LibraryHelper, then you need to take this behavior of the installer into account and pre-save and then add the saved parameters back to the extension's installer script when updating the library.

<?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 when updating extensions of the library type, it actually deletes them (along with the data in the database),
     *  and then installs it again.
     *  In order to avoid losing library data from the database, we are writing this crutch.
     *
     * @see https://github.com/joomla/joomla-cms/issues/39360
     *
     */

    if ($type == 'update')
    {
        $lib_params = LibraryHelper::getParams('Webtolk/Amocrm');
        $jconfig    = $this->app->getConfig();
        $options    = [
            '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;

}

And in the postflight() method accordingly, we put the saved parameters back using LibraryHelper::saveParams('Webtolk/Amocrm', $lib_params);. See the Install Process and Script Files article in the Joomla docs.

For the library to work, it must be enabled in the extension manager (Menu - System - Management - Extensions).

Often, certain parameters (API keys, tokens, etc.) are needed for the library to work, which must be specified by people in the Joomla admin area. For these purposes, it is convenient to write a plugin (an extension type library does not have its own interface for configuring parameters). Either the system one or your own custom group doesn't matter. Inside your library, you can get plugin parameters pretty quickly like this:

<?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;
      // OR you can use Joomla\Registry\Registry
      $params = new Registry($plugin->params);
      $param = $params->get('param', 'defatul value if empty');
   }

This article was originally published in Russian on habr.com and the author's website. Then translated into English and published on dev.to.