Créer une extension Joomla personnalisée : le guide développeur

Vous avez ouvert le fichier mod_breadcrumbs.php pour changer deux lignes. Deux heures plus tard, vous avez cassé le menu latéral du site. On connaît tous ça.

La différence entre bricoler un template et créer une extension Joomla personnalisée qui survit à une mise à jour, c'est rarement la compétence PHP. C'est l'architecture. Et l'architecture, Joomla ne vous la donne pas gratuitement : elle vous la cache derrière des conventions que personne n'explique vraiment dans les tutoriels d'introduction.

J'ai passé une bonne partie de l'année dernière à réécrire un composant maison qui avait été « fini » par trois prestataires successifs. Il marchait. Il ne survivait juste à aucune montée de version. Voici ce que j'aurais aimé qu'on me dise avant.

Quel type d'extension Joomla choisir avant d'écrire la moindre ligne de code

C'est la question que je vois arriver dans à peu près une demande sur deux : « je veux ajouter un bloc personnalisé sur mon site, je fais un composant ? ». Non. Surtout pas.

Joomla découpe ses extensions en familles distinctes, et chaque famille a un rôle précis dans le cycle de vie d'une page. Se tromper là-dessus, c'est se retrouver avec un composant de 4 000 lignes pour afficher une citation dans un pied de page.

Composant, module, plugin, template : le rôle réel de chacun

• Le composant est l'application dans l'application. Il gère ses propres vues, ses propres modèles, ses propres formulaires, et il occupe la zone principale de la page. Si votre besoin a une URL dédiée, c'est un composant.
• Le module est un bloc positionnable. Il s'affiche dans une position de template, à côté ou autour du contenu principal. Un module peut être un formulaire de connexion, un filtre, une liste d'articles récents.
• Le plugin ne s'affiche jamais. Il s'accroche à un événement du cœur et modifie un comportement : réécrire une URL, filtrer un champ de formulaire, intercepter un enregistrement utilisateur.
• Le template contrôle la mise en forme globale, et les overrides vous permettent de surcharger une vue sans toucher au composant d'origine.

Et là, franchement, la règle qui m'a fait gagner le plus de temps : si vous hésitez entre module et plugin, posez-vous une seule question. Est-ce que ça produit quelque chose de visible ? Si oui, module. Si non, plugin.

Comparatif des quatre familles

Type	Zone d'affichage	URL propre	Cas typique
Composant	Zone principale	Oui	Annuaire, gestion de projets, catalogue
Module	Position de template	Non	Derniers articles, filtres, bannière
Plugin	Aucune	Non	Réécriture d'URL, validation de champ
Template	Structure complète	Sans objet	Design, overrides, gabarits de page

Un dernier point qui surprend souvent : une même extension peut contenir plusieurs de ces types. Un composant peut embarquer son propre module et son propre plugin dans un seul paquet installable. C'est même la pratique courante dès qu'on publie quelque chose de sérieux.

La structure de fichiers d'une extension Joomla, expliquée sans détour

Voici l'arborescence minimale d'un composant, celle que la doc vous montre en schéma mais que peu de gens prennent le temps de lire vraiment.

com_exemple/
├── exemple.xml          ← le manifeste
├── admin/
│   ├── services/
│   │   └── provider.php
│   ├── src/
│   │   ├── Controller/
│   │   ├── Model/
│   │   └── Table/
│   └── sql/
│       └── updates/
└── site/
    ├── src/
    │   ├── Controller/
    │   ├── Model/
    │   └── View/
    ├── tmpl/
    └── services/
        └── provider.php

Le manifeste XML : le fichier que tout le monde sous-estime

Le fichier exemple.xml à la racine décrit votre extension au gestionnaire d'extensions. Il contient le nom, la version, l'auteur, mais surtout trois choses qu'on oublie régulièrement :

1. La liste des fichiers et dossiers à copier lors de l'installation.
2. Les scripts d'installation, de mise à jour et de désinstallation, qui permettent d'exécuter du code PHP à ces moments précis.
3. Le point d'entrée vers le fichier SQL qui crée ou fait évoluer vos tables.

J'ai vu un projet où la mise à jour écrasait silencieusement les préférences des utilisateurs parce que le script de mise à jour n'avait jamais été écrit. Personne ne s'en était rendu compte pendant huit mois. Huit mois.

Namespaces et services providers : la bascule Joomla 4 et 5

Si vous arrivez de Joomla 3, oubliez les anciens fichiers controller.php procéduraux. Les versions 4 et 5 reposent sur l'autoloading PSR-4, avec un namespace qui reprend en général le nom de l'éditeur. Un service provider déclare les dépendances de votre extension auprès du conteneur d'injection.

Concrètement, ça veut dire que vous ne faites plus new MonModele() à la main dans un contrôleur. Vous demandez l'objet au conteneur, et il vous le fournit. Ça paraît lourd au départ. Ça devient indispensable dès que vous avez besoin de tester votre code ou de remplacer une dépendance.

Petit conseil de quelqu'un qui s'est arraché les cheveux : ne mélangez jamais les deux approches dans un même composant. Soit tout passe par le conteneur, soit rien. Un composant à moitié migré est un cauchemar à déboguer.

Développer une extension Joomla : par où commencer concrètement

Plutôt qu'un tutoriel théorique, voici l'ordre dans lequel je travaille aujourd'hui. Il est le fruit de plusieurs échecs, dont un composant abandonné après trois semaines parce que j'avais attaqué par le mauvais bout.

1. Écrire le manifeste en premier, avec le nom, la version et l'arborescence prévue. Même vide. Il sert de contrat.
2. Créer le service provider et vérifier que l'extension s'installe sans erreur sur un Joomla propre.
3. Construire la table en base et son modèle, avant toute vue. Le contraire m'a coûté une refonte complète.
4. Ajouter le contrôleur et la vue liste, puis la vue détail.
5. Seulement là, s'occuper des overrides côté template et du rendu visuel.
6. Terminer par les scripts de mise à jour et la gestion de version.

Le point 3 est celui que tout le monde saute. On veut voir quelque chose à l'écran. On bricole une vue, puis une deuxième, et on se rend compte au bout d'une semaine que le modèle ne gère pas les relations dont on a besoin. Retour à la case départ.

Comment tester correctement une extension avant de la déployer

Trois environnements, pas un. Un Joomla vierge pour valider l'installation, un Joomla chargé avec du contenu réel pour valider le rendu, et une copie de la production pour valider les conflits avec les autres extensions. Cette troisième étape est celle qu'on néglige, et c'est celle qui révèle les vrais problèmes.

Une extension qui fonctionne parfaitement sur un site vide peut entrer en collision avec un plugin de mise en cache, un template alternatif ou un autre composant qui touche aux mêmes tables. Ce genre de conflit ne se voit qu'en conditions réelles.

Publier et maintenir son extension dans la durée

Une extension qui n'est jamais mise à jour devient une dette de sécurité. C'est aussi simple que ça.

Le serveur de mise à jour se déclare dans le manifeste, via un fichier XML que votre extension publie quelque part et que Joomla interroge périodiquement. Sans ce mécanisme, chaque correctif doit être installé manuellement sur chaque site client. Inutile de préciser qu'en pratique, ça ne se fait pas.

Côté distribution, le Joomla Extensions Directory reste le point de passage principal pour se faire connaître, mais il impose des règles de qualité strictes : code conforme aux standards, absence d'erreurs PHP, documentation. Un refus au premier passage est courant et ne signifie pas que votre travail est mauvais. Il signifie qu'il manque un fichier de langue ou un README.

Faut-il créer une extension sur mesure ou utiliser une solution existante ?

Franchement, la réponse honnête est : commencez toujours par chercher l'existant.

Pour un formulaire sur mesure, un outil de construction de formulaires couvrira 90 % des besoins sans une ligne de code. Pour de la gestion de données structurées, des solutions génériques de type constructeur d'applications font le travail correctement. Le développement sur mesure se justifie quand votre logique métier est réellement spécifique, quand vous devez vous interfacer avec un système interne, ou quand la performance devient critique.

La mauvaise raison de développer, c'est le contrôle. « Je veux tout maîtriser » se paie en maintenance, en mises à jour de compatibilité, en tests à chaque nouvelle version de Joomla. J'ai un client qui a fait ce choix pour une fonctionnalité finalement assez banale. Deux ans après, il payait plus cher de maintenance que ce que lui aurait coûté une extension du marché.

Ce qu'il faut retenir

Créer une extension Joomla personnalisée n'est pas difficile parce que le code est compliqué. C'est difficile parce que les conventions sont nombreuses et qu'une seule erreur d'architecture se paie pendant des mois. Le type d'extension, le manifeste, la séparation entre modèle et vue, la gestion des migrations : chaque décision prise au départ conditionne tout le reste.

Et cette histoire de composant réécrit trois fois ? La version finale a tenu. Pas parce qu'on a écrit du meilleur PHP, mais parce qu'on a passé une journée entière, au début, à ne rien coder du tout. Juste à décider de la structure.

Une journée. Contre plusieurs mois perdus avant.