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 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.

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.

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.

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.

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.

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

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.

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

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.