Documentação DfStreamCategoryTree para Shopware 6

O DfStreamCategoryTree acrescenta um campo Category (including subcategories) ao construtor de condições dos grupos de produtos dinâmicos do Shopware 6. Filtrar por uma categoria principal inclui então todos os produtos arrumados nas suas subcategorias, seja qual for a profundidade.

O problema que a extensão resolve

O construtor de condições nativo oferece um campo Categories que consulta a relação product.categoriesRo. Essa relação contém apenas as categorias às quais um produto está explicitamente associado no seu separador Categories.

Um catálogo bem organizado arruma os produtos nas categorias folha. Um modelo de sapatilhas é atribuído a Homem / Calçado / Sapatilhas, e não a Homem. Um filtro sobre Homem devolve portanto apenas os raros produtos atribuídos diretamente a esse nível, muitas vezes nenhum.

A solução nativa consiste em assinalar manualmente cada subcategoria, e depois reabrir a configuração do stream a cada evolução da árvore. Esta extensão elimina essa manutenção.

Como funciona

O Shopware já mantém, para cada produto, um campo JSON chamado categoryTree que contém o identificador de todas as categorias do caminho, desde a raiz até à categoria de atribuição. Este campo é recalculado pelo CategoryIndexer nativo a cada movimentação de categoria e a cada alteração de atribuição de produto.

Um filtro equalsAny sobre este campo com o identificador de uma categoria principal devolve portanto todos os produtos cujo caminho passa por ela. O campo existe e funciona perfeitamente no DAL, mas a administração não o expõe no seletor do construtor de condições: não figura na lista de permissões do serviço productStreamConditionService.

A extensão acrescenta uma entrada a essa lista de permissões e fornece as etiquetas traduzidas associadas. Não introduz qualquer decorador de serviço, qualquer listener nos eventos de produto, qualquer tabela nem qualquer migração.

Pré-requisitos

• Shopware 6.7.x auto-alojado
• PHP 8.2 ou superior
• Acesso à linha de comandos ou a um pipeline de deploy capaz de recompilar a administração

A extensão não funciona no Shopware Cloud, uma vez que a versão SaaS alojada pela Shopware não permite instalar extensões de servidor.

Instalação

Por carregamento de ZIP

1. Na administração, abra Extensões e depois As minhas extensões
2. Clique em Carregar extensão e selecione o arquivo DfStreamCategoryTree-1.0.0.zip
3. Instale e ative a extensão
4. Recompile a administração (ver a secção seguinte)

Por colocação da pasta

Descomprima o arquivo no diretório das extensões personalizadas da sua instância e execute:

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

Recompilação da administração

A extensão altera o comportamento da interface de administração. É necessária uma recompilação do bundle de administração uma vez após a instalação, sem a qual o novo campo não aparecerá no seletor de condições.

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

Num ambiente de produção gerido por um pipeline de deploy, este passo costuma já fazer parte do processo normal. Limpe depois a cache do navegador ou abra a administração numa janela privada para ter a certeza de carregar o bundle atualizado.

Utilização

Criar um grupo dinâmico recursivo

1. Abra Catálogos e depois Dynamic product groups
2. Crie um novo grupo ou abra um grupo existente
3. No construtor de condições, abra o seletor de campo
4. Escolha Category (including subcategories), mesmo acima da entrada Categories original
5. Selecione o operador Is equal to any of
6. Escolha uma ou várias categorias principais no campo de valor
7. Guarde e abra o separador Preview para verificar o número de produtos devolvidos

Operadores disponíveis

• Is equal to any of: o produto pertence à subárvore de pelo menos uma das categorias selecionadas
• Is not equal to any of: o produto não pertence à subárvore de nenhuma das categorias selecionadas, útil para excluir um sector inteiro de uma operação comercial

Combinar com outras condições

O campo comporta-se como qualquer outra condição do stream. Combina-se livremente com o fabricante, o preço, o estado do stock, as propriedades, as tags, e usa-se nos grupos AND e OR aninhados do construtor.

Exemplo de configuração típica para uma operação de escoamento de stock: Category (including subcategories) is equal to any of Homem, E Stock is greater than 0, E Price is greater than 50.

Onde o grupo pode ser usado

• Página de categoria de navegação alimentada por um grupo dinâmico
• Blocos de produtos nas Shopping Experiences
• Condições de regras de promoção
• Cross-selling automático na página de produto
• Qualquer integração que consuma um product stream através da Admin API ou da Store API

Utilização através da Admin API

Sendo o campo nativo do DAL, uma condição colocada diretamente pela API funciona mesmo sem a extensão. A extensão serve para tornar esse filtro visível e modificável na interface, o que conta assim que uma equipa de marketing gere os grupos sem passar pela API.

POST /api/product-stream
{
  "name": "Todo o sector Homem",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Sem a extensão instalada, um stream que contenha este filtro continua funcional do lado do DAL, mas o seu campo não pode ser apresentado no construtor de condições.

Resolução de problemas

O campo não aparece no seletor

Na grande maioria dos casos, a administração não foi recompilada depois da instalação. Repita a sequência bundle:dump, build-administration e cache:clear, e recarregue a administração limpando a cache do navegador. Verifique também que a extensão está mesmo ativa em Extensões e depois As minhas extensões.

O grupo continua a não devolver os produtos certos

Verifique que selecionou mesmo o novo campo e não a entrada Categories original, uma vez que ambas coexistem no seletor. Verifique depois, na ficha de um produto esperado, que este está mesmo atribuído a uma subcategoria do principal escolhido, e que está ativo e visível no canal de venda em causa.

Um produto movido recentemente não aparece

O campo categoryTree é recalculado pelo CategoryIndexer nativo. Se a fila de mensagens estiver atrasada ou se a indexação tiver sido pausada, force uma reindexação:

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

Repor depois de uma atualização principal do Shopware

Depois de uma subida de versão menor do Shopware, recompile a administração para que a extensão volte a registar a sua entrada na lista de permissões. Não é necessária qualquer outra ação, uma vez que a extensão não guarda quaisquer dados.

Desinstalação

Desative e desinstale a extensão a partir de Extensões ou por linha de comandos. A extensão não cria qualquer tabela nem guarda qualquer configuração, pelo que a desinstalação é inteiramente neutra.

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

Os grupos dinâmicos já configurados com o filtro continuam a funcionar: a condição está guardada na base de dados sob a forma de filtro DAL normal e continua a ser avaliada pelo motor nativo. Apenas desaparece a apresentação do campo no construtor de condições, o que torna o filtro não modificável a partir da interface enquanto a extensão não for reativada. Nenhum dado se perde.

Limites conhecidos

• A extensão não se aplica aos filtros de listagem do storefront nem à navegação por facetas, que dependem de um mecanismo distinto
• Não altera o algoritmo de indexação das categorias, consome o campo que o Shopware já produz
• Não funciona no Shopware Cloud