Joomla 4/5 User Manual
Manual Index
Le déploiement d'un serveur de mise à jour
Joomla! 2.5 Joomla! 3.x Joomla! 4.x
Introduction¶
Ce didacticiel a pour vocation d'aider les développeurs à créer un serveur de mise à jour pour une intégration avec le système de mise à jour implémenté dans Joomla. En ajoutant une liste de serveurs de mise à jour dans le fichier manifest de leurs extensions, les développeurs vont permettre aux utilisateurs de mettre à jour leurs extensions via le gestionnaire des mises à jour des extensions (voir l'écran d'aide Mise à Jour de Joomla 3.x) en un clic seulement.
Définition d'un serveur de mise à jour¶
Pour pouvoir utiliser cette fonction, un serveur de mise à jour doit être défini dans le fichier "manifest" de votre extension. Cette définition peut être utilisée pour toutes les extensions compatibles avec les versions 2.5 et plus récentes de Joomla! mais n'est pas disponible pour les templates. Vous pouvez utiliser deux options pour votre type de serveur : collection ou extension. Celles-ci seront expliquées en détail par la suite. Ce code doit être ajouté au fichier "manifest" de l'extension, à l'intérieur de la balise pour l'élément extension. Le serveur de mise à jour est définie comme suit pour chaque type :
<extension>
<...>
<updateservers>
<server type="collection">https://example.com/list.xml</server>
<server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
</updateservers>
</extension>
Plusieurs serveurs peuvent être définis à l'aide de balises . Si vous disposez de plusieurs serveurs de mise à jour, vous pouvez indiquer une priorité différente pour chacun d'eux. De cette manière, vous contrôlez l'ordre dans lequel les serveurs de mise à jour vont être utilisés.
Types de serveur¶
Collection¶
Le serveur de type "collection"
permet aux développeurs de définir un
fichier "manifest" pour une extension afin de charger des mises à jour à
partir d'une collection. Ce type de serveur peut être utilisé par les
développeurs qui souhaitent définir les mises à jour pour leurs
extensions dans un seul fichier (non recommandé) ou si leurs extensions
disposent de plusieurs sous-extensions qui ne sont pas distribués ou
mises à jour toutes en même temps (comme un type pack d'extension).
L'exemple ci-dessous est la définition de "collection"
utilisée par le
programme de mise à jour du noyau 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>
Toutes les définitions doivent être présentes entre les balises dans
votre "manifest" collection. La balise peut avoir deux paramètres
facultatifs : name
et description
. Pour chaque extension que cette
collection références, une balise est nécessaire. La balise présente les
paramètres suivants, qui sont tous requis pour que le processus de mise
à jour se déroule correctement :
- name (nom) - le nom de l'extension
- element (élément) - le nom non traduit de l'extension c'est à dire mod_custom
- type - le type d'extension (composant, module, plugin, etc.)
- version - la dernière version de l'extension
- detailsurl - L'URL du fichier XML qui contient les définitions indivielles de mises à jour de l'extension
Extensions¶
Le type de serveur d'"extension"
permet aux développeurs de définir un
manifest d'extension pour obtenir les mises à jour depuis un seul
manifest d'extension. Tous les manifests de collection pointent
finalement vers ce fichier XML. Toutes les mises à jour dans ce fichier
doivent être définies après une balise au début du fichier. L'exemple
ci-dessous est la définition de la mise à jour pour la version 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>
La section suivante décrit les éléments d'une mise à jour unique.
- name - le nom de l'extension, ce nom apparaîtra dans la colonne "Nom" de la vue de mise à jour du gestionnaire d'extension (obligatoire).
- description – une courte description de l'extension (facultatif) — si vous choisissez d'utiliser , les guillemets doubles vont briser le formatage HTML. Utilisez des guillemets simples avec vos entités HTML.
-
element - le nom de l'extension installée (obligatoire). Pour les
plugins, ce doit être le même que la valeur de l'attribut du plugin
dans le manifest du fichier principal du plugin. Pour
nomduplugin.php
, la valeur de l'élément doit être nomduplugin. - type - le type de l'extension (composant, module, plugin, etc.) (obligatoire).
- folder (dossier) - spécifique aux plugins, cette balise décrit le type du plugin mis à jour (contenu, système, etc.) (obligatoire pour les plugins).
-
client – Le client de l'extension. Requis pour les modules et
modèles de site depuis la version 3.2.0. – Les valeurs possibles
actuellement sont "site" ou "administrator". Attention ! Les
plugins et les modules du site public sont automatiquement installés
avec le client à 0 (site), mais vous devez tout de même indiquer le
client dans une mise à jour ou il sera mis par défaut à 1
(administrator) et, du coup, la mise à jour trouvée ne sera pas
affichée parce qu'elle ne correspondra à aucune extension. Les
composants sont automatiquement installés avec un client à
"administrator", ce qui est la valeur actuelle par défaut.
- Attention : Concernant Joomla! 4.0 seule une chaîne de caractère est autorisée. L'utilisation de nombres pour le champ client a été déprécié en 2012 et supprimé de Joomla! 4.0 (remplacer "0" par "site" et "1" par "administrator").
- Attention : le nom de la balise est pour Joomla! 2.5 et pour les versions 1.6 et 1.7. Si vous utilisez plutôt que de sur un site de 2.5, la balise sera ignorée.
- version - les références de la version (obligatoire)
- infourl - l'URL pour diriger les utilisateurs vers des informations complémentaires concernant la mise à jour (facultatif).
-
downloads - la section qui liste tous les emplacements pour le
téléchargement.
-
downloadurl - l'URL à partir de laquelle il est possible de
télécharger l'extension. La balise doit contenir deux paramètres
obligatoires :
- type - le type du package (complète ou mise à jour).
- format - Le format de l'archive (zip, tar, etc.).
-
downloadsource - Facultatif. Depuis la version Joomlaǃ 3.8.3.,
une URL alternative depuis laquelle il est possible de télécharger
l'extension lorsque la connexion depuis échoue. Plusieurs balises
sont autorisées. La balise nécessite de renseigner deux paramètres
obligatoires :
- type - Le type du package (complète ou mise à jour).
- format - Le format de l'archive (zip, tar, etc.).
- NB - il ne doit pas y avoir de saut à la ligne avant ou après l'URL ; tout doit être écrit sur une seule est même ligne où vous aurez une erreur de connexion au serveur : requête malformée quand la mise à jour sera exécutée
-
downloadurl - l'URL à partir de laquelle il est possible de
télécharger l'extension. La balise doit contenir deux paramètres
obligatoires :
- changelogurl - Un lien vers un fichier xml du journal des modifications. Les versions Joomlaǃ 4.0 et ultérieures vous permettront d'afficher un bouton vers le journal des modifications dans la page de mise à jour de l'extension. Pour plus de détails pour utiliser cela, consulter : Ajouter un journal de modifications à votre fichier manifest
-
tags - Une liste de mots clés pertinents pour cette version. Les
versions Joomla! 3.4 et suivantes utilisent cela pour déterminer le
niveau de stabilité de la mise à jour. Les valeurs des tags valides
sont :
- dev : versions de développement, très instables et pré-alpha (par exemple, les nightly builds).
- alpha : Niveau de qualité de logiciel Alpha (fonctionnalités non implémentées, bogues bloquants)
- beta : Niveau de qualité de logiciel Beta (toutes les fonctionnalités sont implémentées, possibilité de bogues bloquants, certitude de présence de bogues mineurs)
- rc : Niveau de qualité de logiciel Release Candidate (plus de bogues bloquants, des bogues mineurs peuvent encore subsister)
- stable : Niveau de qualité de logiciel Production. Tous les autres tags sont actuellement ignorés. Si vous fournissez plus d'un tag contenant l'un des mots clés de stabilité du code ci-dessus, seul le DERNIER tag sera pris en compte. Si aucun tag n'est fourni, Joomla! va considérer que la version est stable.
- maintainer – Le nom de la personne qui maintient l'extension (similaire à la balise dans le manifest) (optionnel)
- maintainerurl – Le site web de la personne qui maintient l'extension (similaire à la balise du manifest) (optionnel)
- section – Facultatif (utilisation inconnue)
-
targetplatform – Une balise pour définir les exigences de la
plateforme (depuis la version
ceci est également utilisé pour détecter la compatibilité des extensions pour le composant de mise à jour de Joomla), et qui a besoin des éléments suivant ː
- name – Le nom de la dépendance de la plateforme ; actuellement, SEUL "joomla" est supporté
- version– La version de Joomla! prenant en charge l'extension.
-
min_dev_level et max_dev_level – Ces attributs ont été
ajoutés en 3.0.1 pour permettre de sélectionner une plateforme cible
pour un certain niveau de développement ("z" dans x.y.z). Ils sont
optionnels. Vous pouvez en spécifier un seul ou les deux. S'il sont
omis, les niveaux de développements correspondent tous. Par exemple,
la balise suivante inclut les versions 4.0.0 et 4.0.1.
-
Note : Si votre extension est compatible Joomla! 2.5 et/ou
3.1, vous devrez avoir des définitions séparées de pour chaque
version à cause de la manière dans le moteur de mise à jour va
vérifier la version, si vous spécifiez une valeur. Cependant, pour
montrer votre extension sur toutes les versions Joomla qui
supportent les mises à jour automatiques (et de fait indique la
compatibilité avec toutes les versions futures de Joomla dans le
système de mise à jour de Joomla), ajoutez . Si vous voulez que la
mise à jour de votre extension s'affiche pour toutes les versions
, alors plutôt que de spécifier une version dans le tag de version, ajoutez . Ceci va montrer la mise à jour dans toutes les versions 3.x de 3.0 à 3.5. Si vous voulez inclure la version 3.10, vous pouvez utiliser un
|
comme ceci : . Si vous voulez montrer les mises à jour pour toutes les versions 3.8.x et toutes les versions 3.10.x, vous pouvez utiliser
-
Note : Si votre extension est compatible Joomla! 2.5 et/ou
3.1, vous devrez avoir des définitions séparées de pour chaque
version à cause de la manière dans le moteur de mise à jour va
vérifier la version, si vous spécifiez une valeur. Cependant, pour
montrer votre extension sur toutes les versions Joomla qui
supportent les mises à jour automatiques (et de fait indique la
compatibilité avec toutes les versions futures de Joomla dans le
système de mise à jour de Joomla), ajoutez . Si vous voulez que la
mise à jour de votre extension s'affiche pour toutes les versions
- php_minimum – Depuis la version 3.2.2, une version minimale PHP supportée peut être fournie dans le flux de mise à jour. Si le serveur n'a pas cette version minimale, un message indique à l'utilisateur que la mise à jour est accessible mais ne peut pas être installée du fait d'une exigence non couverte.
-
supported_databases – Depuis la version 3.7, une vérification de
la base de données et de sa version minimale supportée peut être
fournie dans le flux de mise à jour. Lorsque le serveur n'a pas cette
version minimale, un message indique à l'utilisateur que la mise à
jour est accessible mais ne peut pas être installée du fait d'une
exigence non couverte. A noter :
Comme pour la version 3.9.12 il
y a également un cas spécial pour mariadb et ainsi vous pouvez
indiquer une version spécifique minimale pour cela aussi.
- Un exemple pourrait être :
- sha256, sha384, sha512 – Facultatif. Depuis la version Joomlaǃ 3.9.0, vous pouvez ajouter des checksums sur vos fichiers pour ces formats hash. Notez que dans Joomlaǃ 3, seule une information est présente dans mises à jour si un checksum n'est pas correct. C'est tout. La mise à jour ne s'arrête pas pour autant. Pour les mises à jour avec Joomlaǃ 4 et les installations, si un checksum fourni n'est pas correct, alors la mise à jour s'arrêtera.
La définition d'un séparé sera requis pour chaque version de l'extension que vous mettez à disposition.
Les valeurs de element, type, client_id et folder doivent correspondre à ceux de la table #__extensions.
Important pour les plugins : les plugins doivent intégrer les éléments et pour fonctionner correctement.
Résolution de problèmes¶
- Le script de mise à jour SQL n'est pas exécuté durant une mise à jour.
Si le script de mise à jour SQL (par exemple, dans le répertoire
sql/updates/mysql
) n'est pas exécuté durant le processus de mise à
jour, cela peut être dû au fait qu'il n'y avait pas de numéro de version
dans la table #__schemas
de cette extension avant la mise à jour.
Cette valeur est déterminée par le dernier nom de script dans le
répertoire de mises à jour SQL. Si cette valeur est vierge, aucun script
SQL ne sera exécuté durant le cycle de mise à jour. Pour vous assurer
que cette valeur est correctement spécifiée, assurez vous que vous avez
un script SQL dans ce répertoire dont le nom est le numéro de version
(par exemple, 1.2.3.sql si la version est 1.2.3). Le fichier peut être
vide ou avoir juste une ligne de commentaire SQL. Ceci doit avoir été
fait dans une version antérieure — celle avant la mise à jour. Comme
alternative, vous pouvez ajouter cette valeur dans la table #__schemas
en utilisant une requête SQL.