Qui sommes nous ?
a
M

Suivez nous

Acceuil > Tous nos articles Magento & Ecommerce > Beginner’s Guide Magento #02 : Anatomie d’un module Magento 2

Beginner’s Guide Magento #02 : Anatomie d’un module Magento 2

Dans notre premier article, nous avons vu que Magento 2 repose sur une architecture entièrement modulaire.

Aujourd’hui, nous allons mettre les mains dans le cambouis. L’objectif n’est pas encore de coder une fonctionnalité complexe, mais de disséquer un module Magento 2 : sa structure, ses fichiers essentiels et leur rôle.

Il est crucial de comprendre ce que vous voyez lorsque vous ouvrez un dossier de module pour la première fois. C’est parti pour l’autopsie.

1. Rappel : Qu’est-ce qu’un module Magento 2 ?

Un module est une brique fonctionnelle autonome. Dans Magento, tout est module : le catalogue, le panier, la gestion client, et même l’interface d’administration.

Pour être valide, un module doit :

  • Avoir un nom unique (ex : Company_Module).
  • Être chargé par le framework Magento.
  • Servir à ajouter, modifier ou étendre un comportement existant.

2. Où se trouvent les modules ?

Il existe deux emplacements distincts selon la provenance du module.

A. Les modules « Custom » (Les vôtres)

C’est ici que vous allez travailler. Vos modules personnels ou spécifiques au projet se trouvent dans : app/code/Company/ModuleName

B. Les modules « Core » ou « Vendor »

Ce sont les modules natifs de Magento ou les extensions tierces installées via Composer. Ils se trouvent dans : vendor/vendor-name/module-name

⚠️ Règle d’or : Ne modifiez jamais les fichiers situés dans le dossier vendor. Vos modifications seraient écrasées à la prochaine mise à jour.

3. La structure minimale (Le strict nécessaire)

Pour qu’un module existe aux yeux de Magento, il a besoin de deux fichiers indispensables. Sans eux, rien ne se passe.

app/code/Vendor/Module/
├── registration.php      <-- Point d'entrée
└── etc/
    └── module.xml        <-- Carte d'identité
  1. registration.php : C’est le fichier qui dit à Magento « Coucou, je suis là, charge-moi ».
  2. etc/module.xml : Il définit le nom du module, sa version (setup_version) et ses éventuelles dépendances envers d’autres modules.

Une fois ces bases posées, un module peut s’étoffer avec de nombreux dossiers. Voici à quoi ressemble une structure standard complète :

Plaintext

Vendor/Module/
├── Block/
├── Controller/
├── Cron/
├── Helper/
├── Model/
├── Observer/
├── Plugin/
├── Setup/
├── etc/
├── view/
└── ... (Api, Console, Injection, Ui, ViewModel, etc.)

Voyons maintenant le rôle de chaque dossier clé.

4. etc/ : Le cerveau du module

C’est le centre de configuration. Il contient tous les fichiers XML qui dictent le comportement du module.

  • di.xml : (Dependency Injection) Gère l’injection de dépendances et la déclaration des Plugins. C’est un fichier central pour modifier des classes existantes.
  • events.xml : Déclare les Observers qui écoutent des événements spécifiques.
  • routes.xml : Définit les URLs (routes) du module pour le frontend ou l’admin.
  • acl.xml : Gère les permissions (Access Control List) pour les utilisateurs du Back-office.
  • crontab.xml : Planifie les tâches récurrentes (Cron jobs).
  • db_schema.xml : Le standard moderne pour créer ou modifier la structure des tables en base de données (Declarative Schema).

💡 Note : Ce dossier est souvent segmenté par « Zone ».

  • etc/frontend/ : Configuration qui ne s’applique qu’au site client.
  • etc/adminhtml/ : Configuration réservée au panneau d’administration.
  • etc/webapi_rest/ : Configuration des APIs.

5. Controller/ : Le chef de gare

Ce dossier contient les classes qui reçoivent les requêtes URL.

Si vous créez une page accessible via monsite.com/test/page, la logique de réception se trouve ici.

Le chemin suit la logique : Controller/NomDuDossier/NomDeLaction.php. Par exemple : Controller/Page/Index.php.

Bonne pratique : Le contrôleur doit rester léger. Il ne contient pas de logique métier, il se contente de déléguer le travail et de demander l’affichage d’une page.

6. Block/ : Le préparateur de vue

Les Blocks font le pont entre le PHP et le HTML. Leur rôle est de préparer les données (récupérées via les Models) pour les injecter proprement dans les templates (.phtml).

Cela évite d’avoir du code PHP complexe directement dans le fichier de vue. Le template doit juste faire un echo $block->getTitre(); sans se soucier de comment le titre est calculé.

7. view/ : L’affichage (Frontend et Admin)

C’est ici que réside tout ce qui est visuel. Comme pour etc, ce dossier est obligatoirement divisé en sous-dossiers par zone (frontend et adminhtml).

Structure type :

view/
├── frontend/
│   ├── layout/          <-- XML de structure de page
│   ├── templates/       <-- Fichiers .phtml (HTML + PHP simple)
│   └── web/             <-- CSS, JS, Images, Fonts
└── adminhtml/
    ├── ui_component/    <-- Grilles et formulaires Admin (UI Component)
    └── ... (layout, templates, web)
  • layout/*.xml : Il définit la structure de la page.
  • templates/*.phtml : Il contient les templates des blocs définis dans les layouts.
  • web/ : Il contient les différents assets (CSS, JavaScript, images).
  • ui_component/ : Il permet de générer des grilles de données et des formulaires complexes en XML (utilisé en admin).

8. Model/ : La logique métier et la donnée

C’est le moteur du module. Pour manipuler une donnée en base de données, Magento utilise un trio inséparable :

  1. Model (Item.php) : Représente l’objet métier (ex: Une facture, un produit). C’est une boîte à données.
  2. ResourceModel (ResourceModel/Item.php) : Le seul autorisé à parler SQL. C’est lui qui fait les INSERT, UPDATE, SELECT.
  3. Collection (ResourceModel/Item/Collection.php) : Permet de gérer une liste de modèles (ex: « Donne-moi les 10 dernières factures »).

9. Observer/ et Plugin/ : Intercepter et réagir

  • Observers : Ils réagissent à un événement déclenché (ex: « Une commande a été passée »). Ils sont déclarés dans events.xml.
  • Plugins (Interceptors) : Ils permettent de modifier le comportement d’une méthode publique avant, après ou pendant son exécution. Ils sont déclarés dans di.xml.

N’hésitez pas à consulter notre article dédié aux différences entre Plugins et Observers pour approfondir ce sujet.

10. Setup/ : L’évolution des données

Si db_schema.xml (dans etc) gère la structure des tables, le dossier Setup est aujourd’hui principalement utilisé pour manipuler le contenu de la base de données via les Data Patches.

  • Patch/Data : Contient des classes pour insérer des données par défaut, créer des attributs ou modifier des configurations lors de l’installation du module.
  • Ces scripts s’exécutent lors de la commande bin/magento setup:upgrade.

11. Cron/

Contient les classes exécutées automatiquement en arrière-plan à intervalles réguliers (nettoyage de logs, synchronisation ERP, envois d’emails…).

12. Helper/

Contient des classes utilitaires avec des fonctions génériques réutilisables partout dans le module.

Attention cependant à ne pas en abuser et à ne pas créer des « classes fourre-tout ».

Magento 2 peut paraître impressionnant lors des premiers pas. Son arborescence dense, son usage
massif du XML et son découpage très strict donnent parfois l’impression d’un framework inutilement
complexe. En réalité, cette structure est ce qui fait sa force.


Comprendre cette organisation est une première étape essentielle pour aborder sereinement un
projet et savoir où intervenir.