Instruções de instalação e configuração do módulo Kowal_ExportImportCategories

Este documento descreve a instalação, configuração e utilização do módulo Kowal_ExportImportCategories para Magento 2. As instruções incluem informações do ficheiro README.md e as funcionalidades implementadas no módulo.

Requisitos

• Magento 2.
• PHP compatível com a instalação Magento, recomendado PHP 8.1 ou mais recente.
• Acesso à CLI do Magento.
• Acesso ao Composer.
• Permissões de administrador Magento.
• Acesso ao repositório do módulo.
• Para importação de imagens: possibilidade de colocar ficheiros no diretório pub/media/import/categories.

Instalação através do Composer

O módulo está disponível através do repositório Composer.

1. Adicione o repositório Composer

Receberá os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença, por e-mail após a compra. Também estão disponíveis no painel do cliente após iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do Magento.

composer config repositories.kowal composer https://repo.kowal.store

2. Configure o acesso ao repositório Composer Kowal

Configure os dados de acesso ao repositório Composer Kowal:

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Substitua pelo seu próprio token de acesso.

3. Instale o módulo

composer require kowal/module-export-import-categories

4. Ative o módulo no Magento

bin/magento module:enable Kowal_ExportImportCategories

5. Execute a atualização do Magento

bin/magento setup:upgrade

6. Limpe a cache

bin/magento cache:flush

7. Opcionalmente, execute a compilação DI

Em ambientes de produção ou no modo production:

bin/magento setup:di:compile

8. Opcionalmente, implemente os recursos estáticos

Se o ambiente o exigir:

bin/magento setup:static-content:deploybin/magento cache:flush

Instalação manual em app/code

Em alternativa, o módulo pode ser colocado manualmente no diretório:

app/code/Kowal/ExportImportCategories

Depois de copiar os ficheiros, execute:

bin/magento module:enable Kowal_ExportImportCategoriesbin/magento setup:upgradebin/magento cache:flush

No modo production, execute também:

bin/magento setup:di:compile

Verificação da instalação

Após a instalação, verifique se o módulo está ativo:

bin/magento module:status Kowal_ExportImportCategories

O módulo deve constar na lista de módulos ativos.

No painel de administração, aceda a:

System > Data Transfer > Export/Import Categories

Devem estar visíveis três opções:

• Export Categories,
• Import Categories,
• Import History.

Permissões ACL

O módulo adiciona permissões administrativas separadas:

• acesso à secção principal Export/Import Categories,
• exportação de categorias,
• importação de categorias,
• histórico de importações.

Se o utilizador admin não vir o menu do módulo, verifique a função do utilizador em:

System > Permissions > User Roles

Em seguida, atribua as permissões adequadas para os recursos do módulo.

Localização do módulo no painel

O módulo está disponível em:

System > Data Transfer > Export/Import Categories

Vistas:

• Export Categories - exportação de categorias para CSV.
• Import Categories - importação de categorias a partir de CSV.
• Import History - histórico de importações e relatórios.

Configuração da exportação

A vista de exportação permite gerar um ficheiro CSV com categorias.

Campos de exportação

Store View

Seleciona o store view a partir do qual serão lidos os valores dos atributos de categorias.

Se selecionar um store view linguístico, a exportação pode conter valores específicos desse store view ou valores herdados do scope predefinido, consoante o modo de valores.

Start Category ID

Campo opcional que permite limitar a exportação à categoria selecionada e à respetiva subárvore.

Se o campo ficar vazio, o módulo exporta categorias a partir da root category do store view selecionado.

Store View Value Mode

Define como exportar valores dependentes do store view.

Variantes disponíveis:

• resolved_value,
• store_override_only.

resolved_value exporta o valor visível no store view selecionado depois de considerar o fallback do Magento.

store_override_only exporta apenas o valor substituído para o store view selecionado. Se o valor for herdado do default scope, a célula CSV ficará vazia.

CSV Delimiter

Separador CSV. Por predefinição:

,

Pode ser usado outro separador se o ficheiro for editado numa ferramenta que exija, por exemplo, ponto e vírgula.

Attributes

Lista de atributos de categorias disponíveis no Magento.

O módulo obtém atributos dinamicamente a partir de EAV, por isso a lista também pode incluir atributos de categorias personalizados adicionados no projeto.

As colunas de sistema são adicionadas automaticamente e não precisam de ser selecionadas.

Colunas de sistema na exportação

A exportação deve incluir sempre colunas de sistema:

• store_view_code,
• entity_id,
• parent_entity_id,
• category_path,
• parent_path,
• level,
• position,
• attribute_set_id.

Estas colunas servem para identificar categorias, validar o store view e gerir a estrutura da árvore.

Configuração da importação

A vista de importação permite carregar CSV e gravar dados de categorias.

Campos de importação

Store View

Seleciona o store view no qual os valores serão gravados.

Este campo determina o store_id numérico usado na gravação nas tabelas Magento.

A coluna store_view_code do CSV não é convertida diretamente em store_id. É usada para validar se o ficheiro corresponde ao store view selecionado.

Exemplo:

• no formulário, seleciona um store view com store_id = 1,
• no CSV deve existir store_view_code correspondente a esse store view,
• o módulo grava os dados usando store_id = 1.

Import Mode

Modos disponíveis:

• update,
• insert.

update atualiza categorias existentes.

insert cria novas categorias.

CSV File

Ficheiro CSV com cabeçalhos na primeira linha.

O ficheiro deve estar codificado em UTF-8.

CSV Delimiter

Separador CSV. Deve corresponder ao separador usado no ficheiro.

Unknown Columns Policy

Define o comportamento para colunas que não são colunas de sistema nem atributos de categorias conhecidos.

Variantes disponíveis:

• error - a importação comunica um erro para colunas desconhecidas.
• ignore - as colunas desconhecidas são ignoradas.

Variante recomendada:

error

Empty Values Policy

Define como o módulo interpreta células CSV vazias.

Variantes disponíveis:

• skip_empty,
• clear_value,
• use_default.

skip_empty significa que uma célula vazia não altera o valor atual.

clear_value significa que uma célula vazia limpa o valor do atributo.

use_default significa que uma célula vazia remove a substituição do store view e permite ao Magento usar o valor predefinido.

Variante recomendada para importação de atualização:

skip_empty

URL Key Strategy

Define a forma de gestão do atributo url_key.

Variantes disponíveis:

• use_csv_value,
• generate_from_name,
• keep_existing,
• magento_default.

use_csv_value grava url_key a partir do CSV.

generate_from_name gera url_key com base no valor name.

keep_existing mantém o url_key existente no modo update.

magento_default deixa a gestão do URL ao mecanismo padrão do Magento.

Create permanent redirect for URL key changes

A opção define se o Magento deve criar permanent redirect ao alterar url_key.

Vale a pena ativá-la quando a alteração do URL da categoria deve preservar os redirecionamentos SEO dos endereços antigos.

Images Base Directory

Diretório base para importação de imagens de categorias relativamente a pub/media.

Por predefinição:

import/categories

Caminho completo no Magento:

pub/media/import/categories

Se indicar no CSV:

gear/bags.jpg

o módulo procurará o ficheiro:

pub/media/import/categories/gear/bags.jpg

Error Policy

Define o comportamento da importação perante erros.

Variantes disponíveis:

• skip_invalid_rows,
• stop_on_first_error,
• all_or_nothing.

skip_invalid_rows ignora linhas incorretas e continua a importação.

stop_on_first_error interrompe a importação após o primeiro erro.

all_or_nothing exige que todo o ficheiro esteja correto; se ocorrer um erro, a importação não deve gravar dados.

Variante recomendada para ficheiros grandes:

skip_invalid_rows

Batch Size

Número de linhas processadas num único lote.

Por predefinição:

100

Um valor mais baixo reduz o consumo de memória. Um valor mais alto pode acelerar a importação em ambientes mais potentes.

Attributes to Import

Lista de atributos que devem ser importados.

A importação atualiza apenas os atributos selecionados. Se a coluna existir no CSV, mas o atributo não for selecionado no formulário, o módulo não deverá gravá-lo.

Dry Run

Modo de validação sem gravação de dados.

Recomenda-se executar dry-run antes da importação propriamente dita, especialmente para ficheiros grandes ou alterações SEO.

Modo import/update

O modo update serve para atualizar categorias existentes.

Dados obrigatórios

O CSV deve conter:

• store_view_code,
• entity_id ou category_path,
• pelo menos uma coluna de atributo selecionado.

Como funciona a identificação de categorias

O módulo tenta encontrar a categoria por:

1. entity_id,
2. category_path, se entity_id estiver vazio.

entity_id é o melhor identificador quando a importação é feita no mesmo ambiente Magento.

category_path é mais portável entre ambientes, mas deve ser inequívoco.

Exemplo de atualização de traduções

store_view_code,entity_id,category_path,name,url_key,meta_title,meta_descriptionpl,13,Default Category/Gear/Bags,Torby,torby,Torby,Torby i akcesoriapl,14,Default Category/Gear/Gloves,Rekawiczki,rekawiczki,Rekawiczki,Rekawiczki sportowe

Definições de importação:

• Store View: store view polaco,
• Import Mode: update,
• Attributes to Import: name, url_key, meta_title, meta_description,
• URL Key Strategy: use_csv_value,
• Empty Values Policy: skip_empty,
• primeiro Dry Run, depois a importação final.

Modo import/insert

O modo insert serve para criar novas categorias.

Dados obrigatórios

O CSV deve conter:

• store_view_code,
• category_path,
• parent_entity_id ou parent_path,
• name,
• pelo menos uma coluna de atributo selecionado.

entity_id não é obrigatório, porque o Magento atribui-o automaticamente.

Exemplo de criação de categorias

store_view_code,parent_entity_id,parent_path,category_path,name,url_key,is_active,include_in_menudefault,12,Default Category/Gear,Default Category/Gear/Helmets,Helmets,helmets,1,1default,12,Default Category/Gear,Default Category/Gear/Gloves,Gloves,gloves,1,1

Definições de importação:

• Store View: default store view,
• Import Mode: insert,
• Attributes to Import: name, url_key, is_active, include_in_menu,
• URL Key Strategy: use_csv_value ou generate_from_name,
• Error Policy: skip_invalid_rows,
• primeiro Dry Run.

Trabalho com select e multiselect

O módulo suporta select e multiselect através dos labels das opções.

Não é necessário indicar IDs técnicos das opções.

Exemplo:

store_view_code,entity_id,category_path,display_mode,available_sort_by,default_sort_bydefault,13,Default Category/Gear/Bags,Products only,Position|Product Name|Price,Position

Para multiselect, vários valores são separados pelo separador:

|

Se o label não existir ou for ambíguo, a importação comunicará um erro.

Importação de imagens de categorias

Antes de importar imagens, coloque os ficheiros no diretório:

pub/media/import/categories

Exemplo de CSV:

store_view_code,entity_id,category_path,image,thumbnaildefault,13,Default Category/Gear/Bags,gear/bags.jpg,gear/bags-thumb.jpg

Definições de importação:

• Images Base Directory: import/categories,
• atributos selecionados: image, thumbnail.

O módulo verificará se os ficheiros existem e têm extensões suportadas.

Relatório de importação

Após a importação, o módulo gera um relatório CSV.

O relatório contém:

• número da linha,
• identificador da categoria,
• estado,
• mensagem,
• atributos alterados.

Os estados podem incluir:

• success,
• error,
• skipped_no_change,
• skipped_existing.

Histórico de importações

O histórico de importações está disponível em:

System > Data Transfer > Export/Import Categories > Import History

O histórico inclui:

• data da importação,
• utilizador admin,
• store view,
• modo de importação,
• nome do ficheiro,
• número de linhas,
• número de sucessos,
• número de erros,
• informação sobre dry-run,
• link para descarregar o relatório.

Processo de trabalho recomendado

Importação de atualização segura

1. Exporte as categorias atuais.
2. Guarde o ficheiro original como backup.
3. Prepare as alterações numa cópia do CSV.
4. Certifique-se de que store_view_code corresponde ao store view de destino.
5. Selecione a importação update.
6. Selecione apenas os atributos que pretende alterar.
7. Defina Empty Values Policy como skip_empty.
8. Execute Dry Run.
9. Verifique o relatório.
10. Execute a importação final.
11. Limpe a cache se as alterações não ficarem imediatamente visíveis.

Importação segura de novas categorias

1. Prepare o CSV com category_path, parent_path ou parent_entity_id.
2. Certifique-se de que os pais existem ou aparecem antes no ficheiro.
3. Selecione a importação insert.
4. Selecione, no mínimo, name e outros atributos obrigatórios.
5. Execute Dry Run.
6. Corrija os erros do relatório.
7. Execute a importação final.

Cache e índices

Após importar alterações nas categorias, é recomendável atualizar a cache do Magento:

bin/magento cache:clean

Se a loja exigir reindexação manual após alterações maiores no catálogo:

bin/magento indexer:reindex

Em instalações Magento típicas, a gravação de categorias através dos mecanismos padrão do Magento deve acionar os processos adequados associados ao modelo de categoria, mas após importações grandes recomenda-se verificar a cache e os índices.

Problemas mais frequentes

A importação comunica store_view_code incompatível

Verifique se o código na coluna store_view_code corresponde ao store view selecionado no formulário de importação.

A importação não altera valores

Verifique:

• se o atributo foi selecionado em Attributes to Import,
• se a célula CSV não está vazia,
• se Empty Values Policy não está definido como skip_empty,
• se a importação não foi executada como Dry Run.

Select ou multiselect comunica erro

Verifique se o label da opção no CSV corresponde exatamente ao label da opção no Magento para o store view selecionado.

A imagem não é importada

Verifique:

• se o ficheiro existe em pub/media/import/categories,
• se o caminho no CSV está correto,
• se a extensão do ficheiro é suportada,
• se o atributo de imagem foi selecionado para importação.

Insert comunica falta do pai

Verifique parent_entity_id ou parent_path. O pai deve existir no Magento ou aparecer antes no ficheiro de importação.

Desinstalação do módulo

Se o módulo tiver sido instalado através do Composer:

composer remove kowal/module-export-import-categoriesbin/magento setup:upgradebin/magento cache:flush

Antes de desinstalar, certifique-se de que o histórico de importações pode ser removido. O módulo cria a tabela:

kowal_export_import_categories_history