Схема данных для сервера обновлений

Что такое сервер обновлений для программного обеспечения?

При разработке вашего программного обеспечения (если вы используете SW JProjects для каталога ПО) вы исправляете ошибки, добавляете новые функции: ваше приложение (компонент, плагин, модуль, библиотека) начинает жить своей жизнью. В течение жизненного цикла вашего приложения вы выпускаете новые версии. В мире разработки очень часто пользуются SemVer (статья Семантическое версионирование (semver) в Joomla и её расширениях). Вашим предыдущим версиям, работающим у ваших пользователей, нужно каким-то образом узнать о выходе новой версии, а затем получить ссылку на скачивание файлов и произвести обновление. Для этого на стороне разработчика поднимают сервер обновлений, который предоставляет программе всю необходимую информацию.

Видео

Также это видео на YouTube и RuTube. 

Собственный сервер обновлений для Joomla расширений

Исторически компонент SW JProejcts создавался как каталог расширений для Joomla. Согласно официальной документации Joomla (старая на docs.joomla.org, новая на manual.joomla.org) для обновления CMS со стороны разработчика нужно предоставить URL для информации:

• списка расширений (extensionset, не обязательно)
• для конкретного расширения (updates)
• для списка изменений (changelog, не обязательно)

По запросам на эти URL сервер обновлений отдаёт XML определенной для Joomla структуры. Joomla-компонент SW JProjects позволяет сформировать все нужные данные автоматически и ваши расширения на сайтах ваших клиентов всегда будут знать о выходе новых версий плагина или модуля. Нужные URL для вставки в XML-манифест вашего расширения вы узнаёте при создании и настройке проекта.

Сервер обновлений для НЕ расширения Joomla

Однако, что делать, если у вас не расширение Joomla, а любой другой тип файла или плагин для WordPress (или любой другой CMS) или программный модуль не для веб-разработки, а для Windows приложения? Или (например) вы производитель станков с ЧПУ и предлагаете клиентам периодически обновлять прошивки станков? В таком случае вам будет мешать специфичная для Joomla структура данных в сервере обновлений и вам захочется создать свою собственную, может быть более простую схему данных. Также вам может потребоваться другой формат, отличный от XML (JSON, SOAP или что-то другое). Для этих случаев вам может пригодится создание собственной схемы данных для сервера обновлений.

Схемы данных для сервера обновлений

Начиная с версии SW JProejects 2.5.0 вы можете создавать сервер обновлений не только для расширений Joomla, но и свои собственные.  Формирование структуры данных для сервера обновлений расширений Joomla вынесено в отдельный плагин. Вы можете создать свой собственный плагин и реализовать в нём нужную вам структуру данных, добавив или наоборот исключив отображаемые данные. Сервер обновлений в компоненте по-прежнему отображает информацию о списке проектов и их версиях, о конкретном проекте и его changelog.
Можно выбрать схему данных сервера обновлений глобально для всего компонента, выбрать другую схему данных для категории проектов, а так же выбрать схему в каждом проекте. 

Создание плагина схемы данных для сервера обновлений

Если вы разработчик - изучите плагин Joomlaserverscheme группы плагинов swjprojects, который входит в состав компонента. Этот плагин генерирует XML манифесты обновлений по спецификации Joomla. Также изучите плагин-образец на GitHub, который реализует ту же структуру с небольшими изменениями, но в формате JSON.

Ваш плагин расширяет не CMSPlugin, а Joomla\Component\SWJProjects\Administrator\Serverscheme\ServerschemePlugin (файл administrator/com_swjprojects/src/Serverscheme/ServerschemePlugin.php), который наследует CMSPLugin ядра Joomla. В нём вы можете посмотреть добавленные дополнительные методы, необходимые для работы плагина схемы данных.

Необходимые свойства класса

Основной файл плагина находится в папке src/Extension. В нём для вас важны свойства:

$mimeType

MIME тип данных, который будет установлен для ваших данных в заголовок сервера Content-Type. Его можно проверять на стороне программы-клиента, получающей обновления.

$charset

Кодировка отдаваемых данных.

$name

Имя вашей схемы данных, отображаемое в списках в интерфейса компонента.

$type

Уникальное "системное" имя вашей схемы данных. Именно оно сохраняется в параметрах компонента, категорий и проектов.

/**
 * @var string
 * @since 2.5.0
 */
protected string $mimeType = 'application/json';

/**
 * @var string
 * @since 2.5.0
 */
protected string $charset = 'utf-8';

/**
 * @var string
 * @since 2.5.0
 */
protected string $name = 'Custom Sample JSON';

/**
 * @var string
 * @since 2.5.0
 */
protected string $type = 'customsample';

Рекомендуем использовать в названии плагинов (в том числе названиях классов), а также свойства $type брендированные префиксы для максимальной унификации класса. Например, не "wordpressServerScheme", а "VendorWordpressServerScheme", где "Vendor" - это ваш бренд.

Метод renderOutput

Это метод, создающий структуру данных в нужном вам формате. Для удобства, логика создания структур данных для списка проектов (collection), конкретного проекта (updates) и списка изменений проекта (changelogs) разделена на 3 метода, которые вы реализуете в своём плагине самостоятельно. 

public function renderOutput(array $data): mixed
{
	switch ($this->getScheme()) {
		case 'updates':
			$output = $this->buildProjectUpdatesJson($data);
			break;
		case 'changelogs':
			$output = $this->buildChangelogsJson($data);
			break;
		case 'collection':
		default:
			$output = $this->buildCollectionJson($data);
			break;
	}

	return $output;
}

В своих методах вы можете формировать структуру так, как вам надо, использовать или не использовать данные из массива $data, добавлять свои собственные данные из базы данных или сторонних источников.

Созданные схемы данных кэшируются в кэше Joomla.