From e29df2e88dfb5f397b9c45162b5fc4ac4247b50c Mon Sep 17 00:00:00 2001
From: Cyssoo <cyrilchalamon@gmail.com>
Date: Wed, 4 Mar 2026 08:06:18 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20ajouter=20des=20commentaires=20sur=20le?=
 =?UTF-8?q?s=20m=C3=A9thodes=20cl=C3=A9s=20PHP?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 everblock.php                     | 27 ++++++++++++++++++++++++++-
 src/Command/ImportFileCommand.php | 14 ++++++++++++++
 src/Service/EverblockTools.php    |  6 ++++++
 3 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/everblock.php b/everblock.php
index c20b5f3f..88851c35 100644
--- a/everblock.php
+++ b/everblock.php
@@ -88,6 +88,17 @@ public function __construct()
         ];
     }
 
+    /**
+     * Intercepte dynamiquement les hooks display non déclarés explicitement.
+     *
+     * Cette méthode évite de devoir créer une méthode hook* pour chaque hook display,
+     * tout en limitant l'exécution au front-office (hors contrôleurs bypassés).
+     *
+     * @param string $method Nom de la méthode appelée (ex: hookDisplayHome)
+     * @param array<int, mixed> $args Arguments transmis par PrestaShop
+     *
+     * @return mixed
+     */
     public function __call($method, $args)
     {
         if (php_sapi_name() == 'cli') {
@@ -106,7 +117,9 @@ public function __call($method, $args)
         }
     }
 
-
+    /**
+     * Installe le module et son socle fonctionnel (config, SQL, hooks, onglets BO).
+     */
     public function install(): bool
     {
         if (!parent::install()) {
@@ -132,6 +145,9 @@ public function install(): bool
         return true;
     }
 
+    /**
+     * Initialise les clés de configuration nécessaires au fonctionnement du module.
+     */
     private function installConfiguration(): bool
     {
         $configuration = [
@@ -180,6 +196,9 @@ private function installConfiguration(): bool
         return true;
     }
 
+    /**
+     * Exécute le script SQL d'installation et crée les tables du module.
+     */
     private function installSql(): bool
     {
         $sql = [];
@@ -194,6 +213,9 @@ private function installSql(): bool
         return true;
     }
 
+    /**
+     * Crée les hooks personnalisés du module puis enregistre les hooks natifs requis.
+     */
     private function installHooks(): bool
     {
         $customHooks = [
@@ -231,6 +253,9 @@ private function installHooks(): bool
         return true;
     }
 
+    /**
+     * Enregistre les hooks d'intégration avec QCD Builder lorsqu'ils sont disponibles.
+     */
     private function registerQcdBuilderHooks(): bool
     {
         $hooksToRegister = [
diff --git a/src/Command/ImportFileCommand.php b/src/Command/ImportFileCommand.php
index cdeac1ae..882481ee 100644
--- a/src/Command/ImportFileCommand.php
+++ b/src/Command/ImportFileCommand.php
@@ -48,6 +48,9 @@ public function __construct(KernelInterface $kernel)
         parent::__construct();
     }
 
+    /**
+     * Déclare la commande d'import et prépare les chemins de fichiers utilisés.
+     */
     protected function configure()
     {
         $this->setName('everblock:tools:import');
@@ -61,6 +64,9 @@ protected function configure()
         $this->module = \Module::getInstanceByName('everblock');
     }
 
+    /**
+     * Orchestration de l'import XLSX : lecture, mise à jour des blocs puis nettoyage.
+     */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
         if (file_exists($this->filename)) {
@@ -93,6 +99,14 @@ protected function execute(InputInterface $input, OutputInterface $output)
         }
     }
 
+    /**
+     * Crée ou met à jour un bloc à partir d'une ligne du fichier d'import.
+     *
+     * Chaque colonne est validée avant affectation afin d'éviter l'écriture de données
+     * incohérentes en base.
+     *
+     * @param array<string, mixed> $line
+     */
     protected function updateEverblocks($line, $output)
     {
         if (!isset($line['id_lang'])
diff --git a/src/Service/EverblockTools.php b/src/Service/EverblockTools.php
index d706e3b5..5cee5733 100644
--- a/src/Service/EverblockTools.php
+++ b/src/Service/EverblockTools.php
@@ -75,6 +75,12 @@
 
 class EverblockTools extends ObjectModel
 {
+    /**
+     * Point d'entrée principal du moteur de shortcodes.
+     *
+     * Le texte est enrichi en plusieurs étapes : hooks d'extension, résolution des
+     * shortcodes métier, remplacement des variables Smarty et post-traitements client.
+     */
     public static function renderShortcodes(string $txt, Context $context, Everblock $module): string
     {
         Hook::exec('displayBeforeRenderingShortcodes', ['html' => &$txt]);