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

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

Введение.

Это руководство предназначено для обучения разработчиков тому, как создать сервер обновлений для интеграции с системой обновлений, представленной в Joomla. Добавляя список сервера обновлений в манифест своего расширения, разработчики позволяют пользователям обновлять свои расширения через представление "Обновление" Менеджера расширений (см. для Joomla 3.x) всего в несколько кликов.

Определение сервера обновлений.

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

<extension>
 <...>
 <updateservers>
    <server type="collection">https://example.com/list.xml</server>
    <server type="extension" priority="2" name="Обновления моего расширения">http://example.com/extension.xml</server>
 </updateservers>
 </extension>

В теге <updateservers> можно определить несколько серверов. Если имеется более одного сервера обновлений, для каждого из них можно установить свой приоритет. Таким образом, можно контролировать порядок проверки серверов обновлений.

Типы серверов.

Коллекция (Collection).

Тип сервера "коллекция" позволяет разработчикам определить манифест расширения для получения обновлений из коллекции. Этот тип сервера может быть использован, если разработчик хочет определить все обновления своего расширения в одном файле (не рекомендуется) или если его расширение имеет несколько подрасширений, которые не распространяются и не обновляются одновременно (например, пакетное расширение). Приведенный ниже пример - это определение "коллекции", используемое программой обновления при обработке обновлений ядра Joomla:

 <extensionset name="Joomla Core" description="Joomla! Core">
    <extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="https://update.joomla.org/core/extension.xml"/>
 </extensionset>

Все определения должны быть определены между тегами <extensionset> в манифесте коллекции. Тег <extensionset> имеет два необязательных параметра: имя (name) и описание (description). Для каждого расширения, на которое ссылается данная коллекция, требуется отдельный тег <extension>. Тег <extension> имеет следующие параметры, все из которых необходимы для правильной обработки обновлений:

name - Имя расширения
element - Непереведенное имя расширения, т.е. mod_custom
type - Тип расширения (компонент (component), модуль (module), плагин (plugin) и т.д.)
version - Последняя версия расширения
detailsurl - URL-адрес XML-файла, содержащего отдельные определения обновлений для данного расширения.

Расширение (Extension).

Тип сервера "расширение" (extension) позволяет разработчикам определять манифест расширения для получения обновлений из манифеста одного расширения. Все манифесты коллекций в конечном итоге указывают на этот XML-файл. Все обновления в этом файле должны быть определены после тега <updates> в начале файла. Ниже приведен пример определения обновления для релиза Joomla 3.9.6:

<updates>
	<update>
		<name>Joomla! 3.9</name>
		<description>Joomla! 3.9 CMS</description>
		<element>joomla</element>
		<type>file</type>
		<version>3.9.6</version>
		<infourl title="Joomla!">https://www.joomla.org/announcements/release-news/5765-joomla-3-9-6-release.html</infourl>
		<downloads>
			<downloadurl type="full" format="zip">https://downloads.joomla.org/cms/joomla3/3-9-6/Joomla_3.9.6-Stable-Update_Package.zip</downloadurl>
			<downloadsource type="full" format="zip">https://github.com/joomla/joomla-cms/releases/download/3.9.6/Joomla_3.9.6-Stable-Update_Package.zip</downloadsource>
			<downloadsource type="full" format="zip">https://update.joomla.org/releases/3.9.6/Joomla_3.9.6-Stable-Update_Package.zip</downloadsource>
		</downloads>
		<tags>
			<tag>stable</tag>
		</tags>
		<sha256>05157273aadd3045564ee44373ea3643b437fa5321d17993a3119b38b04578e2</sha256>
		<sha384>ebd9b0666fbe84e20a420a4bcd6c10d306fc4dee4edbbe8e2133c85f0fb84e59be5a50aa97cb38c068b77f77f6bbc091</sha384>
		<sha512>a4c47644ceeaeec28944e0c74160203cf12037e0ea1439022e95055dfb6716de172667ce6d9164f12bb519d9cfcf1fdc728abea00f853b41debc7d2740f2b711</sha512>
		<maintainer>Joomla! Production Department</maintainer>
		<maintainerurl>https://www.joomla.org</maintainerurl>
		<section>STS</section>
		<targetplatform name="joomla" version="3.[789]" />
		<php_minimum>5.3.10</php_minimum>
</update>
</updates>

В следующем разделе описаны элементы одного объекта обновления.

name - Имя расширения, это имя будет отображаться в столбце Name (Название) в представлении Update Менеджера расширений (обязательное).
description - Краткое описание расширения (необязательно) - если вы решите использовать <![CDATA[]]>, двойные кавычки нарушат HTML-форматирование. Используйте одинарные кавычки с сущностями HTML.
element - Установленное имя расширения (обязательно). Для плагинов оно должно быть таким же, как значение атрибута plugin для основного файла в манифесте плагина. Для <filename plugin="pluginname">pluginname.php</filename>, значение элемента должно быть pluginname.
type - Тип расширения (компонент (component), модуль (module), плагин (plugin) и т.д.) (обязательное).
folder - Специфический тег для плагинов, который описывает тип обновляемого плагина (контент (content), система (system) и т.д.) (обязательно для плагинов)
client - Клиент расширения. Требуется для модулей и шаблонов начиная с версии 3.2.0. Возможные значения на данный момент - "сайт" (site) или "администратор" (administrator).
- Внимание! Плагины и внешние модули автоматически устанавливаются с клиентом site, но вам необходимо указать клиент в обновлении, иначе по умолчанию будет установлено значение administrator, и тогда найденное обновление не будет отображаться, так как не будет соответствовать ни одному расширению.
  - Компоненты автоматически устанавливаются с клиентом administrator, который в настоящее время используется по умолчанию.
- Предупреждение: Начиная с версии Joomla 4.0 допускается только строка. Использование чисел в качестве клиента было отменено в 2012 году и удалено в Joomla 4.0 (Замените 0 на "site" и 1 на "administrator").
- Предупреждение: Имя тега <client> для Joomla 2.5 и <client_id> для 1.6 и 1.7. Если вы используете <client_id> (а не <client>) site для Joomla 2.5, он будет проигнорирован.
version - Версия релиза (обязательно).
infourl - URL, на который можно направить пользователей, содержащий информацию об обновлении (необязательно) (В Joomla 2.5, если установлен, этот URL будет отображаться в представлении обновления)
downloads - Раздел, в котором перечислены все места загрузки
- downloadurl - URL для загрузки расширения; тег <downloadurl> имеет два обязательных параметра:
  - type - Тип пакета (full или upgrade)
  - format - Формат пакета (zip, tar и т.д.).
- downloadsource - Необязательный параметр. Начиная с Joomla 3.8.3. Альтернативный URL для загрузки расширения, если соединение с <downloadurl> не удалось. Допускается использование нескольких тегов <downloadsource>. Тег <downloadsource> имеет два обязательных параметра:
  - type - Тип пакета (full или upgrade).
  - format - Формат пакета (zip, tar и т.д.).
- Примечание - перед или после URL не должно быть новой строки; он должен быть в одной строке, иначе при запуске обновления возникнет ошибка Error connecting to the server: malformed.
changelogurl - ссылка на xml файл, содержащий журнал изменений. Joomla 4.0 и более поздние версии позволят показать кнопку для журнала изменений на странице обновления расширения. Более подробную информацию о том, как это использовать, можно найти здесь: Добавление журнала изменений в файл манифеста.
tags - Список тегов, относящихся к данной версии. Joomla 3.4 и более поздние версии используют его для определения уровня стабильности обновления. Действительными тегами являются:
- dev: версии для разработки, очень нестабильные и pre-alpha (например, ночные сборки)
- alpha (альфа): Альфа-качество программного обеспечения (нереализованные функции, ошибки)
- beta: Бета-качество (все функции реализованы, возможны ошибки, не дающие покоя, мелкие ошибки почти наверняка)
- rc: Программное обеспечение качества Release Candidate (нет ошибок, которые можно было бы показать, незначительные ошибки все еще могут присутствовать)
- stable: Программное обеспечение производственного качества Все остальные теги в настоящее время игнорируются. Если будет указано более одного тега, содержащего одно из вышеупомянутых ключевых слов стабильности, только последний тег будет принят во внимание. Если не указать ни одного тега, Joomla будет считать, что это стабильная версия.
maintainer - Имя разработчика расширения (аналогично тегу <author> в манифесте) (необязательно).
maintainerurl - Веб-сайт создателя расширения (аналогично тегу <authorUrl> в манифесте) (необязательно).
section - Необязательно (неизвестное использование).
targetplatform - тег для определения требований к платформе (начиная с Joomla 3.10 этот тег также используется для определения совместимости расширений для компонента Joomla Update), требует следующих элементовː
- name - Имя зависимости платформы; на момент написания этой статьи оно должно быть ТОЛЬКО "joomla"
- version - Версия Joomla, которую поддерживает расширение
- min_dev_level и max_dev_level - Эти атрибуты были добавлены в 3.0.1, чтобы позволить сделать выбор целевой платформы на основе уровня разработки ("z" в x.y.z). Они являются необязательными. Можно указать либо один, либо оба. Если они опущены, то сопоставляются все уровни разработки. Например, дальше приведено соответствие версий 4.0.0 и 4.0.1. <targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/>
  - Примечание:
    - Если расширение совместимо с Joomla 2.5 и/или 3.1, необходимо иметь отдельные определения <update> для каждой версии из-за того, как программа обновления проверяет версию, если указывается число. Однако, чтобы отображать расширение на всех версиях Joomla, которые поддерживают автоматическое обновление (и, таким образом, отметить как совместимое со всеми будущими невыпущенными версиями Joomla в Joomla Update) нужно добавить <targetplatform name="joomla" version=".*"/>.
    - Если необходимо, чтобы расширение отображалось на всех версиях Joomla 3.x, то вместо указания версии в теге version следует добавить <targetplatform name="joomla" version="3.[012345]"/>. Это отобразит обновление для всех версий 3.x от версии 3.0 до 3.5.
    - Если необходимо включить версию 3.10, можно использовать такой вариант: <targetplatform name="joomla" version="3.[012345]|10"/>.
    - Если необходимо показать обновления для всех версий 3.8.x и всех версий 3.10.x, можно использовать <targetplatform name="joomla" version="3.(8|10)"/>.
php_minimum - Начиная с версии 3.2.2, минимальная поддерживаемая версия PHP может быть указана в потоке обновлений. Если сервер не соответствует минимальной версии, пользователю выводится сообщение о том, что обновление доступно, но не может быть установлено из-за несоответствия техническим требованиям.
supported_databases - Начиная с версии 3.7, в состав обновления может быть включена проверка минимальной поддерживаемой базы данных + версии. Если сервер не соответствует минимуму, пользователю выводится сообщение о том, что обновление доступно, но не может быть установлено из-за неподдерживаемых технических требований. Примечание: Начиная с версии 3.9.12 есть специальный случай для mariadb, поэтому теперь можно установить определенную минимальную версию и для нее.
- Пример может выглядеть следующим образом: <supported_databases mysql="5.5.3" mariadb="10.1" postgresql="9.2" mssql="10.50.1600.1" />
sha256, sha384, sha512 - Необязательно. Начиная с Joomla 3.9.0 можно добавлять контрольные суммы файлов в данных формата хэшей. Имейте в виду, что в Joomla 3 только уведомление показывается в обновлениях, если контрольная сумма не верна. Это все. Обновление при этом не останавливается. В Joomla 4 обновления и установки будут остановлены, если предоставленная контрольная сумма не совпадает.

Для каждой версии выпускаемого расширения потребуется отдельное определение <update>.

Значения element, type, client_id и folder должны соответствовать значениям в таблице #_extensions.

Важно для плагинов: Плагины должны включать элементы <folder> и <client> для правильной работы.

Устранение неполадок.

Сценарий обновления SQL не выполняется во время обновления.

Если сценарий обновления SQL (например, в папке sql/updates/mysql) не выполняется в процессе обновления, это может быть связано с отсутствием номера версии в таблице #_schemas для данного расширения до обновления. Это значение определяется последним именем сценария в папке обновлений SQL. Если это значение пустое, никакие сценарии SQL не будут выполняться во время этого цикла обновления. Чтобы убедиться, что это значение установлено правильно, убедитесь, что в этой папке есть SQL-сценарий, имя которого является номером версии (например, 1.2.3.sql, если версия 1.2.3). Файл может быть пустым или просто содержать строку комментария SQL. Это должно быть сделано в старой версии - той, которая была до обновления. В качестве альтернативы можно добавить это значение в #_schemas с помощью SQL-запроса.

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

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