Documentation DfStreamCategoryTree pour Shopware 6

DfStreamCategoryTree ajoute un champ Category (including subcategories) au constructeur de conditions des groupes de produits dynamiques de Shopware 6. Filtrer sur une catégorie parente inclut alors tous les produits rangés dans ses sous-catégories, quelle que soit la profondeur.

Le problème que le plugin résout

Le constructeur de conditions natif propose un champ Categories qui interroge la relation product.categoriesRo. Cette relation ne contient que les catégories auxquelles un produit est explicitement rattaché dans son onglet Categories.

Un catalogue correctement organisé range ses produits dans les catégories feuilles. Un modèle de sneakers est affecté à Homme / Chaussures / Sneakers, pas à Homme. Un filtre sur Homme ne retourne donc que les rares produits affectés directement à ce niveau, souvent aucun.

La solution native consiste à cocher manuellement chaque sous-catégorie, puis à rouvrir la configuration du stream à chaque évolution de l’arborescence. Ce plugin supprime cette maintenance.

Comment ça fonctionne

Shopware maintient déjà, pour chaque produit, un champ JSON nommé categoryTree qui contient l’identifiant de toutes les catégories du chemin, depuis la racine jusqu’à la catégorie d’affectation. Ce champ est recalculé par le CategoryIndexer natif à chaque déplacement de catégorie et à chaque changement d’affectation produit.

Un filtre equalsAny sur ce champ avec l’identifiant d’une catégorie parente remonte donc tous les produits dont le chemin passe par elle. Le champ existe et fonctionne parfaitement dans le DAL, mais l’administration ne l’expose pas dans le sélecteur du constructeur de conditions : il ne figure pas dans la liste d’autorisation du service productStreamConditionService.

Le plugin ajoute une entrée à cette liste d’autorisation et fournit les libellés traduits associés. Il n’introduit aucun décorateur de service, aucun listener sur les événements produit, aucune table et aucune migration.

Prérequis

• Shopware 6.7.x auto-hébergé
• PHP 8.2 ou supérieur
• Accès à la ligne de commande ou à un pipeline de déploiement capable de recompiler l’administration

Le plugin ne fonctionne pas sur Shopware Cloud, la version SaaS hébergée par Shopware n’autorisant pas l’installation de plugins serveur.

Installation

Par upload de ZIP

1. Dans l’administration, ouvrez Extensions puis Mes extensions
2. Cliquez sur Charger l’extension et sélectionnez l’archive DfStreamCategoryTree-1.0.0.zip
3. Installez puis activez le plugin
4. Recompilez l’administration (voir la section suivante)

Par dépôt du dossier

Décompressez l’archive dans le répertoire des plugins personnalisés de votre instance, puis exécutez :

bin/console plugin:refresh
bin/console plugin:install --activate DfStreamCategoryTree
bin/console cache:clear

Recompilation de l’administration

Le plugin modifie le comportement de l’interface d’administration. Une recompilation du bundle admin est nécessaire une fois après l’installation, sans quoi le nouveau champ n’apparaîtra pas dans le sélecteur de conditions.

bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear

Sur un environnement de production géré par un pipeline de déploiement, cette étape fait généralement déjà partie du processus standard. Videz ensuite le cache de votre navigateur ou ouvrez l’administration dans une fenêtre privée pour être certain de charger le bundle à jour.

Utilisation

Créer un groupe dynamique récursif

1. Ouvrez Catalogues puis Dynamic product groups
2. Créez un nouveau groupe ou ouvrez un groupe existant
3. Dans le constructeur de conditions, déroulez le sélecteur de champ
4. Choisissez Category (including subcategories), juste au-dessus de l’entrée Categories d’origine
5. Sélectionnez l’opérateur Is equal to any of
6. Choisissez une ou plusieurs catégories parentes dans le champ de valeur
7. Enregistrez, puis ouvrez l’onglet Preview pour vérifier le nombre de produits retournés

Opérateurs disponibles

• Is equal to any of : le produit appartient au sous-arbre d’au moins une des catégories sélectionnées
• Is not equal to any of : le produit n’appartient au sous-arbre d’aucune des catégories sélectionnées, utile pour exclure un rayon entier d’une opération commerciale

Combiner avec d’autres conditions

Le champ se comporte comme n’importe quelle autre condition du stream. Il se combine librement avec le fabricant, le prix, l’état du stock, les propriétés, les tags, et s’utilise dans les groupes AND et OR imbriqués du constructeur.

Exemple de configuration typique pour une opération de déstockage : Category (including subcategories) is equal to any of Homme, ET Stock is greater than 0, ET Price is greater than 50.

Où le groupe est utilisable

• Page de catégorie de navigation alimentée par un groupe dynamique
• Blocs de produits dans les Shopping Experiences
• Conditions de règles de promotion
• Cross-selling automatique sur la fiche produit
• Toute intégration consommant un product stream via l’Admin API ou la Store API

Utilisation via l’Admin API

Le champ étant natif au DAL, une condition posée directement en API fonctionne même sans le plugin. Le plugin sert à rendre ce filtre visible et modifiable dans l’interface, ce qui compte dès qu’une équipe marketing gère les groupes sans passer par l’API.

POST /api/product-stream
{
  "name": "Tout le rayon Homme",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Sans le plugin installé, un stream contenant ce filtre reste fonctionnel côté DAL mais son champ n’est pas affichable dans le constructeur de conditions.

Dépannage

Le champ n’apparaît pas dans le sélecteur

Dans l’immense majorité des cas, l’administration n’a pas été recompilée après l’installation. Relancez la séquence bundle:dump, build-administration puis cache:clear, et rechargez l’administration en vidant le cache navigateur. Vérifiez aussi que le plugin est bien actif dans Extensions puis Mes extensions.

Le groupe ne retourne toujours pas les bons produits

Vérifiez que vous avez bien sélectionné le nouveau champ et non l’entrée Categories d’origine, les deux coexistant dans le sélecteur. Vérifiez ensuite dans la fiche d’un produit attendu que celui-ci est bien affecté à une sous-catégorie du parent choisi, et qu’il est actif et visible sur le canal de vente concerné.

Un produit récemment déplacé ne remonte pas

Le champ categoryTree est recalculé par le CategoryIndexer natif. Si la file de messages est en retard ou si l’indexation a été mise en pause, forcez une réindexation :

bin/console dal:refresh:index --only=product.indexer,category.indexer

Réinitialiser après une mise à jour majeure de Shopware

Après une montée de version mineure de Shopware, recompilez l’administration pour que le plugin réenregistre son entrée dans la liste d’autorisation. Aucune autre action n’est nécessaire, le plugin ne stockant aucune donnée.

Désinstallation

Désactivez puis désinstallez le plugin depuis Extensions ou en ligne de commande. Le plugin ne crée aucune table et ne stocke aucune configuration, la désinstallation est donc entièrement neutre.

bin/console plugin:deactivate DfStreamCategoryTree
bin/console plugin:uninstall DfStreamCategoryTree

Les groupes dynamiques déjà configurés avec le filtre continuent de fonctionner : la condition est stockée en base sous forme de filtre DAL standard et reste évaluée par le moteur natif. Seul l’affichage du champ dans le constructeur de conditions disparaît, ce qui rend le filtre non modifiable depuis l’interface tant que le plugin n’est pas réactivé. Aucune donnée n’est perdue.

Limites connues

• Le plugin ne s’applique pas aux filtres de listing du storefront ni à la navigation à facettes, qui relèvent d’un mécanisme distinct
• Il ne modifie pas l’algorithme d’indexation des catégories, il consomme le champ que Shopware produit déjà
• Il ne fonctionne pas sur Shopware Cloud