Documentazione DfStreamCategoryTree per Shopware 6

DfStreamCategoryTree aggiunge un campo Category (including subcategories) al costruttore di condizioni dei gruppi dinamici di prodotti di Shopware 6. Filtrare su una categoria padre include così tutti i prodotti assegnati alle sue sottocategorie, a qualsiasi profondità.

Il problema che il plugin risolve

Il costruttore di condizioni nativo offre un campo Categories che interroga l’associazione product.categoriesRo. Tale associazione contiene soltanto le categorie a cui un prodotto è esplicitamente assegnato nella sua scheda Categories.

Un catalogo ben organizzato assegna i prodotti alle categorie foglia. Un modello di sneaker si trova in Uomo / Calzature / Sneaker, non in Uomo. Un filtro su Uomo restituisce quindi solo i pochi prodotti assegnati direttamente a quel livello, spesso nessuno.

La soluzione nativa consiste nel selezionare manualmente ogni sottocategoria e riaprire la configurazione dello stream a ogni modifica dell’albero. Questo plugin elimina tale manutenzione.

Come funziona

Shopware mantiene già su ogni prodotto un campo JSON chiamato categoryTree che contiene l’identificativo di tutte le categorie del percorso, dalla radice fino alla categoria di assegnazione. Il CategoryIndexer nativo lo ricalcola a ogni spostamento di categoria e a ogni modifica di assegnazione prodotto.

Un filtro equalsAny su questo campo con l’identificativo di una categoria padre restituisce quindi tutti i prodotti il cui percorso passa attraverso di essa. Il campo esiste e funziona perfettamente nel DAL, ma l’amministrazione non lo espone nel selettore del costruttore di condizioni: non compare nella lista di autorizzazione del servizio productStreamConditionService.

Il plugin aggiunge una voce a questa lista di autorizzazione e fornisce le etichette tradotte corrispondenti. Non introduce alcun decoratore di servizio, alcun listener sugli eventi prodotto, alcuna tabella e alcuna migrazione.

Prerequisiti

• Shopware 6.7.x self-hosted
• PHP 8.2 o superiore
• Accesso alla riga di comando o a una pipeline di deploy in grado di ricompilare l’amministrazione

Il plugin non funziona su Shopware Cloud, poiché la versione SaaS ospitata da Shopware non consente l’installazione di plugin server.

Installazione

Tramite caricamento ZIP

1. Nell’amministrazione, aprire Extensions e poi My extensions
2. Fare clic su Carica estensione e selezionare l’archivio DfStreamCategoryTree-1.0.0.zip
3. Installare e attivare il plugin
4. Ricompilare l’amministrazione (vedere la sezione successiva)

Tramite deploy della cartella

Estrarre l’archivio nella directory dei plugin personalizzati della propria istanza, quindi eseguire:

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

Ricompilazione dell’amministrazione

Il plugin modifica il comportamento dell’interfaccia di amministrazione. È necessaria una ricompilazione del bundle admin una volta dopo l’installazione, altrimenti il nuovo campo non comparirà nel selettore delle condizioni.

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

In un ambiente di produzione gestito da una pipeline di deploy, questo passaggio fa in genere già parte del processo standard. Svuotare poi la cache del browser o aprire l’amministrazione in una finestra privata per essere certi di caricare il bundle aggiornato.

Utilizzo

Creare un gruppo dinamico ricorsivo

1. Aprire Cataloghi e poi Dynamic product groups
2. Creare un nuovo gruppo o aprirne uno esistente
3. Nel costruttore di condizioni, espandere il selettore di campo
4. Scegliere Category (including subcategories), appena sopra la voce Categories originale
5. Selezionare l’operatore Is equal to any of
6. Scegliere una o più categorie padre nel campo valore
7. Salvare e aprire la scheda Preview per verificare il numero di prodotti restituiti

Operatori disponibili

• Is equal to any of: il prodotto appartiene al sottoalbero di almeno una delle categorie selezionate
• Is not equal to any of: il prodotto non appartiene a nessuno dei sottoalberi selezionati, utile per escludere un intero reparto da una campagna

Combinare con altre condizioni

Il campo si comporta come qualsiasi altra condizione dello stream. Si combina liberamente con produttore, prezzo, stock, proprietà e tag, e funziona nei gruppi AND e OR annidati del costruttore.

Configurazione tipica per una svendita: Category (including subcategories) is equal to any of Uomo, E Stock is greater than 0, E Price is greater than 50.

Dove il gruppo può essere utilizzato

• Pagine di categoria di navigazione alimentate da un gruppo dinamico
• Blocchi prodotto nelle Shopping Experiences
• Condizioni delle regole di promozione
• Cross-selling automatico sulla scheda prodotto
• Qualsiasi integrazione che consumi un product stream tramite Admin API o Store API

Utilizzo tramite Admin API

Essendo il campo nativo del DAL, una condizione inviata direttamente via API funziona anche senza il plugin. Il plugin serve a rendere il filtro visibile e modificabile nell’interfaccia, aspetto rilevante non appena un team marketing gestisce i gruppi senza passare dall’API.

POST /api/product-stream
{
  "name": "Intero reparto Uomo",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Senza il plugin installato, uno stream contenente questo filtro continua a funzionare a livello DAL ma il suo campo non può essere visualizzato nel costruttore di condizioni.

Risoluzione dei problemi

Il campo non compare nel selettore

Nella stragrande maggioranza dei casi l’amministrazione non è stata ricompilata dopo l’installazione. Rilanciare la sequenza bundle:dump, build-administration e cache:clear, quindi ricaricare l’amministrazione con la cache del browser svuotata. Verificare inoltre che il plugin sia attivo in Extensions e poi My extensions.

Il gruppo restituisce ancora prodotti errati

Assicurarsi di aver selezionato il nuovo campo e non la voce Categories originale, poiché entrambi coesistono nel selettore. Aprire poi un prodotto atteso e verificare che sia assegnato a una sottocategoria del padre scelto e che sia attivo e visibile sul canale di vendita interessato.

Un prodotto spostato di recente non compare

Il campo categoryTree viene ricalcolato dal CategoryIndexer nativo. Se la coda dei messaggi è in ritardo o l’indicizzazione è stata messa in pausa, forzare una reindicizzazione:

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

Ripristino dopo un aggiornamento di Shopware

Dopo un aggiornamento di versione minore di Shopware, ricompilare l’amministrazione affinché il plugin registri nuovamente la sua voce nella lista di autorizzazione. Non serve altro, poiché il plugin non memorizza alcun dato.

Disinstallazione

Disattivare e disinstallare il plugin da Extensions o da riga di comando. Il plugin non crea alcuna tabella e non memorizza configurazioni, quindi la disinstallazione è del tutto neutra.

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

I gruppi dinamici già configurati con il filtro continuano a funzionare: la condizione è memorizzata come filtro DAL standard e resta valutata dal motore nativo. Scompare soltanto la visualizzazione del campo nel costruttore di condizioni, il che rende il filtro non modificabile dall’interfaccia finché il plugin non viene riattivato. Nessun dato viene perso.

Limiti noti

• Il plugin non si applica ai filtri di listing della storefront né alla navigazione a faccette, che dipendono da un meccanismo distinto
• Non modifica l’algoritmo di indicizzazione delle categorie, consuma il campo che Shopware già produce
• Non funziona su Shopware Cloud