Création de promotion personnalisée avec Sylius

Imaginons que vous ayez un site e-commerce qui utilise Sylius.
Il y a un système de promotion à mettre en place. Cette promotion sera appliquée sur tout le site et ne devra pas être modifiable. Elle aura une logique métier complètement personnalisée et dépendra de règles métier spécifiques¹.

Vous pourriez définir des promotions avec les règles de promotion proposés par défaut et les lier à des actions. Cependant, cette façon de fonctionner ne s’applique pas vraiment avec les règles de promotion présentes de base dans Sylius :

• Quantité dans le panier
• Groupe de clients
• N-ième commande
• Pays de livraison
• A au moins un des taxons
• Prix total des Articles du taxon
• Contient le produit
• Total produit

La manière que je propose dans cet article est découpé en 5 partie :

Créer le Vérificateur d’éligibilité

Il faut maintenant créer le vérificateur d’éligibilité. C’est une classe qui va dire si oui ou non l’objet passé en paramètre² est eligible a la promotion. Dans notre cas, nous allons autoriser la promotion que si l’utilisateur est un utilisateur qui a un compte sur le site.

<?php

declare(strict_types=1);

namespace App\Promotion\Checker\Eligibility;

use App\Entity\Order\Order;
use App\Entity\Promotion\Promotion;
use Sylius\Component\Promotion\Checker\Eligibility\PromotionEligibilityCheckerInterface;
use Sylius\Component\Promotion\Exception\UnsupportedTypeException;
use Sylius\Component\Promotion\Model\PromotionInterface;
use Sylius\Component\Promotion\Model\PromotionSubjectInterface;

class DefaultPromotionEligibilityChecker implements PromotionEligibilityCheckerInterface
{
    public function isEligible(PromotionSubjectInterface $promotionSubject, PromotionInterface $promotion): bool
    {
        if (!$promotionSubject instanceof Order) {
            throw new UnsupportedTypeException($promotionSubject, Order::class);
        }

        if ($promotion->getCode() !== Promotion::DEFAULT_PROMOTION_CODE) {
            return false;
        }

        /** @var \App\Entity\Customer\Customer|null $customer */
        $customer = $promotionSubject->getCustomer();
        // is elligible if the customer is a customer
        return $customer !== null;
    }
}

Maintenant que le vérificateur est crée, il faut l’ajouter au fichier services.yaml pour qu’il soit pris en compte par le PromotionProcessor

services:  
  app.default_promotion_eligibility_checker:
    class: App\Promotion\Checker\Eligibility\DefaultPromotionEligibilityChecker
    public: false
    tags:
      - { name: sylius.promotion_eligibility_checker }

PromotionProcessor

Le PromotionProcessor est une classe qui va parcourir et executer tous les vérificateur d’éligibilité jusqu’à trouver le premier renvoyant true pour l’object actuel. Si aucun n’est trouvé, alors on arrête la logique de promotion, car rien n’est applicable.

<?php

/*
 * This file is part of the Sylius package.
 *
 * (c) Sylius Sp. z o.o.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Sylius\Component\Promotion\Processor;

// ...

final class PromotionProcessor implements PromotionProcessorInterface
{
    public function __construct(
        private PreQualifiedPromotionsProviderInterface $preQualifiedPromotionsProvider,
        private PromotionEligibilityCheckerInterface $promotionEligibilityChecker,
        private PromotionApplicatorInterface $promotionApplicator,
    ) {
    }

    public function process(PromotionSubjectInterface $subject): void
    {
		// ...

        $preQualifiedPromotions = $this->preQualifiedPromotionsProvider->getPromotions($subject);

        foreach ($preQualifiedPromotions as $promotion) {
            if ($promotion->isExclusive() && $this->promotionEligibilityChecker->isEligible($subject, $promotion)) {
                $this->promotionApplicator->apply($subject, $promotion);

                return;
            }
        }

        // ...
    }
}

Ce qui nous intéresse ici est PromotionEligibilityCheckerInterface. Par défaut Sylius va aller choisir la classe CompositePromotionEligibilityChecker pour implémenter cette interface. Cette classe va ensuite itérer sur tous les classes implémentant PromotionEligibilityCheckerInterface, dont notre vérificateur d’éligibilité fait parti. Il sera donc appelé via la méthode isEligible($promotionSubject, $promotion).

<?php

declare(strict_types=1);

namespace Sylius\Component\Promotion\Checker\Eligibility;

// ...

final class CompositePromotionEligibilityChecker implements PromotionEligibilityCheckerInterface
{
    /** @var PromotionEligibilityCheckerInterface[] */
    private array $promotionEligibilityCheckers;

    // ...

    public function isEligible(PromotionSubjectInterface $promotionSubject, PromotionInterface $promotion): bool
    {
        foreach ($this->promotionEligibilityCheckers as $promotionEligibilityChecker) {
            if (!$promotionEligibilityChecker->isEligible($promotionSubject, $promotion)) {
                return false;
            }
        }

        return true;
    }
}

Le PromotionApplicator

Le PromotionApplicator est utilisé par le PromotionProcessor. Le PromotionProcessor reçoit un PromotionApplicatorInterface dans son constructeur lors de l’injection de dépendance. Par défaut cette interface est instanciée par la classe PromotionApplicator ci-dessous :

<?php
// ...

final class PromotionApplicator implements PromotionApplicatorInterface
{
    public function __construct(private ServiceRegistryInterface $registry)
    {
    }

    public function apply(PromotionSubjectInterface $subject, PromotionInterface $promotion): void
    {
        $applyPromotion = false;
        foreach ($promotion->getActions() as $action) {
            $result = $this->getActionCommandByType($action->getType())->execute($subject, $action->getConfiguration(), $promotion);
            $applyPromotion = $applyPromotion || $result;
        }

        if ($applyPromotion) {
            $subject->addPromotion($promotion);
        }
    }

    public function revert(PromotionSubjectInterface $subject, PromotionInterface $promotion): void
    {
        // ...
    }

    private function getActionCommandByType(string $type): PromotionActionCommandInterface
    {
        return $this->registry->get($type);
    }
}

On voit dans la classe que la méthode apply() a besoin de récupérer les actions de la promotion. Les actions sont définies dans la base de données. Elles peuvent être par exemple :

• Remise sur la commande
• Remise fixe produit
• Rabais en pourcentage commande
• Rabais en pourcentage produit
• Rabais en pourcentage expédition

Cependant nous n’en avons pas défini. Nous avons une logique métier qui est plus complexe et nécessite de récupérer les infos de la base de données pour savoir quelle montant de remise appliquer en fonction de quel produit.

Il est possible aussi d’attribuer une action via l’interface ou via notre commande de création de promotion, cependant cela n’a pas trop de sens, alors autant rester sur la promotion utilisant des règles et des actions.

Décorer l’applicateur

Dans notre cas, comme nous ne définissons pas d’action sur notre promotion, il faut un moyen d’appliquer quand même notre logique. Si elle n’est pas applicable dans le contexte courant, alors on retombe par défaut sur la logique de PromotionApplicator de Sylius. Pour cela nous allons décorer le PromotionApplicator de Sylius avec notre propre classe.
En faisant un bin/console debug:container PromotionApplicatorInterface de PromotionApplicator, on peut voir que Sylius lui attribut l’alias sylius.promotion_applicator. Nous allons donc utiliser cette alias pour référencer notre classe décorée.

Pour cela on va venir ajouter l’attribut AsDecorator disponible depuis Symfony 6.1. On lui passe l’alias en paramètre, et cela nous permet de récupérer le PromotionApplicator de Sylius directement dans notre constructeur. On vient rajouter notre logique dans la fonction apply() et revert() si on est sur une commande et sur la bonne promotion. Si non, on appelle notre classe décorée pour revenir au comportement de base de Sylius.

<?php

declare(strict_types=1);

namespace App\Promotion\Action;

use App\Entity\Order\Order;
use App\Entity\Promotion\Promotion;
use Sylius\Component\Promotion\Action\PromotionApplicatorInterface;
use Sylius\Component\Promotion\Model\PromotionInterface;
use Sylius\Component\Promotion\Model\PromotionSubjectInterface;
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;

#[AsDecorator('sylius.promotion_applicator')]
final readonly class DefaultPromotionApplicator implements PromotionApplicatorInterface
{
    public function __construct(
        private PromotionApplicatorInterface $promotionApplicator,
        #[Autowire(service: 'sylius.factory.adjustment')]
        private readonly FactoryInterface $adjustmentFactory,
    ) {
    }

    public function apply(PromotionSubjectInterface $subject, PromotionInterface $promotion): void
    {
        if ($subject instanceof Order && $promotion->getCode() === Promotion::DEFAULT_PROMOTION_CODE) {
        	/**
        	 * TODO :
        	 * Il reste a implémenter la logique métier, par exemple en injectant le repository d'un model
        	 * et en faisant des requêtes permettant de savoir si des remises sont disponibles pour le panier 
        	 * courant. Si oui, appliquer des modifications au panier suivant ces règles
        	 * 
        	 */

        	$amount = // ...


	        $adjustment = $this->adjustmentFactory->createNew();
	        $adjustment->setType(AdjustmentInterface::ORDER_PROMOTION_ADJUSTMENT);
	        $adjustment->setAmount($amount);
	        $adjustment->setNeutral(false);
	        $adjustment->setLabel('Test Promotion Adjustment');
	        $order->addAdjustment($adjustment);

            return;
        }

        $this->promotionApplicator->apply($subject, $promotion);
    }

    public function revert(PromotionSubjectInterface $subject, PromotionInterface $promotion): void
    {
        if ($subject instanceof Order && $promotion->getCode() === Promotion::DEFAULT_PROMOTION_CODE) {
        	/**
        	 * TODO :
        	 * Il reste a implémenter la logique métier, par exemple en injectant le repository d'un model
        	 * et en faisant des requêtes permettant de savoir si des remises sont disponibles pour le panier 
        	 * courant. Si oui, appliquer des modifications au panier suivant ces règles
        	 * 
        	 */

            return;
        }

        $this->promotionApplicator->revert($subject, $promotion);
    }
}