Документация Joomla 4: Облачное хранилище для Медиа Менеджера (GSoC 2017)

1. Введение
2. Создайте свой плагин файловой системы
   
   1. Конфигурация
   2. События плагина Filesystem
      
      1. onFileSystemGetAdapters()
      2. onFileSystemOAuthCallback()
3. Аутентификация и авторизация
   
   1. Подводные камни
4. Интерфейс работы с файлами с помощью вашего адаптера

Введение.

Joomla 4.x по умолчанию поставляется с облачными файловыми системами для медиаменеджера (Media Manager). С предыдущим API создание пользовательских файловых систем было сложной задачей. Благодаря новому API теперь легко создать пользовательскую файловую систему. Если вы хотите использовать облачный сервис с новым медиа-менеджером, рекомендуется использовать OAuth2.0.

В этой статье рассмотрены важные шаги по созданию собственного плагина файловой системы (File System Plugin) для расширения медиаменеджера. Прежде чем продолжить, пожалуйста, убедитесь, что у вас есть базовые знания о том, как разработать плагин для Joomla. Эта ссылка должна помочь.

Создайте свой плагин файловой системы.

Конфигурация.

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

Убедитесь, что ваш плагин содержит group="filesystem". Поэтому в вашем файле манифеста плагина [plugin-name].xml у вас должно быть:

<?xml version="1.0" encoding="utf-8"?>
<extension version="4.0" type="plugin" group="filesystem" method="upgrade">
	<name>plg_filesystem_myplugin</name>
	<author>Joomla! Project</author>
	<creationDate>April 2017</creationDate>
	<copyright>Copyright (C) 2005 - 2017 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>__DEPLOY_VERSION__</version>
	<description>Description</description>
	<files>
		<filename plugin="myplugin">myplugin.php</filename>
		<folder>SomeFolder</folder>
	</files>
	
	<config>
		<fields name="params">
			<fieldset name="basic">
				<field
					name="display_name"
					type="text"
					label="YOUR_LABEL"
					description="YOUR_DESCRIPTION"
					default="DEFAULT_VALUE"
				/>
			</fieldset>
		</fields>
	</config>
</extension>

Параметр display_name помогает Media Manager отображать имя вашей файловой системы (File System) в качестве корневого узла в Браузере файлов (File Browser). Любой адаптер, принадлежащий вашей файловой системе, будет отображаться как дочерний в корневом каталоге.

Укажите любые необходимые параметры, которые вам могут понадобиться, такие как App Secret, с соответствующими полями формы.

События плагина Filesystem.

• onFileSystemGetAdapters()
• onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event)

onFileSystemGetAdapters()

Любой плагин файловой системы должен содержать событие, называемое onFileSystemGetAdapters() для функциональности. Это событие должно возвращать массив Joomla\Component\Media\Administrator\Adapter\AdapterInterface при его вызове. Событие возникает при открытии медиаменеджера. Каждый AdapterInterface будет смонтирован под корневым узлом вашей файловой системы.

onFileSystemOAuthCallback()

Это событие запускается, когда вы использовали OAuthCallbackHandler медиаменеджера для процесса авторизации и аутентификации OAuth2.0, описанного ниже. Событие запускается только в запрошенном плагине. Так что нет необходимости проверять $context в вашем сценарии.

Пример использования события выглядит следующим образом:

public function onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event)
{
	// Ваш контекст
	$context = $event->getContext();

	// Получите входные данные
	$data = $event->getInput();

	// Ваш код находится здесь
	
	// Установите результат, который будет возвращен
	$result = [
		"action" => "control-panel"
	];
	
	// Передайте результат обратно в событие
	$event->setArgument('result', $result);
}

OAuthCallbackEvent содержит входные данные, перенаправленные в URI OAuthCallback медиаменеджера. $event->getInput() возвращает объект ввода.

$result определяет, как Joomla ведет себя после перенаправления на обратный вызов (callback). Существует несколько возможных решений:

• action
  
  • close: Закрывает окно, которое открывается с помощью JavaScript с помощью window.open()
  • redirect: Перенаправление на страницу, указанную в панели управления с redirect_uri
  • control-panel: Перенаправление на панель управления
  • media-manager: Перенаправление в медиаменеджер
• redirect_uri
  
  • Используется с действием перенаправления (обязательно)
• message
  
  • Сообщение должно отображаться после действия
• message_type
  
  • warning
  • notice
  • error
  • message (или установить пустым)

После настройки всего, установите аргумент $result $event, чтобы передать его обратно вызывающему скрипту.

Примером отображения сообщения пользователю может быть:

$result = [
	"action" => "media-manager",
	"message" => "Some message",
	"message-type" => "notice"
];

Это перенаправит на медиаменеджера и вызовет уведомление с текстом в сообщении (message).

Этот метод обычно можно использовать для получения кодов авторизации для процесса OAuth2.0. В случае какой-либо ошибки Joomla вернется в Панель управления и отобразит сообщение об ошибке.

Аутентификация и авторизация.

Joomla 4.x советует вам использовать OAuth2.0 для этого процесса. Это распространенный сценарий, в котором OAuth2.0 требует URL-адреса перенаправления (redirect url) для передачи данных аутентификации приложению. Обычно это делается обработчиком обратного вызова (callback handler). Для вашего плагина не нужно изобретать велосипед, вы можете использовать обработчик обратного вызова Media Manager для выполнения задачи.

Все, что вам нужно сделать, это установить URI перенаправления (Redirect URI) следующим образом в вашем OAuth2.0. Предоставьте и реализуйте onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event) в вашем плагине.

[site-name]/administrator/index.php?option=com_media&task=plugin.oauthcallback&plugin=[your-plugin-name]

В этом примере: [site-name]/administrator/index.php?option=com_media&task=plugin.oauthcallback&plugin=myplugin

Теперь, когда вы делаете перенаправление от своего провайдера, как только оно достигает указанного URL-адреса, контроллер для Media Manager гарантирует, что ваш плагин реализует onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event), прежде чем передавать ему какие-либо данные. Если нет, вы будете перенаправлены на панель управления с сообщением об ошибке.

Если вы внедрили все переданные входные данные, поставщик облачных услуг (Cloud Provider) будет включен в $event. Вы можете получить к ним доступ с помощью $event->getInput() и рассматривать его как обычный input в Joomla.

После получения input вы можете использовать их для получения сведений о вашей облачной службе, таких как Access Token, Refresh Token и т.д..

Если вы хотите различать несколько учетных записей, вы можете использовать для этого Session.

Примечание: Рекомендуется проверить токен CSRF, прежде чем продолжить запрос. Большинство облачных провайдеров поддерживают параметр state, который можно использовать для выполнения задачи.

Подводные камни.

При отправке вашего uri перенаправления поставщику облачных услуг необходимо указать urlencode(). Пожалуйста, используйте его, чтобы избежать неправильного поведения в вашем облаке.

Интерфейс работы с файлами с помощью вашего адаптера.

Для передачи ваших медиафайлов из медиаменеджера на сайт Joomla вам поможет интерфейс Joomla\Component\Media\Administrator\Adapter\AdapterInterface. Этот интерфейс содержит специальный метод, называемый getUrl($path).

• $path : Путь относится к вашему корню

Цель метода состоит в том, чтобы предоставить общедоступный абсолютный URL-адрес (Public Absolute URL) для файла, который вы просили вставить на сайт. Например, предположим, что ваш путь к файлу /path/to/me.png на облачном сервере. Теперь общедоступный URL-адрес может быть чем-то вроде mycloud.com/share/u/myusername/path/to/me.png. Как это подается, полностью зависит от вас. Когда пользователь хочет вставить URL-адрес, сгенерированный носителем, будет использоваться этот метод.

Более подробную информацию об Adapter Interface можно найти в administrator/componenents/com_media/Adapter/AdapterInterface.php

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

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