Planification et mise à niveau de Joomla 4 vers 5, étape par étape

Introduction

Bonne nouvelle pour le passage de Joomla 4.4.x à 5.x, il s'agit d'une mise à niveau, pas d'une migration. Pourquoi ? Pour deux raisons principales :

1. Les extensions Joomla 4 (J4) qui ont supprimé toutes les dépréciations de code et utilisent un code Joomla à jour fonctionneront dans Joomla 5 (J5)
2. La plupart des autres fonctionneront avec le nouveau comportement - plugin de compatibilité ascendante activé

Cette documentation reflète le processus simplifié en combinant la planification et les étapes détaillées dans un seul document. Néanmoins, vous aurez besoin de certaines compétences. Veuillez consulter l'auto-évaluation pour déterminer si vous devez ou non entreprendre la mise à niveau vous-même.

Planification du passage de 4.4.x à 5.x

Hébergement / Spécification technique

1. Déterminer si votre environnement d'hébergement répond aux exigences.

Vous ne pourrez pas effectuer la mise à niveau vers Joomla 5 si l'environnement de votre serveur ne répond pas aux exigences techniques minimales. L'option de mise à niveau n'apparaîtra pas dans le composant de mise à jour de Joomla.

• PHP 8.1
• MySQL 8.0.13
• MariaDB 10.4.x (les tests ont montré que J3, J4 et J5 sont compatibles avec MariaDB 10.4.x)
• PostgreSQL 12.0 (si vous utilisez PostgreSQL 16, vous devrez effectuer une modification manuelle avant de poursuivre.)

Vous pouvez vérifier les informations de votre système sur un site Joomla 4 en cliquant sur Système -> Informations système. Contactez votre hébergeur si votre serveur ne répond pas aux exigences.

Voici un exemple d'environnement répondant aux exigences techniques. Il montre MySQL 8.0.34, PHP 8.1 et Joomla 4.4.x.

2. Vérifier toutes vos extensions pour la compatibilité avec Joomla 5

Il existe un certain nombre de scénarios concernant les extensions tierces pour cette mise à niveau.

1. L'extension peut être compatible à la fois avec J4 et J5 sans l'utilisation du plugin de compatibilité ascendante.
2. L'extension peut être compatible à la fois avec J4 et J5 AVEC l'utilisation du plugin de compatibilité ascendante.
3. L'extension peut sembler fonctionner dans J5, mais lorsque vous essayez de l'utiliser, elle est défaillante.
4. L'extension peut casser l'ensemble du site.

Ne vous inquiétez pas ! Ce n'est pas aussi grave que ça en a l'air ! Parlons d'abord du plugin de compatibilité ascendante.

Le plugin de compatibilité ascendante

Le Comportement - plugin de compatibilité ascendante est une tentative de permettre aux extensions tierces d'utiliser des classes qui ne sont plus incluses dans Joomla 5.

Lors d'une mise à jour de J4.4.x vers J5, le plugin de compatibilité ascendante sera activé automatiquement. Pour les nouvelles installations de J5, le plugin de compatibilité ascendante sera activé par défaut.

Le plugin de compatibilité ascendante qui prend en charge les extensions fonctionnant sous J4 restera en place pendant toute la durée de J5. Dans J6, les extensions J4 ne seront plus rendues compatibles grâce au plugin. Cela donne aux développeurs d'extensions deux années supplémentaires pour rendre leurs extensions compatibles avec J5 sans le plugin de compatibilité ascendante. L'intention est qu'à chaque nouvelle version de cycle de vie, un plugin de compatibilité ascendante prenne en charge le cycle de vie précédent jusqu'au cycle de vie suivant.

Peut-on un jour désactiver le plugin de compatibilité ascendante dans J5 ? Excellente question. Après avoir déterminé que chacune de vos extensions tierces est conforme et pleinement fonctionnelle sans le plugin de compatibilité ascendante activé, vous pouvez le désactiver. Cela dit, nous recommandons la prudence. Avant de désactiver le plugin de compatibilité ascendante, il est suggéré de faire l'une des deux choses suivantes :

1. Faites-le sur un site de développement/test. Ainsi, si vous avez accidentellement oublié une extension qui rend votre back-end inaccessible, cela ne mettra pas hors service votre site de production.
2. Assurez-vous d'avoir accès à la base de données. Ainsi, vous pourrez réactiver rapidement le plugin si nécessaire. Plus d'informations à ce sujet ci-dessous.

Vérification pré-mise à jour comparée à Système -> Gestion des extensions

En théorie, la vérification pré-mise à jour vous indiquerait si vos extensions tierces sont compatibles avec J5. Cependant, la vérification pré-mise à jour n'est utile que si tous les développeurs d'extensions ont fait en sorte que leur extension reflète sa compatibilité. Dans un monde parfait, la section Extensions de la vérification pré-mise à jour vous indiquerait si une extension :

• Peut être mise à jour sans que le plugin de compatibilité ascendante soit activé
• Peut être mise à jour avec le plugin de compatibilité ascendante activé
• Nécessite une mise à jour de l'extension avant de passer de J4 à J5
• Est totalement incompatible

Les tests ont révélé des divergences entre les extensions compatibles et non compatibles. Il ne s'agit pas d'un problème lié au composant de vérification pré-mise à jour. En réalité, les développeurs d'extensions transmettent des informations via leurs extensions qui alimenteraient correctement la vérification pré-mise à jour. Si leurs extensions ne sont pas codées pour indiquer à la vérification pré-mise à jour les informations correctes, il y a très peu (voire rien) que la vérification pré-mise à jour ou le Projet Joomla! puisse y faire. Une bonne source d'informations serait le site web du développeur de l'extension tierce pour vérifier comment l'extension spécifique doit être gérée lors de la mise à niveau de J4 vers J5.

L'image ci-dessous montre un exemple du composant de vérification pré-mise à jour dans Joomla 4.4.x de la section Extensions.

La section du haut montre les extensions qui nécessitent une mise à jour. Veuillez aller dans Système -> Mise à jour -> Extensions et mettre à jour vos extensions.

La section du milieu montre les extensions pour lesquelles les informations de mise à jour ne sont pas disponibles auprès du développeur de l'extension. Vous ne saurez pas si elles sont compatibles ou non sans les tester ou contacter le développeur.

La section du bas montre les extensions qui ne nécessitent aucune mise à jour. Cela signifie que les extensions indiquent à Joomla qu'elles sont compatibles avec Joomla 5. Il n'est pas précisé si elles nécessitent le plugin de compatibilité ascendante ou non.

Veuillez noter que ces extensions ne sont pas recommandées par le Projet Joomla. Ces extensions sont présentées uniquement à titre d'exemple. Elles ont été choisies au hasard dans le JED à des fins de test.

Il est recommandé de n'utiliser la partie Extensions du composant de vérification pré-mise à jour que comme un aperçu très général, mais pas comme une source de vérité à 100 %. Autrement dit, vous ne pourrez peut-être pas faire confiance au composant de vérification pré-mise à jour selon les extensions que vous utilisez.

Quelle est donc la source de vérité ? Système -> Gestion des extensions

Depuis l'écran Extensions : Gestion, vous pourrez voir toutes les extensions tierces que vous utilisez sur le site. Dans la capture d'écran ci-dessous, vous voyez l'écran principal. Dans la colonne Auteur, vous pouvez voir le nom d'un développeur d'extensions populaire dans un certain nombre de lignes. Vous pouvez également voir l'Auteur du Projet Joomla dans un certain nombre de lignes.

Vérifiez vos extensions tierces. Vous allez ensuite déterminer si elles sont compatibles avec J5 (avec ou sans le plugin de compatibilité ascendante) ou non. Si ce n'est pas le cas, la mise à niveau échouera.

Trois façons de vérifier la compatibilité de vos extensions tierces avec J5

1. Vérifier le site web du développeur.
2. Effectuer une sauvegarde/copie de votre site J4, la restaurer sur un sous-domaine, activer le débogage, suivre les étapes (ci-dessous) pour la mise à niveau vers J5. Voir si quelque chose casse. Si c'est le cas, désactiver chaque extension qui génère une erreur en notant l'extension concernée. Vous devrez contacter le développeur à ce sujet puisqu'elle n'est pas compatible avec J5.
3. Installer un pack J5 propre sur un sous-domaine, activer le plugin Comportement - Compatibilité ascendante, installer toutes les extensions que vous utilisez et voir si elles fonctionnent.

REMARQUE : le répertoire d'extensions Joomla! (JED) affichera des indicateurs de compatibilité Joomla 5 pour les extensions compatibles, avec ou sans l'utilisation du plugin de compatibilité ascendante.

Vous pourriez faire une combinaison des approches ci-dessus. Commencer par une installation propre et tester vos extensions. Une fois que vous savez lesquelles fonctionnent ou non, vous pouvez échanger avec les développeurs pour voir où ils en sont dans leur développement pour J5. ENSUITE, une fois que toutes vos extensions fonctionnent sur un site propre, vous saurez que vous pouvez tester une mise à niveau complète de J4.4.x vers 5.x.

Vous pourriez vouloir déterminer si une extension fonctionne sans que le plugin de compatibilité ascendante soit activé. Si c'est le cas, vous aurez besoin d'un accès à la base de données. Prévoyez-le. Assurez-vous d'avoir accès à la base de données.

Après l'installation de J5, le plugin de compatibilité ascendante sera activé. Vous devez le désactiver. Aller dans 'Plugins', filtrer par le type 'Comportement' et désactiver 'Comportement - Compatibilité ascendante'. Installer chaque extension une à la fois. Si cela bloque votre site, activer le plugin de compatibilité ascendante via la base de données.

Le plugin de compatibilité ascendante se trouve dans la base de données, dans la table _extensions. Il s'appelle plg_behaviour_compat. Définissez le champ Enabled sur 0 pour désactiver le plugin, et sur 1 pour l'activer. En réactivant le plugin de compatibilité ascendante, vous pourrez peut-être accéder à nouveau à l'administration de Joomla (tant que l'extension fonctionne avec le plugin de compatibilité ascendante).

OU

Vous pouvez désactiver l'extension dans la base de données afin de pouvoir continuer à tester vos autres extensions pour voir si elles fonctionnent sans que le plugin de compatibilité soit activé. Ces entrées se trouveront dans la table #_extensions. Vous devrez changer le champ Enabled sur 0 pour désactiver l'extension.

Dans certains cas, lorsque vous installez une extension dans J5 qui n'est pas compatible avec ou sans le plugin de compatibilité ascendante activé, vous devrez trouver les entrées correspondant à cette extension dans la base de données (il peut y en avoir quelques-unes ou beaucoup) et les désactiver jusqu'à ce que vous puissiez retrouver l'accès à l'administration. Ces entrées se trouveront dans la table #_extensions. Vous devrez changer le champ Enabled sur 0 pour désactiver l'extension. Une fois que vous pouvez à nouveau accéder à l'administration de Joomla, vous pouvez la désinstaller proprement depuis Système -> Gestion -> Extensions et vous renseigner auprès du développeur.

Cassiopeia, Recaptcha, Weblinks, Schema.org, et Search (com_search et non la Recherche avancée)

Cassiopeia

Cassiopeia restera le template frontal de Joomla 5. Vos personnalisations devraient fonctionner normalement, mais nous recommandons tout de même de tester sur un site de développement pour en être sûr. Bootstrap sera mis à niveau vers Bootstrap 5.3 dans Joomla 4.4.0. S'il y a des incohérences Bootstrap dans votre template, elles seront déjà visibles en 4.4.0. Ainsi, la plupart, voire la totalité, des problèmes seront détectés avant la mise à niveau vers J5.

Google reCAPTCHA

Si vous utilisez Google reCAPTCHA dans J4, vous devez le remplacer par Invisible reCAPTCHA avant de passer à Joomla 5 (ou par une solution tierce). J5 n'inclura plus Google Recaptcha. Le plugin Recaptcha sera désinstallé lors de la mise à niveau vers J5. Le plugin Invisible reCAPTCHA existe toujours si vous avez effectué une mise à niveau depuis 4.4.x. Vous pouvez l'activer et le configurer avec de nouvelles clés afin d'utiliser Invisible reCAPTCHA à la place. Vous pouvez également utiliser une autre solution tierce. Les nouvelles installations de Joomla 5.x n'incluent aucun plugin reCAPTCHA dans le noyau. Les nouvelles installations de Joomla 5.x devront utiliser un plugin/une solution tiers.

com_weblinks

L'extension Weblinks fonctionne dans J5 sans que le plugin de compatibilité ascendante soit activé à partir de la version 4.3.0+. 4.3.0 sur Github. Weblinks sur le JED.

Plugin Schema.org

Avec Joomla! 5, une nouvelle façon, plus dynamique, de gérer les extraits enrichis (basée sur https://schema.org/) a été mise en œuvre. Par défaut, ils sont configurés de manière à ce que les informations destinées aux moteurs de recherche soient identiques à celles de Joomla 4, mais pour personnaliser le résultat, veuillez vous rendre dans Système => Gestion => Plugins et rechercher le plugin système « System - Schema.org ». Modifiez le plugin pour ajouter les informations de votre site afin d'utiliser correctement cette fonctionnalité. Pour en savoir plus, consultez cet article de magazine sur les extraits enrichis.

com_search

com_search n'est pas disponible dans Joomla 5. Désinstallez-le avant de passer à Joomla 5. Vous utiliserez désormais la Recherche avancée (com_finder).

Essai préalable

Dans le cadre de votre planification, il est recommandé de tester votre mise à niveau sur un sous-domaine ou en local afin de vérifier qu'elle fonctionne parfaitement. Veillez à noter toutes les étapes nécessaires pour que votre mise à niveau se déroule parfaitement.

Une fois que vous avez testé votre mise à niveau sur un sous-domaine ou en local, et qu'elle fonctionne parfaitement, vous pouvez effectuer une sauvegarde de votre site de production et procéder à la mise à niveau de celui-ci. Les instructions étape par étape figurent ci-dessous.

Mise à niveau étape par étape

Le site que vous allez mettre à niveau doit répondre à toutes les exigences techniques et exécuter Joomla 4.4.x pour pouvoir être mis à niveau. Si votre site n'exécute pas encore Joomla 4.4.x, mettez-le à jour vers la version 4.4.x avant de passer à J5.

1. Suivez toutes les instructions de la section Planification (ci-dessus) avant de procéder à la mise à niveau.
   
   
2. Sauvegardez votre site web.
   
   
3. Mettez à jour les extensions qui doivent l'être.
   
   
4. Désactivez ou désinstallez les extensions qui ne sont pas compatibles avec J5.
   
   
5. Si vous utilisez l'ancien composant Rechercher (com_search) ou des modules liés, désinstallez-les avant de procéder à la mise à niveau.
   
   
6. Si vous utilisez Google reCAPTCHA, désactivez-le et commencez à utiliser Invisible reCAPTCHA à la place.
   
   
7. Activez le débogage (Configuration générale -> onglet Système -> paramètre Débogage système sur Oui).
   
   
8. Sauvegardez à nouveau votre site web.
   
   
9. Testez votre sauvegarde pour vous assurer qu'elle se restaure correctement. (Oui, faites-le. Vous vous sentirez mieux.)
   
   
10. Allez dans Système -> Mise à jour -> Joomla
    
    
    
    
11. Cliquez sur Paramètres dans la barre d'outils supérieure, sur le côté droit.
    
    
    
    
12. Changez le canal de mise à jour pour Joomla Next.
    
    
    
    
13. Cliquez sur Enregistrer & Fermer dans la barre d'outils supérieure.
    
    
14. Si votre serveur répond aux exigences techniques, vous verrez l'écran suivant avec des liens dans la barre latérale gauche pour les Paramètres requis, les Paramètres recommandés et les Extensions.
    
    
    
    
15. Il y a de fortes chances que vos Paramètres requis et vos Paramètres recommandés soient corrects puisque cet écran ne s'affichera pas si votre environnement ne répond pas aux exigences techniques. Les Extensions peuvent en revanche poser problème. Consultez la section Planification (ci-dessus) à propos de la vérification pré-mise à jour et des raisons pour lesquelles elle peut ne pas afficher de coche verte tout en ayant des extensions compatibles. Vous avez déjà effectué vos tests (n'est-ce pas ?), vous savez donc déjà si elles sont compatibles ou non.
    
    
16. Le plugin de compatibilité ascendante sera activé lors de la mise à niveau de Joomla 4.4.x vers 5.x.
    
    
17. Si vous n'avez pas suivi les instructions de la section Planification (ci-dessus) concernant l'Essai préalable, arrêtez-vous maintenant et retournez à la section Planification pour suivre les instructions. La planification est la partie la plus importante de cette mise à niveau.
    
    
18. Une fois que vous êtes certain que toutes vos extensions sont compatibles avec J5 et que vous avez testé la mise à niveau avec un résultat parfait, vous pouvez cocher la case pour accepter les alertes concernant les extensions potentiellement incompatibles et poursuivre la mise à jour, cliquer sur OK dans la fenêtre modale, puis cliquer sur le bouton Mettre à jour.
    
    
    
    
19. Ensuite, votre site vous demandera à nouveau de confirmer que vous avez effectué une sauvegarde (ce que vous avez fait et dont vous avez testé la restauration).
    
    
    
    
20. Votre site va effectuer la mise à niveau vers J5.
    
    
    
    
21. Une mise à niveau réussie affichera un écran comme celui-ci
    
    
    
    
22. Vous verrez que votre site est en Joomla 5 dans le coin supérieur droit de l'écran.
    
    
23. Tester le frontal de votre site.
    
    
24. Tester l'arrière-plan de votre site.
    
    
25. Désactiver le mode Debug dans Système -> Configuration Générale -> onglet Serveur.
    
    
26. Corriger votre nouvelle Indexation si nécessaire.
    
    
27. Configurer votre plugin de schéma comme décrit dans la partie planification de ce document.
    
    
28. Savourez une bonne boisson et admirez à quel point vous êtes formidable.
    
    

Que faire en cas de problème ?

Si vous avez tout testé au préalable, cela ne devrait pas arriver. Mais il est possible qu'un élément de l'environnement ait changé, ou qu'un code d'une extension ait été modifié entre le moment de vos tests et votre mise à niveau.

Comme vous avez activé le mode Debug avant de commencer, vous devriez pouvoir identifier l'extension à l'origine du problème et la désactiver (cela peut nécessiter une intervention depuis la base de données si vous ne pouvez plus accéder à l'arrière-plan pour la désactiver). Ainsi, votre site restera opérationnel pendant que vous déterminez ce qui s'est mal passé et le corrigez.

Dans le pire des cas, restaurez votre sauvegarde afin d'avoir le temps de résoudre le problème dans un environnement de test.

La correction de la base de données peut résoudre certains de vos problèmes. Accédez au Panneau d'administration Système et cliquez sur Base de données.

Dans la page Maintenance : Base de données, les éventuels problèmes de structure de la base de données de votre site seront affichés. Cochez la case appropriée puis cliquez sur le bouton Mettre à jour la structure dans la barre d'outils supérieure.

Autres sources d'aide

Forum Joomla : Forum Migration et mise à niveau 5.x

Communauté Joomla sur Mattermost