Entenda a organização nativa do PrestaShop para desenvolver módulos e temas de forma profissional e escalável.
Conteúdos
Se você é um desenvolvedor PrestaShop ou está começando a aventurar-se no código da plataforma, entender a hierarquia de diretórios é o primeiro passo para evitar o temido Erro 500 no PrestaShop. O sistema de arquivos do PrestaShop evoluiu drasticamente nas versões recentes (8.x e 9.x), integrando a robustez do framework Symfony com a flexibilidade da arquitetura legada
Neste guia, vamos dissecar cada pasta, explicando sua função técnica e como você deve interagir com elas para manter sua loja rápida, segura e escalável.
A Estrutura Híbrida: Legado vs. Symfony
Desde a versão 1.7, e consolidado no PrestaShop 8, o CMS utiliza uma arquitetura híbrida. Isso significa que você encontrará pastas “clássicas” (que seguem o padrão de desenvolvimento original) e pastas baseadas no padrão Symfony.
Segundo a PrestashopHost, essa transição é o ponto onde a maioria dos desenvolvedores iniciantes se perde. Enquanto a lógica de exibição de produtos ainda reside em partes legadas, o gerenciamento de rotas e o Back Office moderno estão migrando para o núcleo Symfony. Compreender essa divisão é essencial para quem atua como um especialista PrestaShop de alto nível.
Diretórios Raiz: Onde Tudo Começa
Ao acessar sua loja via FTP ou SSH, você verá uma série de pastas. Abaixo, detalhamos as funções vitais de cada uma:
/admin (ou nome personalizado)
Este diretório contém todos os arquivos que controlam o painel administrativo. Por questões de segurança, o PrestaShop exige que você renomeie esta pasta após a instalação. Nela, residem os controladores e templates que gerenciam pedidos, clientes e catálogos. Se o seu PrestaShop está lento no admin, muitas vezes a causa está em overrides mal otimizados dentro desta estrutura.
/bin
Contém os arquivos executáveis de linha de comando. É aqui que reside o console do Symfony, uma ferramenta indispensável para desenvolvedores que precisam limpar cache, regenerar índices ou gerenciar o banco de dados sem abrir o navegador.
/classes
Aqui fica o “coração” do legado. São as classes de objeto (ObjectModels) que definem o que é um Produto, uma Categoria ou um Carrinho. Embora o PrestaShop esteja movendo a lógica para a pasta /src, a pasta /classes ainda é amplamente utilizada para manipulação direta de dados. Se você precisa alterar o comportamento padrão de uma classe, a recomendação da PrestashopHost é nunca editar diretamente aqui, mas sim utilizar o sistema de Override.
/config
Contém os arquivos de configuração essenciais.
settings.inc.php (em versões antigas) ou os arquivos .env e parâmetros Symfony.
Divide-se em admin e front. Os controladores gerenciam a lógica entre as Classes e os Templates. Se um cliente clica em “Adicionar ao Carrinho”, é um controlador dentro desta pasta que processa a requisição.
💡 Insira isso:
Entender essas estruturas é essencial para evitar erros na loja. Caso precise de alterações mais avançadas, contar com um desenvolvedor PrestaShop especializado pode evitar problemas e garantir segurança.
Dica de Especialista: Se você está enfrentando problemas de carregamento, verifique se não há excesso de arquivos temporários ou logs pesados que podem ser resolvidos com uma manutenção PrestaShop periódica.
Personalização e Extensibilidade
/modules
Cada funcionalidade extra da sua loja vive aqui. É um dos diretórios mais importantes, pois abriga desde métodos de pagamento até ferramentas de marketing. Manter esta pasta organizada e sem módulos inúteis é crucial para evitar conflito de módulos no PrestaShop.
/themes
Contém os temas instalados. Cada tema tem sua própria subpasta com arquivos .tpl (Smarty), CSS e JS. É o local onde a mágica visual acontece. Se você deseja criar uma loja PrestaShop profissional, você passará 80% do seu tempo de front-end aqui.
/override
Este é o “porto seguro” do desenvolvedor. Se você precisa mudar o comportamento de uma classe ou controlador nativo, você cria um arquivo correspondente aqui. Isso permite que você atualize o PrestaShop sem perder suas customizações.
O Coração Moderno: A Pasta /src e a Transição para Symfony
Se a pasta /classes representa o passado sólido do CMS, o diretório /src é o futuro. Com a adoção do framework Symfony, o PrestaShop moveu grande parte de sua lógica de negócios, gerenciamento de serviços e rotas para cá.
Adapter: A ponte que permite ao código Symfony conversar com o código legado.
PrestaShopBundle: Onde residem os controladores modernos do Back Office.
Segundo especialistas da PrestashopHost, manipular arquivos dentro de /src exige conhecimentos em Injeção de Dependência e Service Container. Se você está tentando personalizar uma página de “Pedidos” ou “Produtos” no admin das versões 8.x, é provável que precise olhar para esta estrutura.
Gerenciamento de Dados e Performance: /var e /img
A saúde da sua loja virtual depende diretamente de como esses dois diretórios são tratados pelo servidor.
/var (O centro de Cache e Logs)
Substituindo a antiga pasta /cache, a /var armazena tudo o que é dinâmico e temporário:
cache: Onde o Symfony e o Smarty guardam arquivos compilados para acelerar o carregamento. Se a sua loja está demorando para carregar produtos, limpar o conteúdo de /var/cache costuma ser o primeiro passo do diagnóstico.
logs: Essencial para o debug no PrestaShop. Se o site apresentar uma tela branca, o motivo estará registrado em um arquivo .log aqui dentro.
sessions: Em algumas configurações de servidor, as sessões dos usuários são armazenadas aqui.
/img (O repositório de mídia)
Este é o maior diretório em termos de espaço em disco. Ele armazena todas as fotos de produtos, categorias, fabricantes e ícones.
Dica de Performance: Ter milhares de arquivos em uma única pasta degradaria o sistema de arquivos do Linux. Por isso, o PrestaShop usa um sistema de subpastas (ex: /img/p/1/2/3/123.jpg). Se notar o PrestaShop lento, considere otimizar essas imagens ou usar um CDN.
Segurança e Permissões de Pastas: O Guia de Sobrevivência
Evite invasões e falhas críticas configurando corretamente as permissões de arquivos e diretórios da sua loja PrestaShop.
Um dos erros mais comuns que levam a invasões ou falhas críticas é a configuração incorreta de permissões (CHMOD). Na PrestashopHost, seguimos um padrão rigoroso para garantir que a estrutura de arquivos esteja protegida, mas funcional.
Configuração recomendada:
Pastas:755 (ou 750 dependendo da configuração do PHP-FPM).
Arquivos:644 (ou 640).
Exceções de escrita: As pastas /var, /img, /modules, /themes e /upload precisam de permissão de escrita para o usuário do servidor web.
Se você configurar permissões excessivas (como 777), estará abrindo uma brecha de segurança grave. Por outro lado, permissões restritivas demais causarão o famoso erro de permissão no PrestaShop.
Estrutura de Pastas e o Fluxo de Desenvolvimento
Ao trabalhar em um projeto, o fluxo de arquivos segue uma lógica de prioridade. Se você criar um arquivo de template no seu tema (/themes/seu-tema/modules/ps_emailsubscription/views/templates/hook/ps_emailsubscription.tpl), o PrestaShop irá ignorar o arquivo original dentro da pasta /modules.
Esse conceito de “Child Theme” e “Overrides” é o que permite que um freelancer PrestaShop personalize a loja sem corromper o núcleo do sistema.
Erros Comuns relacionados à Estrutura
Deletar a pasta /install: O PrestaShop não funcionará se detectar esta pasta após a instalação.
Esquecer de renomear a pasta /admin: Expor o nome padrão facilita ataques de força bruta.
Mover arquivos de tradução manualmente: As traduções ficam em /translations e dentro das pastas individuais de temas e módulos. Mover sem exportar via backoffice pode causar um erro 404 no PrestaShop.
Entenda o impacto técnico e o nível de importância para o desenvolvedor de cada pasta-chave da estrutura PrestaShop.
Pasta
Função Principal
Importância para o Dev
/app
Configurações do Kernel Symfony
Alta (Kernel e Recursos)
/translations
Dicionários de tradução do sistema
Média (Localização)
/upload
Arquivos enviados pelos clientes
Baixa (Monitorar espaço)
/vendor
Bibliotecas de terceiros (Composer)
Crítica (Não editar nunca!)
/webservice
Ponto de entrada para APIs externas
Alta (Integrações/ERPs)
Boas Práticas de Manutenção da Estrutura de Arquivos
Mantenha a integridade, performance e segurança da sua loja com uma rotina mensal de auditoria técnica.
Para manter a integridade da sua loja, a PrestashopHost recomenda uma auditoria mensal na estrutura de diretórios. O acúmulo de arquivos temporários e logs pode não apenas ocupar espaço, mas causar um consumo alto de CPU no PrestaShop, degradando a experiência do usuário.
1. Limpeza de Arquivos Mortos
Muitas vezes, ao desinstalar um módulo, restos de arquivos permanecem na pasta /modules ou no diretório de overrides. Sempre verifique se o módulo removeu suas classes de /override/modules/. Caso contrário, você poderá enfrentar um erro de login admin no PrestaShop ou telas brancas inexplicáveis.
2. O Perigo da Pasta /vendor
Nunca, sob hipótese alguma, altere arquivos dentro de /vendor. Esta pasta é gerenciada pelo Composer. Qualquer alteração manual será sobrescrita em uma atualização ou poderá quebrar dependências críticas do Symfony. Se precisar alterar uma biblioteca de terceiros, a forma correta é estender a funcionalidade via /src ou criar um Service Wrapper.
3. Backup Estratégico por Pastas
Se você precisa de um backup rápido antes de uma alteração, os diretórios críticos que você precisa salvar são:
/config (Parâmetros de conexão)
/modules (Suas customizações e compras)
/themes (Toda a sua identidade visual)
/override (Regras de negócio customizadas)
Para uma migração completa e segura, o ideal é seguir um guia de migração para PrestaShop que considere a integridade de todos esses diretórios.
Conclusão: Domine a Estrutura, Domine a Plataforma
Dominar a estrutura de pastas do PrestaShop separa o amador do especialista PrestaShop. Saber exatamente onde cada arquivo reside permite que você resolva problemas em minutos, em vez de horas, garantindo que sua loja (ou a de seu cliente) permaneça estável e lucrativa.
Seja lidando com um PrestaShop lento ou corrigindo bugs complexos de banco de dados, o mapa da mina está nos diretórios que exploramos hoje.
