Как создать плагин для Joomla 4

Информация о материале: Родительская категория: CMS — движки сайтов; Категория: Joomla 4

Введение в создание собственного плагина для CMS Joomla 4
Создание установочного файла плагина для CMS Joomla 4
Создание плагина для CMS Joomla 4
Использование готовых плагинов. Как вызвать плагин в коде Joomla 4
1. Новый способ работы с плагинами в CMS Joomla 4
2. Как добиться максимальной совместимости с Joomla 3

Введение в создание собственного плагина для CMS Joomla 4

Структура плагина для Joomla! 1.5, 2.5 и 3.x были очень гибкими и мощными. Плагины могут использоваться не только для обработки событий, вызванных основным приложением и расширениями, но и для расширения имеющихся и расширения сторонних расширений. В Joomla 4.x была переписана большая часть системы диспетчеризации, чтобы еще больше повысить гибкость при изменении параметров, передаваемых в виде событий, одновременно повышая производительность плагинов.

Это руководство должно предоставить вам основы того, что нужно знать, чтобы разработать свой собственный плагин. Большинство плагинов состоят всего из одного файла кода, но для правильной установки кода плагина он должен быть упакован в установочный пакет с файлом-манифестом, который может быть обработан установщиком Joomla.

Создание файла-манифеста плагина для CMS Joomla 4

Как и все расширения в Joomla, плагины легко устанавливаются в виде zip-файла (.tar.gz также поддерживается), но должен быть включен правильно отформатированный XML-файл с манифестом устанавливаемого расширения.

В качестве примера приведем установочный файл XML для плагина поиска категорий:

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search" method="upgrade">
	<name>plg_search_categories</name>
	<author>Joomla! Project</author>
	<creationDate>November 2005</creationDate>
	<copyright>Copyright (C) 2005 - 2018 Open Source Matters. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
	<authorEmail>admin@joomla.org</authorEmail>
	<authorUrl>www.joomla.org</authorUrl>
	<version>3.0.0</version>
	<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
	<files>
		<filename plugin="categories">categories.php</filename>
	</files>
	<languages>
		<language tag="en-GB">en-GB.plg_search_categories.ini</language>
		<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
	</languages>
	<config>
		<fields name="params">

			<fieldset name="basic">
				<field
					name="search_limit"
					type="number"
					label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
					default="50"
				/>

				<field
					name="search_content"
					type="radio"
					label="JFIELD_PLG_SEARCH_ALL_LABEL"
					layout="joomla.form.field.radio.switcher"
					default="0"
					>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>

				<field
					name="search_archived"
					type="radio"
					label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
					layout="joomla.form.field.radio.switcher"
					default="0"
					>
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>
			</fieldset>

		</fields>
	</config>
</extension>

Как вы можете видеть, система похожа на другие установочные XML-файлы CMS Joomla. Вам нужно только обратить внимание на запись group="xxx" в теге <extension> и расширенную информацию в теге <filename>. Эта информация сообщает Joomla, в какую папку скопировать файл и в какую группу следует добавить плагин.

Если вы создаете плагин, который реагирует на существующие основные события, атрибут group="xxx" будет изменен, чтобы отразить имя существующей папки плагина для типа события, который вы хотите расширить. Например, group="authentication" или group="user". Полный список существующих категорий основных событий см. в разделе Плагин/События официальной документации Joomla (Прим.переводчика: Который по какой-то причине отсутствует и дополнительно смотреть фактически нечего). При создании нового плагина для реагирования на основные события важно, чтобы имя вашего плагина было уникальным и не конфликтовало ни с одним из других плагинов, которые также могут реагировать на основное событие, которое вы хотите обслуживать.

Если вы создаете плагин для реагирования на неосновные системные события, ваш выбор для тега group="xxx" должен отличаться от любой из существующих основных категорий.

СОВЕТ: Если вы добавите атрибут method="upgrade" в тег extension, этот плагин можно установить без удаления более ранней версии. Все существующие файлы будут перезаписаны, но старые файлы не будут удалены.

Создание плагина для CMS Joomla 4

В Joomla 4 вы также можете иметь код пространства имен в своем плагине - пожалуйста, прочитайте Соглашения о пространстве имен в Joomla 4. Обратите внимание, что основной файл плагина не имеет пространства имен, а только файлы, работающие с полями и любой другой вспомогательный код.

Объектно-ориентированный способ написания плагинов включает в себя написание подкласса CMSPlugin, базового класса, реализующего основные свойства плагинов. В ваших методах доступны следующие свойства:

$this->params: параметры, установленные для этого плагина администратором
$this->_name: имя плагина
$this->_type: группа (тип) плагина
$this->db: объект db (базы данных)
$this->app: объект приложения

СОВЕТ: Чтобы использовать $this->db и $this->app, CMSPlugin проверяет, существует ли свойство и не является оно приватным. Если требуется, чтобы объекты по умолчанию использовались, создайте не созданные свойства в классе плагина (т.е. protected $db; protected $app; в той же области, что и protected $autoloadLanguage = true;). Свойства не будут существовать, если они не будут созданы явно.

В следующем примере кода <PluginGroup> представляет группу (тип) плагина, а <PluginName> представляет его имя. Обратите внимание, что имена классов и функций в PHP не зависят от регистра.

Мы также реализуем здесь интерфейс SubscriberInterface, который является основным изменением по сравнению с Joomla 1.5-3.x. Вместо того, чтобы имя функции автоматически обнаруживалось и совпадало с именем события, это позволяет вам иметь пользовательские имена функций. Это позволяет нам сказать, какие плагины реализуют какие функции, и поскольку разбор общедоступных методов в PHP-коде происходит медленно, это значительно повышает производительность.

Примечание.Во всей серии Joomla 4 существует устаревший слой, который будет охватывать плагины, использующие старую стратегию именования, когда имена плагинов совпадают с именем события, когда SubscriberInterface не реализован.

<?php
// всем, кто не Joomla - кыш и брысь!
defined( '_JEXEC' ) or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Event\Event;
use Joomla\Event\SubscriberInterface;

class Plg<PluginGroup><PluginName> extends CMSPlugin implements SubscriberInterface
{
	/**
	 * Загрузите языковой файл при создании экземпляра
	 *
	 * @var    boolean
	 * @since  3.1
	 */
	protected $autoloadLanguage = true;

	/**
	 * Возвращает массив событий, которые будет прослушивать этот подписчик.
	 *
	 * @return  array
	 */
	public static function getSubscribedEvents(): array
	{
		return [
			'<EventName>' => 'myFunctionName',
		];
	}

	/**
	 * Метод плагина - это значение массива в методе getSubscribedEvents
	 * Затем плагин изменяет объект события (если он не является неизменяемым)
	 */
	 public function myFunctionName(Event $event)
	 {
		/*
		 * Код плагина тута!
		 * Вы можете получить доступ к параметрам через $this->params
		 */
		return true;
	}
}
?>

Использование готовых плагинов. Как вызвать плагин в коде Joomla 4

Если вы создаете плагин для нового, непрофильного события, не забудьте активировать его после установки в админке. Перед любой ссылкой на ваш новый плагин используйте команду JPluginHelper::importPlugin().

Теперь, когда вы создали свой плагин, вы, вероятно, захотите вызвать его в своем коде. Возможно, нет: ядро Joomla имеет ряд встроенных событий, на которые вы можете зарегистрировать свой код плагина (и в этом случае вы можете игнорировать этот раздел).

Новый способ работы с плагинами в CMS Joomla 4

Новый способ сделать это в Joomla 4 - это получение диспетчера и отправить именованное событие.

use Joomla\CMS\Event\AbstractEvent;
use Joomla\CMS\Factory;

$dispatcher = Factory::getApplication()->getDispatcher();

// Здесь мы создаем событие, однако, пока вы реализуете EventInterface, 
// вы можете создавать свои собственные пользовательские классы.
$event = AbstractEvent::create(
	'<EventName>',
	[
		'name' => $value,
	]
);

$eventResult = $dispatcher->dispatch('<EventName>', $event);

Если вы хотите разрешить пользователю изменять значения, вы можете использовать результат события и получить результаты из getResults. Вы можете делать так:

defined('_JEXEC') or die;

use BadMethodCallException;
use Joomla\CMS\Event\AbstractImmutableEvent;
use Joomla\CMS\Table\TableInterface;

/**
 * Класс события для события
 */
class MyCustomEvent extends AbstractImmutableEvent
{
	/**
	 * Constructor.
	 *
	 * @param   string  $name       Название события.
	 * @param   array   $arguments  Аргументы события.
	 *
	 * @throws  BadMethodCallException
	 */
	public function __construct($name, array $arguments = array())
	{
		if (!array_key_exists('myProperty', $arguments))
		{
			throw new BadMethodCallException("Аргумент 'MyProperty' требуется для события $name");
		}

		parent::__construct($name, $arguments);
	}

	/**
	 * Установщик для аргумента myProperty
	 *
	 * @param   mixed  $value  Значение для установки
	 *
	 * @return  mixed
	 *
	 * @throws  BadMethodCallException  если аргумент не имеет ожидаемого типа
	 */
	protected function setMyProperty($value)
	{
		if (!empty($value) && !is_object($value) && !is_array($value))
		{
			throw new BadMethodCallException("Аргумент 'src' события {$this->name} должен быть пустым, объектом или массивом");
		}

		return $value;
	}
}

Почему мы ввели этот класс имени над параметрами? Что ж, это облегчает введение пользовательских установщиков и геттеров для свойств - в настоящее время плагин может либо полностью изменить свойство по своему усмотрению - для компонентов нет никакого способа налагать какие-либо ограничения. Кроме того, это значительно облегчает разработчикам добавление и удаление параметров в событии без серьезных b/c проблем (поскольку теперь вы вызываете определенные методы и не подчиняетесь свойству, являющемуся 2-м аргументом вашей функции).

Как добиться максимальной совместимости с Joomla 3

Если вы хотите вызвать событие аналогично устаревшему J3.x JEventDispatcher, то используйте такой код:

$results = \Joomla\CMS\Factory::getApplication()->triggerEvent( '<EventName>', <ParameterArray> );

Важно отметить, что параметры должны быть в массиве. Сама функция плагина получит параметры в виде объекта события, если она реализует SubscriberInterface, и в виде отдельных значений, если это не так, но этот метод всегда будет возвращать массив, возвращаемый плагином.

Обратите внимание, что если КАКОЙ-ЛИБО плагин в группе не реализует интерфейс SubscriberInterface, то свойство result (как именованный параметр, так и результат плагина) используется как специальное свойство и не может быть использовано иначе.

Перевод с английского официальной документации CMS Joomla 4:
https://docs.joomla.org/J4.x:Creating_a_Plugin_for_Joomla

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)