Modules

1. Test préalable

Un module s’articulant sur la structure MVC (modèle-vue-contrôleur) de PrestaShop, il est important que les fichiers PHP de celui-ci ne soient pas exécutables en dehors de celle-ci.

Afin de réaliser ce test, il est possible de s’appuyer sur la valeur de la constante PS_VERSION, qui est toujours définie en début d’initialisation par PrestaShop. 

Cette vérification peut se faire de la sorte :

<?php 
if (!defined('_PS_VERSION_')) { 
    exit; 
} 

2. Héritage

La classe principale de votre module doit étendre la classe Module afin d’être reconnue comme telle.

Ainsi, la classe principale du module est nommée eniblog et étend donc la classe Module. L’usage du camel case est suggéré mais non obligatoire, il est avant tout utile à la lecture.

Le fichier eniblog.php situé dans le répertoire /modules/eniblog contient ceci :

<?php 
declare(strict_types=1); 
 
if (!defined('_PS_VERSION_')) { 
    exit; 
} 
 
class eniblog extends Module 
{ 
    public function __construct() 
    { 
        $this->name...

1. Méthode install()

Cette méthode est appelée par PrestaShop lors de l’installation d’un module.

Elle permet de définir une série d’actions à réaliser par défaut lors de l’installation, comme l’ajout de tables, de variables de configuration ou encore l’enregistrement de points d’accroche de votre module.

public function install() 
{ 
    return 
        parent::install() 
        // Enregistrement des points d'accroche 
        // Traitement des tables pour la base de données 
        && Configuration::updateValue('ENIBLOG_NB_ARTICLES', 10); 
} 

Par défaut, cette méthode procède également à l’installation des surcharges (vues au sein du chapitre Pour aller plus loin).

Lors de son déroulement, deux hooks sont appelés :

2. Méthode uninstall()

Lorsqu’un module est en cours de désinstallation, la méthode uninstall() est appelée par PrestaShop.

Celle-ci permet notamment à votre module de procéder à une série d’actions pour, par exemple, supprimer les tables ou variables de configuration ajoutées à l’installation du module.

public function uninstall() 
{ 
    return ...

1. Effectuer un rendu

Lorsque vous allez consulter la page qui se trouve derrière le bouton Configurer, le rendu est vide de contenu.

La méthode getContent() attend en retour une chaîne de caractères et se charge de restituer celle-ci au navigateur.

public function getContent() 
{ 
    return 'Page de configuration'; 
} 

Étant donné qu’un template Smarty compilé est à son tour une chaîne de caractères, il est également possible de restituer celui-ci en tant que rendu.

public function getContent() 
{ 
    return $this->context->smarty-> ...

1. Préambule

Les points d’accroche - autrement nommés hooks - sont des portes ouvertes à l’affichage d’un module à un endroit prédéfini ou encore à l’exécution d’une action à un moment donné.

Les hooks d’action tels que actionCartSave ou encore actionCategoryDelete sont déclenchés lorsqu’une action précise se déroule.

Les hooks d’affichage (display) tels que displayFooter ou displayHome permettent quant à eux de venir placer du code (HTML, mais également JavaScript ou CSS) sur la partie visible, aussi bien en front-office que back-office. 

Enfin, divers hooks comme moduleRoutes ou actionDispatcher permettent de modifier le système natif sans en altérer ses fichiers.

L’utilisation des points d’accroche est plus largement vue dans le chapitre Au cœur de PrestaShop - Hooks.

2. Alias

Les alias permettent d’utiliser l’ancien nom d’un hook lorsque celui-ci change de nom au sein du code principal de PrestaShop.

Pour exemple, le nom du hook displayHeader remplace le hook header.

Il est donc possible d’utiliser les deux noms indifféremment.

3. Enregistrement d’un hook

Positionner un module sur un point d’accroche peut se faire à tout moment, tant que ce dernier est installé.

Via le code

Dans un contexte...

1. Introduction

Au sein du chapitre Au cœur de PrestaShop, une introduction à la classe ObjectModel a été réalisée.

Les spécifications et spécificités relatives à cette classe ne sont pas reprises dans cette section.

Le module conçu durant ce chapitre devant stocker des données relatives à un élément, il est toutefois nécessaire de lui définir un à plusieurs ObjectModel.

2. Définition du modèle

La structure d’une table issue de la base de données définit le modèle.

Les tables dérivées ayant le suffixe _lang et _shop sont des tables issues du même modèle.

Le nom du modèle est libre. On essaie toutefois de le créer de manière évocatrice.

Chaque colonne de la table se représente par une propriété de la classe.

La définition est retranscrite dans la propriété statique du même nom ($definition) sous forme de tableau reprenant le nom de la table, l’identifiant du champ primaire ainsi que les différents champs constituant le modèle. 

<?php 
 
class BlogCategory extends ObjectModel 
{ 
    /** @var int BlogCategory ID */ 
    public $id_blog_category; 
 
    /** @var bool active */ 
    public $active; 
 
    /** @var string title */ 
    public $title; 
 
    /** @var string Object creation date */ 
    public $date_add; 
 
    /** @var string Object last modification date */ 
    public $date_upd; 
 
    /** 
     * @see ObjectModel::$definition 
     */ 
    public static $definition = [ 
        'table' => 'blog_category', 
        'primary' => 'id_blog_category', 
        'multilang_shop' => true, 
        'fields' => [ 
            'active'    => [ 
                'type' => self::TYPE_BOOL, 
                'validate' => 'isBool' 
            ], 
            'date_add'  => [ 
                'type' => self::TYPE_DATE, 
                'validate'...

1. Introduction

Les contrôleurs ont la charge de traiter la requête de l’utilisateur afin de faire appel au modèle de données et d’effectuer le rendu des données obtenues mises en forme.

2. Front-office

Un contrôleur front-office permet de présenter les données à l’utilisateur de votre boutique.

Chaque contrôleur est représenté par une classe unique définie dans un fichier devant respecter les règles suivantes :

Sur la base de ces règles, créez le fichier blog.php que vous placez dans le dossier controllers/front et dans lequel vous déclarez la classe correspondante.

<?php 
class EniBlogBlogModuleFrontController extends ModuleFrontController {} 

L’accès à cette URL provoque une erreur concernant la vue.

Afin de définir la vue utilisée par votre contrôleur, vous pouvez définir sa propriété spécifique directement ou bien utiliser une méthode à cet effet.

<?php 
class EniBlogBlogModuleFrontController extends ModuleFrontController 
{ 
    protected $template = 
'module:eniblog/views/templates/front/blog.tpl'; 
 
    public function __construct() 
    { 
        parent::__construct(); 
 
        $this->setTemplate('module:eniblog/views/templates/front/
blog.tpl'); 
    } 
} 

Votre vue est ensuite ajoutée et étend le layout défini pour cette page, communiqué par la variable $layout par PrestaShop.

{* /modules/eniblog/views/templates/front/blog.tpl *} 
{extends file=$layout} 

Au sein d’un contrôleur front-office, vous avez accès à sa propriété $module ayant pour valeur une instance du module associé au contrôleur.

public function hookModuleRoutes($params) 
{ 
    $customRoutes = []; 
 
    $customRoutes['module-' . $this->name . '-blog'] = [ 
        'controller' => 'blog', 
        'rule' => 'blog', 
        'keywords' => [], 
        'params'...

1. Préambule

Les modules disposent de deux systèmes de traduction :

2. Système legacy

Le système legacy, présent depuis la création de PrestaShop se base sur l’utilisation de fichiers PHP dans lesquels sont contenus des tableaux reprenant le message localisé.

Il se présente comme suit :

# translations/fr.php 
 
<?php 
global $_MODULE; 
$_MODULE = []; 
$_MODULE['<{psgdpr}prestashop>psgdpr_5966265f35dd87febf4d59029bc9ef66'] 
= 'RGPD Officiel '; 

L’utilisation de ce système s’effectue par le biais des méthodes l() disponibles dans les différentes classes utiles (Module, ModuleAdminController, ModuleFrontController…) ou encore via l’utilisation de la fonction {l} dans un template Smarty.

// Dans un fichier PHP 
$this->l('Your message'); 
 
// Dans un fichier PHP nommé SpecificFile 
$this->module->l('Your message', 'SpecificFile'); 
 
// Dans un template 
{l s='Your message' mod='enitests'} 

Il n’existe pas de méthode utilitaire pour un template Twig et il n’est pas supporté dans un contrôleur moderne.

Créer le dictionnaire

Pour créer le dictionnaire, autrement dit pour procéder à la traduction du module, cela se passe dans la gestion...

1. Préambule

Le service est un objet PHP, une classe ayant pour objectifs une à plusieurs tâches déterminées.

Aussi bien Symfony que le bundle PrestaShop embarquent différents services.

On retrouve ainsi des services servant à la traduction, à la gestion des configurations ou encore à la création de logs d’erreurs.

La création d’un module permet également l’ajout de services.

2. Ajouter un service

Pour rajouter un service, il faut tout d’abord écrire l’objet PHP servant à le décrire. La classe implémentée n’a pas besoin d’étendre une interface spécifique.

Dans le cadre de ce module de blog, il peut être judicieux d’avoir un service permettant de trouver un ensemble d’articles de blog correspondant à un terme de recherche saisi par l’utilisateur.

Le fichier est placé dans /src/Services/et se nomme ExampleService.php.

En voici son ébauche :

<?php 
namespace Eni\Blog\Services; 
 
use Symfony\Component\Translation\TranslatorInterface; 
 
class SearchService { 
    /** @var TranslatorInterface */     private $translator; 
 
    /** 
@param TranslatorInterface $translator 
     */ 
    public function __construct( 
        TranslatorInterface $translator 
    ) { 
        $this->translator = $translator; 
    } 
 
    /** 
@return string 
     */ 
    public function getNoResultsMessage() { 
        return $this->translator->trans('There are no results 
matching your query', [], 'Modules.Eniblog'); 
    } 
} 

Maintenant que le service est prêt à être utilisé, il est temps d’en déclarer l’existence, au moyen du fichier de configuration prévu à cet effet.

C’est ainsi le fichier /config/services.yml qui sert à rendre le service utilisable dans son applicatif.

services: 
  _defaults: 
    public: true 
    eni.blog.search: ...

1. Définition de la grille

Une grille se compose de plusieurs paramètres, dont l’identifiant et le nom.

Les colonnes, filtres et actions terminent de définir pleinement une grille.

C’est ainsi que la définition d’une grille représentant les catégories de blog peut se retranscrire :

#/src/Grid/Definition/Factory/BlogCategoryGridDefinitionFactory.php 
 
<?php 
namespace Eni\Blog\Grid\Definition\Factory; 
 
use PrestaShop\PrestaShop\Core\Grid\Action\Row\RowActionCollection; 
use PrestaShop\PrestaShop\Core\Grid\Action\Row\Type\LinkRowAction; 
use PrestaShop\PrestaShop\Core\Grid\Action\Row\Type\SubmitRowAction; 
use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection; 
use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ActionColumn; 
use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ToggleColumn; 
use PrestaShop\PrestaShop\Core\Grid\Column\Type\DataColumn; 
use PrestaShop\PrestaShop\Core\Grid\Definition\Factory\
AbstractGridDefinitionFactory; 
 
final class BlogCategoryGridDefinitionFactory extends  
AbstractGridDefinitionFactory 
{ 
    const GRID_ID = 'blog_category'; 
 
    protected function getId() 
    { 
        return self::GRID_ID; 
    } 
 
    protected function getName() 
    { 
        return $this->trans('Categories', [], 'Modules.Eniblog.Admin'); 
    } 
 
    protected function getColumns() 
    { 
        return (new ColumnCollection()) 
            ->add((new DataColumn('id_blog_category')) 
                ->setName($this->trans('ID', [], 'Admin.Global')) 
                ->setOptions([ 
                    'field' => 'id_blog_category', 
                ]) 
            ) 
            ->add((new DataColumn('title')) 
                ->setName($this->trans('Title'...

1. Conception du formulaire

La composition d’un formulaire repose sur quatre éléments, chacun étant responsable d’opérer sa tâche respective.

On retrouve :

Type

La représentation d’un type, servant ainsi à sa définition, est l’ensemble des champs utilisés pour pouvoir donner l’ensemble des informations nécessaires à son enregistrement.

PrestaShop propose une longue liste de types, allant du color picker au champ de texte relatif à une adresse IP.

Lorsque votre formulaire concerne un élément bien précis et qu’il vous est possible d’utiliser un type existant, il est vivement suggéré de ne pas créer le vôtre.

Ajoutons toutefois un nouveau type nous permettant d’associer l’ensemble des champs nécessaires à l’enregistrement d’une catégorie pour notre module de blog.

<?php 
 
namespace Eni\Blog\Form; ...

1. Introduction

Les commandes de console sont des services permettant d’interagir avec votre application en ligne de commande CLI (Command Line Interface).

Dans le chapitre Au cœur de PrestaShop - Console plusieurs commandes issues du bundle PrestaShop ont été évoquées.

Par le biais d’un module, vous êtes en mesure d’ajouter vos propres commandes afin notamment d’effectuer des actions d’export.

2. Définir une commande

La commande est un objet PHP qui doit étendre la classe Symfony\Component\Console\Command\Command.

Votre objet doit par ailleurs implémenter deux méthodes :

Vous pourriez ainsi obtenir une commande d’export des articles de blog suivant la définition suivante.

 <?php 
namespace Eni\Blog\Command; 
 
use Symfony\Component\Console\Command\Command; use  
Symfony\Component\Console\Input\InputInterface; use  
Symfony\Component\Console\Output\OutputInterface; 
 
class ExportCommand extends Command 
{ 
    protected function configure() 
    { 
        $this 
            // Configuration du nom 
            ->setName('eniblog:export') ...

1. Création des commandes

Afin de pouvoir utiliser des commandes, il est tout d’abord nécessaire de les implémenter.

Ajoutons en premier lieu une commande pour la création.

<?php 
# /src/Command/AddBlogCategoryCommand.php 
 
namespace Eni\Blog\Command; 
 
/** 
 * 
 */ 
class AddBlogCategoryCommand 
{ 
    /** 
     * @var bool 
     */ 
    private $active; 
 
    /** 
     * @var string[] 
     */ 
    private $title; 
 
    /** 
     * @var string[] 
     */ 
    private $description; 
 
    /** 
     */ 
    public function __construct(bool $active, array $title, 
array $description) 
    { 
        $this->active = $active; 
        $this->title = $title; 
        $this->description = $description; 
    } 
 
    /** 
     * @return bool 
     */ 
    public function getActive() 
    { 
        return $this->active; 
    } 
 
    /** 
     * @return string[] 
     */ 
    public function getTitle() 
    { 
        return $this->title; 
    } 
 
    /** 
     * @return string[] 
     */ 
    public function getDescription() 
    { 
        return $this->description; 
    } 
} 

Procédons ensuite à l’ajout de la commande d’édition, qui est identique à la précédente, à la nuance près qu’elle a une propriété de plus permettant de gérer l’identifiant de l’entité.

<?php 
# /src/Command/EditBlogCategoryCommand.php 
 
namespace Eni\Blog\Command; 
 
/** 
 * 
 */ 
class EditBlogCategoryCommand ...

1. Module de paiement

Les modes de paiement associés à une boutique le sont obligatoirement par l’utilisation d’un module. Il n’est pas possible d’ajouter de nouveau mode de paiement manuellement.

a. Déclaration d’un module comme module de paiement

Pour que votre module devienne un module de paiement, il doit étendre la classe PaymentModule, qui étend à son tour la classe Module.

<?php 
// PaymentModule étend Module 
class EniPayments extends PaymentModule 
{ 
    public function install() 
    { 
        $hooks = [ 
            'paymentOptions', 
            'displayPaymentReturn', 
        ]; 
 
        return 
            parent::install() 
            && $this->registerHook($hooks); 
    } 
 
} 

La classe PaymentModule embarque un ensemble de propriétés et de méthodes utiles à cet effet.

Les propriétés $currencies et $currencies_mode vous permettent de définir des restrictions sur les modes de paiement en fonction des devises.

Le mode de restriction peut être défini via des cases à cocher (checkbox) ou un sélecteur unique (radio).

Le premier cas permet d’associer plusieurs devises à un mode de paiement tandis que le second cas de figure force cette association à une devise unique.

Ces éléments sont définis sur le module et non sur un mode de paiement.

Les modules de paiement peuvent également être restreints en fonction du groupe de clients, d’un pays ou encore d’un transporteur utilisé pour le panier courant.

$option = new \PrestaShop\PrestaShop\Core\Payment\PaymentOption(); 
 
$option->setCallToActionText($this->l('Mode de paiement')); 
 
$option->setAction($actionLink); 
); 

$option ->setLogo(Media::getMediaPath(_PS_MODULE_DIR_.$this-> 
name.'/payment.jpg')); 

1. Préambule

Vue.js est un framework JavaScript reposant sur l’utilisation de composants et qui ne requiert pas de configurations serveurs spécifiques, permettant ainsi de l’utiliser dans un module PrestaShop, notamment dans la partie Back End.

Son utilisation n’est pas fort répandue mais, toutefois, de nombreux modules officiels développés par PrestaShop s’appuient dessus.

Il s’agit principalement des modules de la gamme PS Essentials (Checkout, Metrics…) ou encore le module Blockwishlist.

Voici la raison pour laquelle une introduction rapide à son implémentation dans un module est énoncée dans cet ouvrage.

2. Créer son application

La documentation officielle de Vue.js donne plusieurs possibilités concernant son installation, notamment son importation par le biais de la balise <script> de votre document.

Cette implémentation rapide à mettre en œuvre est utile pour des tests rapides. 

Toutefois, nous allons privilégier une méthode d’installation préconisée par PrestaShop lors de développements plus conséquents..

L’installation se fera donc par le biais de NPM, en ligne de commande.

Procédez à l’installation de Vue.js CLI de la sorte :

npm install -g @vue/cli 

Une fois cette installation réalisée, il est désormais possible d’initialiser une application rapidement :

vue create _dev 

Il est possible que Vue.js CLI vous retourne une erreur due à l’utilisation du caractère _ dans le nom de l’application. Dans ce cas, retirez-les. Vous pourrez le rajouter ensuite au dossier créé.

Il vous est demandé de choisir la version de Vue pour votre application.

L’exemple illustré se repose sur Vue 2.

En vous rendant dans le dossier _dev désormais rempli de fichiers constituant votre application, vous pouvez compiler votre application.

npm run build 

L’application construite étant indépendante, vous pourriez ouvrir celle-ci par le biais du script serve.

3. Nettoyer son installation

Avant de poursuivre à proprement parler le développement de son application, il est tout d’abord nécessaire de faire un tri dans certains éléments de celle-ci relatifs à une utilisation indépendante.

Pour cela, supprimez le dossier _dev/public...