JoliMediaSyliusBundle, un nouveau bridge pour vos projets Sylius

This blog post is also available in 🇬🇧 English: JoliMediaSyliusBundle, a New Bridge for Your Sylius Projects.

Est-il encore nécessaire de présenter l’excellent framework E-commerce Sylius ?

Si Sylius s’est imposé dans l’écosystème e-commerce, c’est notamment grâce à sa capacité à s’adapter à des besoins métier très variés sans imposer une architecture rigide. Son système d’extensions permet de faire évoluer progressivement les fonctionnalités tout en conservant les mécanismes du cœur du framework.

Fin d’année dernière, nous avons lancé le JoliMediaBundle, un bundle Symfony dédié à la gestion de bibliothèques de medias.

Il était déjà accompagné de deux bridges pour SonataAdmin et EasyAdmin.

Section intitulée la-genese-du-bridgeLa Genèse du bridge

Récemment arrivé chez JoliCode et expert Sylius, j’ai rapidement engagé des discussions autour de l’intégration du MediaBundle dans cet écosystème. C’est ainsi qu’est née l’idée de ce nouveau bridge, visant à connecter harmonieusement la gestion des médias avec Sylius.

Section intitulée la-gestion-des-medias-dans-syliusLa gestion des médias dans Sylius

Avant d’introduire ce nouveau bridge, il est utile de faire un état des lieux de la gestion des médias dans Sylius aujourd’hui.

Par défaut, Sylius propose un système simple mais efficace pour associer des images aux principales ressources du catalogue, comme les produits ou les taxons. Cette gestion repose sur des entités d’images directement liées aux ressources, avec quelques métadonnées basiques (type, position, etc.).

Cette approche répond parfaitement aux besoins classiques d’un site e-commerce : illustrer un produit, afficher des visuels de catégories, ou encore gérer des galeries simples.

En revanche, certaines limites apparaissent dès que les besoins deviennent plus transverses. Notamment :

• la difficulté à réutiliser facilement un même média à plusieurs endroits sans duplication ;
• l’absence d’une organisation centralisée des fichiers (dossiers, tags, recherche…) ;
• une gestion éclatée des médias, propre à chaque ressource.

En pratique, chaque entité embarque ses propres fichiers, ce qui fonctionne bien à petite échelle mais devient rapidement contraignant dès que le volume de médias augmente ou que plusieurs équipes interviennent.

Section intitulée le-bridge-sylius-et-jolimediabundleLe bridge Sylius et JoliMediaBundle

C’est précisément ce constat qui a motivé la réflexion autour d’une gestion des médias plus centralisée et réutilisable au sein de l’écosystème Sylius, en s’appuyant sur le JoliMediaBundle développé chez JoliCode. Pour répondre à ces limites, nous avons développé le bridge Sylius pour ce bundle. L’objectif n’est pas de modifier le fonctionnement de Sylius ni de réécrire sa gestion des médias, mais d’y ajouter une couche d’intégration propre, basée sur ses mécanismes d’extension.

Dans un projet Sylius, les médias sont utilisés dans les images produit, les images de taxons et les avatars administrateurs. Ces usages sont bien intégrés au modèle natif mais restent isolés les uns des autres. Le bridge vient enrichir ce fonctionnement en introduisant une médiathèque centralisée.

Il est également pensé pour être compatible avec la Sylius Stack au sens large, et pas uniquement avec un contexte e-commerce. Il peut ainsi s’intégrer dans des back-offices Sylius utilisés comme base d’application, où la gestion de médias est un besoin transverse à plusieurs domaines fonctionnels. Cela permet d’utiliser la même approche de médiathèque centralisée dans des projets plus généraux construits avec Sylius.

Concrètement, l’approche repose sur des extensions simples et ciblées :

• extension des entités Sylius concernées lorsque cela est nécessaire ;
• remplacement des champs de formulaire dans le back-office pour utiliser le sélecteur de médias du JoliMediaBundle ;
• intégration progressive via les points d’extension fournis par Sylius.

Cette stratégie permet de conserver les usages métier actuels tout en introduisant une gestion plus cohérente et réutilisable des médias. Chaque image (produit, taxon, administrateur) garde son rôle, mais s’inscrit désormais dans une logique commune de médiathèque.

L’intégration reste volontairement discrète : le bridge agit comme une surcouche qui s’insère dans l’écosystème Sylius sans en modifier les fondations.

C’est cette approche progressive qui rend l’adoption possible dans un projet existant, sans refonte du modèle de données ni rupture fonctionnelle.

La question devient alors plus concrète : comment ce bridge s’insère-t-il techniquement dans Sylius, et quels sont les mécanismes utilisés pour relier proprement la médiathèque au modèle existant ?

Section intitulée une-integration-simple-dans-syliusUne intégration simple dans Sylius

Lorsque vous avez installé le Media bundle, il faut activer le bridge Sylius :

// filepath: config/bundles.php
return [
    // ...
    JoliCode\MediaBundle\Bridge\Sylius\JoliMediaSyliusBundle::class => ['all' => true],
];

Ensuite, on active les routes pour le back-office :

# filepath: config/routes/joli_media.yaml
_joli_media_sylius:
    resource: "@JoliMediaSyliusBundle/src/Admin/Controller/"
    prefix: /admin/media

Et enfin, on importe la configuration du package :

# filepath: config/packages/joli_media_sylius.yaml
imports:
    - { resource: "@JoliMediaSyliusBundle/config/app.php" }

L’idée est de s’appuyer sur les mécanismes d’extension classiques de Symfony et Sylius, afin de rester le moins intrusif possible.

Section intitulée un-trait-reutilisable-pour-les-mediasUn trait réutilisable pour les médias

La première brique consiste à utiliser un trait permettant d’ajouter une gestion de média à n’importe quelle entité métier :

Vous pouvez associer un média à une entité Doctrine Sylius, tout en conservant une logique simple côté domaine. Cela synchronisera le champ path existant dans Sylius.

Section intitulée extension-des-entites-syliusExtension des entités Sylius

Cette approche s’intègre naturellement aux entités existantes. Par exemple, pour les images produit :

namespace App\Entity\Product;

use Doctrine\ORM\Mapping as ORM;
+use JoliCode\MediaBundle\Bridge\Sylius\Doctrine\ORM\EntityWithMediaImageTrait;
use Sylius\Component\Core\Model\ProductImage as BaseProductImage;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_product_image')]
class ProductImage extends BaseProductImage
{
   +use EntityWithMediaImageTrait;
}

On étend ainsi une entité Sylius sans en modifier le cœur, en ajoutant uniquement la capacité de manipuler un média via le bundle.

Section intitulée integration-dans-le-back-officeIntégration dans le back-office

Enfin, côté administration, l’intégration passe par une extension de formulaire Sylius. Le champ fichier natif est remplacé par un composant dédié au JoliMediaBundle :

class ProductImageTypeExtension extends AbstractTypeExtension
{
   public function buildForm(FormBuilderInterface $builder, array $options): void
   {
       $builder->add('file', MediaChoiceType::class, [
           'property_path' => 'media',
       ]);
   }

   public static function getExtendedTypes(): iterable
   {
       yield ProductImageType::class;
   }
}

Cela permet de brancher directement la médiathèque dans l’interface d’administration Sylius, sans casser les formulaires existants.

Ces Forms extensions sont directement fournies par le bridge, il vous suffit de les déclarer dans Symfony:

# config/services.yaml
services:
   JoliCode\MediaBundle\Bridge\Sylius\Admin\Form\Extension\AvatarImageTypeExtension: null
   JoliCode\MediaBundle\Bridge\Sylius\Admin\Form\Extension\ProductImageTypeExtension: null
   JoliCode\MediaBundle\Bridge\Sylius\Admin\Form\Extension\TaxonImageTypeExtension: null

Le File input est remplacé par celui du Media bundle.

Pour les plus observateurs, vous pouvez remarquer que nous avons modifié le template pour retirer l’aperçu fourni par Sylius nativement.

La Médiathèque est le point fort du Media bundle. Elle permet de visualiser mais également d’organiser votre arborescence.

Une vue « Grid » est également disponible pour afficher les images en plus grand format.

Une page détails du media permet d’obtenir davantage d’informations ainsi que les options d’intégration.

Un onglet « Variations » est disponible afin de consulter les différentes variantes de vos médias, avec leurs tailles, formats et dimensions respectifs.

Il est ainsi possible d’utiliser le système de compression du JoliMediaBundle au lieu du système natif de Sylius (utilisant LiipImagine).

Remplaçons les images dans la liste des produits :

<?php

namespace App\Grid\Mutator;

use Sylius\Bundle\AdminBundle\Grid\ProductGridInterface;
use Sylius\Bundle\GridBundle\Builder\Field\TwigField;
use Sylius\Component\Grid\Builder\GridBuilderInterface;
use Sylius\Component\Grid\Attribute\AsGridMutator;
use Sylius\Component\Grid\Mutator\GridMutatorInterface;

#[AsGridMutator(
    grid: 'sylius_admin_product', 
    // ou
    grid: ProductGridInterface::NAME // constante ajoutée sur Sylius 2.3
)]
class ReplaceImageFromProductGridMutator implements GridMutatorInterface
{
    public function __invoke(GridBuilderInterface $gridBuilder): void
    {
        $gridBuilder
            ->withFields(
                TwigField::create('image', template: 'admin/product/grid/field/image.html.twig'),
            )
        ;
    }
}

Ainsi on remplace le field image en utilisant notre propre template Twig.

<!-- templates/admin/product/grid/field/image.html.twig ->
{% from '@JoliMediaSylius/admin/shared/helper/product_image.html.twig' import image %}


<div class="thumbnail-box-image">
   {{ image(data) }}
</div>

Le résultat est identique en apparence, mais on peut voir que l’image a été traitée par le JoliMediaBundle en y regardant de plus près :

Section intitulée utilisation-dans-le-shopUtilisation dans le shop

Le mécanisme cœur de Sylius n’étant pas modifié, les images continuent de fonctionner comme auparavant côté front. Elles peuvent donc être traitées directement par LiipImagine par défaut, sans nécessiter d’adaptation spécifique. Il n’est pas obligatoire, dans un premier temps, d’aller plus loin que cette intégration côté administration. Il est ensuite possible d’améliorer progressivement la qualité du rendu des images en effectuant les ajustements nécessaires côté front, comme décrit dans la documentation du bundle.

Section intitulée reorganiser-votre-mediathequeRéorganiser votre médiathèque

Un mécanisme de propagation des changements dans vos entités permet de déplacer ou renommer vos médias librement, sans casser les références existantes dans votre application. Cette approche facilite non seulement la recherche et l’identification des médias dans le back-office, mais également la réorganisation progressive de la médiathèque au fil du temps, que ce soit pour restructurer une arborescence, harmoniser des noms de fichiers ou regrouper certains médias par domaine fonctionnel.

Section intitulée conclusionConclusion

Sylius propose déjà une base solide pour la gestion des médias dans un contexte e-commerce. Le JoliMediaBundle apporte une vision plus transversale et structurée de la gestion des fichiers. Le bridge entre les deux ne cherche pas à opposer ces approches, mais à les faire coexister proprement. En pratique, cette combinaison permet de conserver la simplicité du modèle Sylius tout en introduisant une médiathèque centralisée, réutilisable et plus adaptée à des projets qui grandissent ou se complexifient. C’est aussi une manière de prolonger la philosophie même de Sylius : rester extensible, sans imposer de rigidité, tout en laissant la liberté d’adapter l’architecture aux besoins réels du projet.