# Gestor de base de dados no back-office, Adminer para PrestaShop: instalação, configuração e resolução de problemas
> O módulo Gestor de Base de Dados no Back-office (referência interna dfdbmanager) integra o Adminer 5.4.2 diretamente no back-office do PrestaShop 8 e 9. Deixa de precisar do cPanel ou…
- Página:
- Idioma: pt
- Atualizado em: 2026-10-10
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/database-manager-adminer-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/database-manager-adminer-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/database-manager-adminer-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/database-manager-adminer-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/database-manager-adminer-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/database-manager-adminer-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/database-manager-adminer-prestashop/index.md)
- Índice:
O módulo **Gestor de Base de Dados no Back-office** (referência interna `dfdbmanager`) integra o Adminer 5.4.2 diretamente no back-office do PrestaShop 8 e 9. Deixa de precisar do cPanel ou de um phpMyAdmin externo: um clique no menu _Parâmetros avançados > Adminer_ e faz a gestão da sua base de dados, já autenticado.
**Numa frase**: instale o ZIP, abra o menu Adminer e gira a sua base de dados. O início de sessão automático usa as credenciais da loja e o acesso está restrito ao perfil SuperAdmin.
## Pré-requisitos
- **PrestaShop**: 8.0.0 a 9.99.99 (testado em 8.0, 8.1, 8.2 e 9.0)
- **PHP**: 7.4 ou superior (compatível com 8.0, 8.1, 8.2 e 8.3)
- **Base de dados**: MySQL 5.7+ ou MariaDB 10.3+
- **Conta de colaborador**: perfil SuperAdmin (id_profile = 1) para abrir o Adminer
- **Alojamento**: compatível com partilhado, VPS e dedicado
Não é preciso qualquer ligação de saída a partir do seu servidor: o Adminer 5.4.2 vem incluído no ZIP do módulo (508 KB, num único ficheiro).
## Instalação
### 1. Carregar o ZIP
No seu back-office do PrestaShop:
1. Vá a _Módulos > Gestor de módulos_
2. Clique em _Carregar um módulo_, no canto superior direito
3. Arraste o ficheiro `dfadminer-1.0.0.zip` ou clique para o selecionar
4. Aguarde o fim do carregamento (alguns segundos, já que o ZIP tem menos de 400 KB)
5. O módulo instala-se automaticamente
### 2. Verificar o separador do menu
A instalação cria automaticamente um separador de menu em _Parâmetros avançados > Adminer_, com um ícone Material de armazenamento. O separador é criado em cinco idiomas (francês, inglês, espanhol, alemão e italiano) e aparece no idioma ativo do seu perfil de colaborador.
**Se o separador não aparecer**: limpe a cache do PrestaShop (_Parâmetros avançados > Desempenho > Limpar a cache_) e recarregue o menu. No PrestaShop 9, termine a sessão e volte a entrar no back-office.
O português não está entre os cinco idiomas do separador: se o seu back-office estiver em português, a entrada aparece com a designação de reserva. Pode renomeá-la em **Parâmetros avançados > Menus**, se preferir vê-la como «Base de dados».
## Primeiro acesso ao Adminer
### Abrir o menu
Navegue até _Parâmetros avançados > Adminer_. Chega diretamente à lista das tabelas da sua base PrestaShop, sem ecrã de autenticação e sem formulários a preencher.
A página é composta por:
- Uma faixa fixa no topo, em azul-escuro, com o nome da sua base à esquerda e um botão azul _Back to PrestaShop BO_ à direita
- A interface do Adminer por baixo: barra lateral de tabelas à esquerda e conteúdo principal à direita
### Início de sessão automático: como funciona
O módulo lê as credenciais da sua base a partir da configuração do PrestaShop (as constantes `_DB_SERVER_`, `_DB_USER_`, `_DB_PASSWD_` e `_DB_NAME_`, definidas em `config/parameters.php` ou `config/settings.inc.php`) e inicia a sessão do Adminer do lado do servidor com essas credenciais, antes de o Adminer carregar. Não é criada qualquer palavra-passe nova nem alargada qualquer permissão de MySQL: o Adminer usa exatamente os mesmos direitos do PrestaShop.
**Sessões do Adminer por colaborador**: cada colaborador SuperAdmin tem a sua própria sessão do Adminer (as sessões de PHP são por cookie do navegador), mas todos se ligam à mesma base com as mesmas credenciais de sistema. Não há contas de Adminer para gerir.
## Página de configuração do módulo
Em _Módulos > Gestor de módulos_, procure o _Gestor de Base de Dados no Back-office_ e clique em _Configurar_. A página tem três secções.
### Estado
Mostra:
- A versão do Adminer instalada localmente (5.4.2 por predefinição)
- O caminho do ficheiro `adminer.php` dentro do módulo
- A variante instalada (Adminer completo ou Adminer Editor)
- O tamanho do ficheiro
### Atualizar o Adminer
Quando sai uma nova versão estável do Adminer em `adminer.org`, pode descarregá-la diretamente nesta página. Clique em _Update to latest Adminer_ e o módulo obtém o ficheiro de `adminer.org/latest-en.php` por cURL (ou por file_get_contents, em alternativa) e substitui o ficheiro local.
**Ligação de saída necessária**: a transferência exige que o seu servidor consiga alcançar `adminer.org` em HTTPS. Nalguns alojamentos partilhados muito restritivos, as ligações de saída estão bloqueadas. Nesse caso, descarregue o ficheiro manualmente de `adminer.org` e substitua-o em `modules/dfadminer/views/adminer/adminer.php` por FTP.
### Mudar para o Adminer Editor
O Adminer publica também uma variante _Editor_, com uma interface idêntica mas sem o campo de execução de SQL em bruto. Ficam disponíveis apenas a navegação nas tabelas e a edição de linhas. É útil se quiser dar acesso a um perfil menos técnico sem o risco de execução de SQL livre.
Clique em _Switch to Adminer Editor_ para descarregar e substituir o ficheiro. Pode voltar ao Adminer completo a qualquer momento, com _Switch back to full Adminer_.
## Modelo de segurança
### Restrição ao SuperAdmin
O Adminer é uma ferramenta poderosa: quem tem acesso à sua base tem acesso a tudo, ou seja, encomendas, clientes, pagamentos e palavras-passe dos colaboradores em hash. Por isso, o módulo restringe o acesso **apenas ao perfil SuperAdmin**, ou seja, ao `id_profile = 1` do PrestaShop.
Os outros perfis (logística, tradução, vendas, perfis personalizados) recebem uma mensagem de _Access Denied_ se tentarem abrir o Adminer, mesmo que conheçam o URL.
Um acesso direto à base é um acesso a todos os dados pessoais dos seus clientes, sem qualquer registo aplicacional. Do ponto de vista do RGPD, isso pede três coisas: limite os perfis SuperAdmin ao mínimo indispensável, inscreva este acesso técnico no seu registo de atividades de tratamento como medida a controlar, e trate qualquer exportação feita a partir do Adminer como um ficheiro de dados pessoais, que não deve ficar esquecido numa pasta de transferências. A CNPD avalia as medidas de segurança pela sua realidade, não pela intenção.
### Dupla verificação no servidor
A restrição é aplicada duas vezes do lado do servidor, no controlador:
- Em `postProcess()`, antes de o Adminer correr
- Em `initContent()`, na apresentação da interface de reserva
Esta dupla verificação garante que nenhum caminho de código contorna a barreira, mesmo perante um comportamento inesperado do encaminhador do PrestaShop.
### Bloqueio do acesso HTTP direto ao ficheiro adminer.php
O ficheiro `views/adminer/adminer.php` está bloqueado ao acesso HTTP direto, por um `.htaccess` com a diretiva `Require all denied`. Tentar abrir diretamente o URL `/modules/dfadminer/views/adminer/adminer.php` devolve um 403 Forbidden. A única forma de chegar ao Adminer é através do controlador do PrestaShop, que aplica a barreira do SuperAdmin.
## Utilizar o Adminer no PrestaShop
### Tabelas correntes a conhecer
Algumas tabelas frequentemente úteis na depuração do PrestaShop (prefixo `ps_` por predefinição, que pode variar na sua instalação):
- **ps_configuration**: todas as variáveis de configuração (chaves e valores)
- **ps_orders**: encomendas
- **ps_customer**: clientes
- **ps_product** e **ps_product_lang**: produtos e as suas traduções
- **ps_employee**: colaboradores do back-office
- **ps_log**: registo de erros do PrestaShop
- **ps_cart** e **ps_cart_product**: carrinhos
- **ps_specific_price**: promoções e regras de preço
Numa loja traduzida, a `ps_product_lang` é a tabela onde vê de relance que traduções portuguesas ainda estão vazias. Uma consulta que compare o `id_lang` do português com o do idioma de origem poupa horas de verificação manual, sobretudo depois de uma importação em massa.
### Executar uma consulta SQL
Na barra lateral esquerda, clique em _SQL command_. Escreva a consulta e clique em _Execute_. O Adminer mostra o resultado em baixo, com paginação automática nos resultados grandes.
**Sugestão**: o Adminer guarda o histórico das suas consultas SQL na sessão. Pode navegar nesse histórico pelo menu _History_, no fundo da página, e voltar a executar uma consulta com um clique.
Faça sempre uma cópia de segurança antes de um UPDATE ou de um DELETE em massa: o Adminer executa o que lhe pedir, sem rede de segurança. Se a alteração tocar em dados de encomendas ou de faturação, lembre-se de que os documentos de suporte da contabilidade têm de ser conservados 10 anos (artigo 123.º do CIRC e artigo 52.º do CIVA): corrigir a base não é o caminho para anular uma venda, que se anula por nota de crédito no software certificado pela AT.
### Exportar uma tabela
Numa tabela, clique em _Export_. O Adminer propõe vários formatos: SQL (com ou sem dados), CSV e TSV. Em tabelas muito grandes, a exportação é feita em fluxo por blocos, sem problemas de memória do PHP.
### Editar uma linha no lugar
Em qualquer tabela, clique em _Select data_ e depois no lápis à esquerda de uma linha. Edita todos os campos num formulário e grava com um clique. O Adminer gera automaticamente a consulta UPDATE.
## Vários colaboradores SuperAdmin
Se tiver vários colaboradores com o perfil SuperAdmin, cada um terá a sua sessão do Adminer, independente. Na prática:
- O colaborador A abre o Adminer no seu navegador e a sua sessão adminer_sid é criada
- O colaborador B faz o mesmo no dele, e a sua própria sessão adminer_sid é criada
- Ambos podem navegar no Adminer em paralelo, sem interferência
- Quando o A termina a sessão do back-office do PrestaShop, a sua sessão do Adminer continua válida até fechar o navegador, altura em que expira
Todos os colaboradores se ligam à mesma base com as mesmas credenciais de sistema, pelo que não há contas de Adminer separadas para gerir.
## Atualização do módulo
Para atualizar o módulo para uma versão mais recente:
1. Descarregue o novo ZIP a partir da sua área de cliente DataFirefly
2. No back-office, vá a _Módulos > Gestor de módulos_
3. Clique em _Carregar um módulo_ e envie o novo ZIP
4. O PrestaShop deteta que já existe uma versão e propõe atualizá-la
5. Confirme, e o módulo é atualizado sem perder a configuração
Como não é criada qualquer tabela na base de dados, não há migração de esquema a gerir entre versões.
## Desinstalação
Para desinstalar o módulo corretamente:
1. Vá a _Módulos > Gestor de módulos_
2. Encontre o _Gestor de Base de Dados no Back-office_
3. Clique em _Desinstalar_, no menu pendente
A desinstalação:
- Elimina o separador de menu _Parâmetros avançados > Adminer_
- Retira os ficheiros do módulo, incluindo o `adminer.php` incluído
- Não toca em qualquer tabela, pelo que a sua base PrestaShop fica intacta
- Não altera qualquer configuração do PrestaShop, palavra-passe ou permissão
A desinstalação é totalmente reversível: reinstale o módulo para recuperar o Adminer no mesmo estado.
## Resolução de problemas
### Aparece o ecrã de autenticação do Adminer em vez da lista de tabelas
Sintoma: abre o menu Adminer e vê o formulário de _Autenticação_ do Adminer (campos _System_, _Server_, _Username_, _Password_ e _Database_) em vez da lista de tabelas.
Causa provável: um cookie antigo do Adminer (de uma instalação anterior ou de outro site com Adminer) está a interferir com a sessão pré-preenchida.
**Solução**:
1. Abra as ferramentas de programador do navegador (F12)
2. Vá ao separador _Application_ (Chrome) ou _Armazenamento_ (Firefox)
3. Na secção _Cookies_, selecione o seu domínio
4. Elimine os cookies `adminer_sid`, `adminer_permanent`, `adminer_key` e `adminer_version`
5. Recarregue a página do Adminer com Ctrl+Shift+R
### Erro 403 Forbidden no carregamento
Sintoma: a página do Adminer devolve um estado HTTP 403, por vezes com o formulário de autenticação visível por baixo.
Causa provável: o Adminer não reconhece a sessão pré-preenchida e cai no seu caminho de código `auth_error`, que acrescenta explicitamente `HTTP/1.1 403 Forbidden` quando `$_GET[username]` está definido mas a autenticação falha.
**Solução**: o mesmo procedimento acima, ou seja, limpe os cookies do Adminer no navegador. Se o problema persistir, confirme que as credenciais do PrestaShop em `config/parameters.php` (PS9) ou `config/settings.inc.php` (PS8) estão corretas e que o PrestaShop se liga mesmo ao MySQL (o back-office funciona normalmente?).
### As ligações do Adminer levam ao painel do PrestaShop
Sintoma: clica no nome de uma tabela na barra lateral do Adminer e chega ao painel do PrestaShop em vez da página da tabela.
Causa provável: o pós-processamento dos URL (que injeta `controller=AdminDfAdminer` nos URL internos do Adminer) não funcionou. Na maioria das vezes, é uma cache de HTML ou um proxy intermédio a servir uma versão antiga da página.
**Solução**:
1. Limpe a cache do PrestaShop (_Parâmetros avançados > Desempenho > Limpar a cache_)
2. Limpe a cache do navegador (Ctrl+Shift+R)
3. Se houver um CDN ou uma cache HTTP à frente (Cloudflare, Varnish), limpe a sua cache para os URL `/admin*/index.php`
### Modo escuro: a faixa ou o Adminer não se adaptam
A faixa do módulo adapta-se automaticamente ao modo escuro do sistema, pela media query `@media (prefers-color-scheme: dark)`. O Adminer 5 tem também o seu próprio modo escuro integrado, que segue a mesma preferência do sistema.
Se a apresentação não seguir o modo do seu sistema:
- Confirme que o sistema operativo está mesmo em modo escuro
- O navegador tem de transmitir essa preferência: o Chrome e o Firefox fazem-no por predefinição, mas algumas extensões de gestão de temas podem sobrepor-se
- Confirme nas ferramentas de programador, em _Rendering > Emulate CSS media feature prefers-color-scheme_, que a preferência está em _dark_
### Invalid Security Token numa ação do Adminer
Sintoma: executa uma consulta SQL ou edita uma linha e o PrestaShop mostra _Invalid Security Token_.
Causa provável: esta mensagem não deveria aparecer com o módulo, porque o controlador substitui o `checkToken()` para contornar o CSRF do PrestaShop nas ações internas do Adminer. Se a vir, é porque está a aceder a um URL que não passa pelo nosso controlador.
**Solução**: confirme que o URL na barra do navegador começa mesmo por `index.php?controller=AdminDfAdminer&token=...`. Se começar por `index.php?select=...` sem o parâmetro controller, o pós-processamento dos URL foi contornado: limpe as caches do PrestaShop e do navegador e volte a abrir o Adminer pelo menu.
## Arquitetura técnica
Para quem programa ou administra e queira perceber como o módulo funciona por dentro.
### Início de sessão automático: pré-preenchimento da sessão
O carregador `views/adminer/loader.php` inicia a sessão do Adminer antes de o `adminer.php` carregar:
1. Fecha qualquer sessão de PHP em curso com `session_write_close()` (o PS9 pode ter iniciado uma através do Symfony)
2. Inicia uma nova sessão com `session_name('adminer_sid')`
3. Pré-preenche `$_SESSION[pwds][server][host][user]` com a palavra-passe real da base, lida de `_DB_PASSWD_`
4. Pré-preenche `$_SESSION[db][server][host][user][dbname] = true`
5. Define `$_GET[username]`, `$_GET[db]` e `$_GET[server]` com os valores do PrestaShop
6. Carrega o `adminer.php`
Quando o Adminer arranca, vê que a constante `SID` já está definida e salta o seu próprio `session_start()`. Vê que `$_SESSION[pwds]` não está vazio e salta a reposição por cookie permanente. A verificação de autenticação passa diretamente, o `Driver::connect()` usa a palavra-passe real através do método `credentials()` da nossa classe, e o `login()` devolve true.
### Contorno do CSRF do PrestaShop
Os formulários POST internos do Adminer (execução de consulta SQL, edição de linha, eliminação de tabela) não levam o token CSRF por controlador do PrestaShop. Sem intervenção, o PS rejeita esses pedidos com um ecrã de _Invalid Security Token_.
O controlador `AdminDfAdminerController` substitui o método `checkToken()` para devolver true sem verificação. É seguro porque a barreira do SuperAdmin (`id_profile === 1`), a montante, é estritamente mais forte do que um token CSRF: um atacante com uma sessão de SuperAdmin roubada já teria acesso a todo o back-office de qualquer modo.
### Reescrita dos URL do Adminer
O Adminer constrói as suas ligações internas na forma `index.php?select=nome_tabela&db=ps`. Sem reescrita, esses URL não levam `controller=AdminDfAdminer` e o PrestaShop encaminhá-los-ia para o painel.
O controlador chama o `ob_start()` com uma função que pós-processa a saída HTML do Adminer: injeta a faixa de regresso ao back-office no início do body e reescreve todos os atributos `href`, `action` e `src` que apontam para `index.php?...`, acrescentando `controller=AdminDfAdminer&` logo a seguir ao `?`.
### Sobreviver aos exit; do Adminer
O Adminer faz 19 chamadas a `exit;` em vários pontos (page_footer, entrega de ficheiros para os recursos, fim de erro). Um simples `ob_get_clean()` no fim do controlador nunca seria alcançado nesses casos.
A solução é passar a função de pós-processamento diretamente ao `ob_start()`. O PHP chama-a automaticamente no momento da descarga final do buffer, mesmo que tenha havido um `exit;`. Todas as saídas do Adminer passam, assim, pelo pós-processamento, sem exceção.
## Compatibilidade com o PrestaShop 9
O módulo está testado no PrestaShop 8.0, 8.1, 8.2 e 9.0. A compatibilidade com o PS 9 é obtida usando exclusivamente os padrões legacy suportados pelas duas versões:
- `ModuleAdminController` em vez de controladores Symfony, suportado no PS 8 e no PS 9
- Smarty no template de configuração, suportado nativamente
- Instalação do separador pela classe `Tab`, com API estável entre versões
- Sem classes específicas do Symfony e sem bundles necessários
- Autoload PSR-4 sem Composer (carregado por `require_once` no módulo principal)
No PS 9, o módulo funciona sem alterações, sem recompilação e sem `composer install`.
## Licença e código-fonte
O módulo DataFirefly está sob licença comercial (DataFirefly Limited, Irlanda). O código-fonte é entregue **não cifrado** no ZIP: pode auditá-lo, estender os hooks ou adaptar o comportamento (por exemplo, acrescentar outros perfis autorizados a abrir o Adminer).
O próprio Adminer está sob licença dupla **Apache 2.0 / GPL 2.0** e foi criado por Jakub Vrana. O ficheiro `adminer.php` incluído é a versão estável 5.4.2, inalterada: pode substituí-lo por qualquer versão compatível do Adminer, respeitando a licença de origem.
## Suporte
O suporte está incluído durante 12 meses após a compra (24 horas úteis, em francês e inglês). Para qualquer questão:
- E-mail: support arroba datafirefly.com
- Área de cliente: [datafirefly.com/my-account](https://www.datafirefly.com/pt/minha-conta/)
Para erros ou pedidos de evolução, indique a sua versão do PrestaShop, a versão do PHP, o seu alojamento e a versão do módulo instalada.