Documentación de DfStreamCategoryTree para Shopware 6

DfStreamCategoryTree añade un campo Category (including subcategories) al constructor de condiciones de los grupos dinámicos de productos de Shopware 6. Filtrar por una categoría padre incluye entonces todos los productos asignados a sus subcategorías, sea cual sea la profundidad.

El problema que resuelve el plugin

El constructor de condiciones nativo ofrece un campo Categories que consulta la asociación product.categoriesRo. Esa asociación solo contiene las categorías a las que un producto está asignado explícitamente en su pestaña Categories.

Un catálogo bien organizado asigna sus productos a las categorías hoja. Un modelo de zapatillas está en Hombre / Calzado / Zapatillas, no en Hombre. Un filtro sobre Hombre devuelve por tanto solo los escasos productos asignados directamente a ese nivel, a menudo ninguno.

La solución nativa consiste en marcar manualmente cada subcategoría y volver a abrir la configuración del stream cada vez que cambia el árbol. Este plugin elimina ese mantenimiento.

Cómo funciona

Shopware ya mantiene en cada producto un campo JSON llamado categoryTree que contiene el identificador de todas las categorías de la ruta, desde la raíz hasta la categoría de asignación. El CategoryIndexer nativo lo recalcula cada vez que se mueve una categoría o cambia una asignación de producto.

Un filtro equalsAny sobre ese campo con el identificador de una categoría padre recupera por tanto todos los productos cuya ruta pasa por ella. El campo existe y funciona perfectamente en el DAL, pero la administración no lo expone en el selector del constructor de condiciones: no figura en la lista de autorización del servicio productStreamConditionService.

El plugin añade una entrada a esa lista de autorización y aporta las etiquetas traducidas correspondientes. No introduce ningún decorador de servicio, ningún listener de eventos de producto, ninguna tabla ni ninguna migración.

Requisitos

• Shopware 6.7.x autoalojado
• PHP 8.2 o superior
• Acceso a la línea de comandos o a un pipeline de despliegue capaz de recompilar la administración

El plugin no funciona en Shopware Cloud, ya que la versión SaaS alojada por Shopware no permite instalar plugins de servidor.

Instalación

Mediante subida de ZIP

1. En la administración, abra Extensions y luego My extensions
2. Haga clic en Subir extensión y seleccione el archivo DfStreamCategoryTree-1.0.0.zip
3. Instale y active el plugin
4. Recompile la administración (ver la sección siguiente)

Mediante despliegue de carpeta

Descomprima el archivo en el directorio de plugins personalizados de su instancia y ejecute:

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

Recompilación de la administración

El plugin modifica el comportamiento de la interfaz de administración. Es necesaria una recompilación del bundle admin una vez tras la instalación, sin la cual el nuevo campo no aparecerá en el selector de condiciones.

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

En un entorno de producción gestionado por un pipeline de despliegue, este paso suele formar parte ya del proceso estándar. Después, vacíe la caché del navegador o abra la administración en una ventana privada para asegurarse de cargar el bundle actualizado.

Uso

Crear un grupo dinámico recursivo

1. Abra Catálogos y luego Dynamic product groups
2. Cree un grupo nuevo o abra uno existente
3. En el constructor de condiciones, despliegue el selector de campo
4. Elija Category (including subcategories), justo encima de la entrada Categories original
5. Seleccione el operador Is equal to any of
6. Elija una o varias categorías padre en el campo de valor
7. Guarde y abra la pestaña Preview para comprobar el número de productos devueltos

Operadores disponibles

• Is equal to any of: el producto pertenece al subárbol de al menos una de las categorías seleccionadas
• Is not equal to any of: el producto no pertenece a ninguno de los subárboles seleccionados, útil para excluir toda una sección de una campaña

Combinar con otras condiciones

El campo se comporta como cualquier otra condición del stream. Se combina libremente con fabricante, precio, stock, propiedades y etiquetas, y funciona dentro de los grupos AND y OR anidados del constructor.

Configuración típica para una liquidación: Category (including subcategories) is equal to any of Hombre, Y Stock is greater than 0, Y Price is greater than 50.

Dónde se puede utilizar el grupo

• Páginas de categoría de navegación alimentadas por un grupo dinámico
• Bloques de productos en Shopping Experiences
• Condiciones de reglas de promoción
• Cross-selling automático en la ficha de producto
• Cualquier integración que consuma un product stream vía Admin API o Store API

Uso mediante la Admin API

Al ser un campo nativo del DAL, una condición enviada directamente por API funciona incluso sin el plugin. El plugin sirve para hacer el filtro visible y editable en la interfaz, lo que importa en cuanto un equipo de marketing gestiona los grupos sin pasar por la API.

POST /api/product-stream
{
  "name": "Toda la seccion Hombre",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Sin el plugin instalado, un stream que contenga este filtro sigue funcionando a nivel DAL pero su campo no puede mostrarse en el constructor de condiciones.

Resolución de problemas

El campo no aparece en el selector

En la inmensa mayoría de los casos, la administración no se recompiló tras la instalación. Vuelva a ejecutar la secuencia bundle:dump, build-administration y cache:clear, y recargue la administración con la caché del navegador vacía. Compruebe también que el plugin está activo en Extensions y luego My extensions.

El grupo sigue devolviendo productos incorrectos

Asegúrese de haber seleccionado el nuevo campo y no la entrada Categories original, ya que ambos coexisten en el selector. Abra después un producto esperado y verifique que está asignado a una subcategoría del padre elegido, y que está activo y visible en el canal de venta correspondiente.

Un producto movido recientemente no aparece

El campo categoryTree lo recalcula el CategoryIndexer nativo. Si la cola de mensajes va con retraso o la indexación se ha pausado, fuerce una reindexación:

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

Reinicializar tras una actualización de Shopware

Tras una subida de versión menor de Shopware, recompile la administración para que el plugin vuelva a registrar su entrada en la lista de autorización. No hace falta nada más, ya que el plugin no almacena ningún dato.

Desinstalación

Desactive y desinstale el plugin desde Extensions o por línea de comandos. El plugin no crea ninguna tabla ni almacena configuración, por lo que la desinstalación es totalmente neutra.

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

Los grupos dinámicos ya configurados con el filtro siguen funcionando: la condición se almacena como filtro DAL estándar y el motor nativo la sigue evaluando. Solo desaparece la visualización del campo en el constructor de condiciones, lo que impide editar el filtro desde la interfaz mientras el plugin no se reactive. No se pierde ningún dato.

Limitaciones conocidas

• El plugin no se aplica a los filtros de listado del storefront ni a la navegación por facetas, que dependen de un mecanismo distinto
• No modifica el algoritmo de indexación de categorías, consume el campo que Shopware ya produce
• No funciona en Shopware Cloud