Precisa de corrigir algum texto num tema, mas em que ficheiro está? Com uma dúzia de plugins instalados e um tema personalizado, a caça ao pedaço de código certo transforma-se numa demanda de meio dia. Uma cena familiar para quem já andou a vasculhar os bastidores do WordPress sem preparação.

Os programadores navegam na hierarquia de templates em piloto automático. Mas se a programação não é a sua área, decorar dezenas de ficheiros PHP e as suas finalidades não faz sentido. É muito mais inteligente instalar uma ferramenta que lhe mostre: «este ficheiro trata do cabeçalho e este outro gera o artigo.»

Como está organizado o sistema de ficheiros do WordPress

Antes de procurar um ficheiro específico, ajuda compreender a estrutura geral. O WordPress é composto por três diretórios principais e as edições em cada um acarretam níveis de risco diferentes.

/wp-content/ é a sua zona de trabalho. Contém temas (/themes/), plugins (/plugins/) e ficheiros de media carregados (/uploads/). Um erro num ficheiro de tema ou plugin quebra apenas essa funcionalidade específica, mas o site mantém-se no ar e o painel de administração continua a funcionar. Este é o diretório com que lidará na grande maioria dos casos.

/wp-admin/ e /wp-includes/ são o núcleo do WordPress. É fortemente desaconselhado mexer em ficheiros aqui: quaisquer alterações serão sobrescritas na próxima atualização e um erro pode deitar abaixo o site inteiro. Se suspeitar que o problema está no núcleo, utilize hooks e filtros no seu tema em vez de editar diretamente os ficheiros de sistema.

O diretório raiz contém o wp-config.php (configurações da base de dados, chaves de segurança, modo de depuração) e o .htaccess (regras de redirecionamento). Pode editar estes ficheiros, mas com cuidado redobrado: um erro de sintaxe no wp-config.php resultará num ecrã branco em todo o site, incluindo o painel de administração.

A regra principal de navegação: se vir uma pasta wp-content, está na zona segura. Se o sistema o levar para dentro de wp-admin ou wp-includes, pare e verifique duas vezes se está no sítio certo.

Abaixo estão dois plugins gratuitos que resolvem a tarefa de ângulos diferentes. O primeiro identifica um template de página com um clique na barra de ferramentas; o segundo procura qualquer string de código em todos os ficheiros do site. Ambos foram testados no WordPress 6.9 e funcionam sem conflitos.

💡 Visão geral rápida:

• Abra uma página do site e passe o cursor sobre o What the File na barra de ferramentas
• Introduza a frase de pesquisa em Ferramentas → String Locator
• Faça uma cópia de segurança completa do site e guarde uma cópia fora do servidor

Comparação de plugins de pesquisa de ficheiros

1. What the File: identificar o template da página

O What the File acrescenta exatamente uma funcionalidade: um item na barra de ferramentas de administração que mostra qual o ficheiro de template utilizado para a página atual quando passa o cursor sobre ele. Clique no nome e estará no editor de temas do WordPress com o ficheiro certo aberto.

A abreviatura do plugin, WTF, capta na perfeição a emoção que sente quando está a filtrar manualmente uma dúzia de ficheiros à procura de um cabeçalho. O plugin elimina completamente essa dor. Suporta temas padrão, temas filho, bem como BuddyPress e Roots.

Na prática, é útil em dois cenários. Primeiro, quando está a familiarizar-se com o tema de outra pessoa e não sabe onde vive a marcação do cabeçalho ou do rodapé. Segundo, quando precisa de fazer uma edição rapidamente sem vasculhar documentação. Passar o cursor, clicar, editar: três ações em vez de meia hora de procura.

• Vantagens: identificação instantânea do template sem configuração; suporte para temas filho e BuddyPress; funciona imediatamente após a ativação.
• Desvantagens: com alguns temas modernos de editor de blocos mostra apenas o ficheiro principal, não o bloco específico; editar diretamente do painel de administração não é seguro para alterações maiores.
• Preço: Grátis, código aberto.
• Download: 🔗 What the File no WordPress.org

2. String Locator: pesquisar código por palavras-chave

O String Locator resolve o problema oposto: sabe O QUE precisa de alterar (uma frase, classe ou função específica), mas não sabe ONDE está. O plugin analisa todos os ficheiros do tema, plugins e até do núcleo do WordPress e devolve uma lista de correspondências com números de linha.

Funciona de forma simples: vá a Ferramentas → String Locator, introduza a string de pesquisa e clique em «Search». Em poucos segundos obtém uma tabela que mostra a string, o ficheiro e o número da linha. Clicar num resultado abre o editor integrado com o fragmento encontrado destacado. Tanto a pesquisa normal como a pesquisa com regex são suportadas e, a partir da versão 2.6.0, a pesquisa na base de dados também está disponível.

Uma nota importante: antes de guardar as alterações, o plugin executa o Smart-Scan para verificar se quebrou parênteses e aspas correspondentes. Não é uma cura milagrosa, mas protege contra um erro de digitação que envolva uma única chaveta. Ainda assim, faça primeiro uma cópia de segurança, depois edite.

Note que a página do plugin no WordPress.org exibe um aviso: «não testado com as últimas três versões principais». No entanto, na prática, a versão 2.6.7 funciona no WordPress 6.9 sem problemas; verificámo-lo num site de teste. O programador (a equipa InstaWP) lança atualizações de forma consistente, mesmo que não para cada versão menor do núcleo.

• Vantagens: pesquisa todos os ficheiros do site em segundos; pesquisa com regex e na base de dados; Smart-Scan para verificação básica de sintaxe; destaque do texto encontrado no editor.
• Desvantagens: aviso de compatibilidade no WP.org (funciona na prática); em alojamentos fracos, a pesquisa no núcleo pode demorar mais do que o habitual.
• Preço: Grátis, código aberto.
• Download: 🔗 String Locator no WordPress.org

Se aprende melhor visualmente, aqui está um pequeno vídeo sobre como encontrar e editar ficheiros do WordPress. Abrange tanto os métodos integrados (editor de temas, FTP) como a abordagem com plugins.

⁉️🤔 Perguntas frequentes

É seguro editar ficheiros do WordPress diretamente do painel de administração?

A edição direta a partir do painel de administração é um método viável para pequenas alterações de uma ou duas linhas. Mas tem três riscos: não há reversão se cometer um erro, o ficheiro é guardado imediatamente no site ativo e um erro fatal de sintaxe pode deitar abaixo o painel de administração juntamente com o site. A nossa recomendação: para qualquer edição com mais de um par de linhas, utilize FTP/SFTP com um editor local e tenha uma cópia de segurança recente à mão. A regra é simples: faça uma cópia de segurança e depois edite com confiança.

O que devo fazer se o site deixar de carregar após uma edição?

Primeiro, não entre em pânico. Ligue-se ao servidor via FTP e restaure o ficheiro alterado para o seu estado original a partir de uma cópia de segurança. Se não tiver cópia de segurança, desative o plugin problemático renomeando a sua pasta em /wp-content/plugins/ via FTP. Para um tema, renomeie temporariamente a pasta do tema ativo; o WordPress passará automaticamente para um tema padrão. Depois de restaurar a funcionalidade, ative o WP_DEBUG no wp-config.php (define('WP_DEBUG', true)) para ver o erro específico em vez de um ecrã branco.

Posso saltar os plugins e procurar ficheiros manualmente?

Pode, se conhecer a hierarquia de templates do WordPress. Por exemplo, o single.php trata dos artigos individuais, o page.php trata das páginas e o archive.php trata dos arquivos. Um diagrama detalhado está disponível na documentação do WordPress. Mas, na prática, os temas e plugins usam dezenas de ficheiros incluídos (content.php, header-banner.php, e assim por diante) e, sem uma ferramenta como o What the File, perderá tempo a adivinhar.

O que pode substituir o String Locator se este deixar de ser atualizado?

A alternativa mais próxima é o Find Posts, Pages & Users da equipa WP Manage Ninja, mas o seu foco inclina-se mais para o conteúdo do que para o código. Para pesquisa pura de ficheiros, a alternativa direta é pesquisar via SSH: o comando grep -r "search_string" /wp-content/ encontra os mesmos resultados sem um plugin. Se estiver num alojamento sem acesso SSH, o String Locator continua a ser a melhor opção gratuita.

Qual o plugin a escolher e como organizar a edição segura de ficheiros

A tarefa resolve-se com duas ferramentas, não uma, porque cobrem etapas fundamentalmente diferentes. O What the File responde «em que ficheiro está isto?» num segundo através de um clique na barra de ferramentas. O String Locator responde «onde aparece esta string?» em todo o site.

Na prática, usamo-los em conjunto: primeiro o What the File identifica o template, depois o String Locator encontra o fragmento específico dentro desse ou de outro ficheiro. Ambos são gratuitos, ambos se instalam num minuto e não entram em conflito entre si nem com temas e plugins populares.

Uma nota importante sobre os métodos de edição. O editor integrado no painel de administração do WordPress é conveniente para editar uma única linha, mas para trabalho a sério recomendamos a combinação de um cliente FTP e um editor de código local. O fluxo de trabalho é: transfira o ficheiro via FTP para o seu computador, abra-o num editor com destaque de sintaxe (Notepad++, VS Code, Sublime Text), faça as edições, verifique visualmente e carregue-o de volta. Se algo correr mal, renomeie o ficheiro alterado de volta para o original a partir da sua cópia de segurança e o site volta a funcionar num segundo.

Um site de teste não é um luxo; é um seguro. Antes de editar ficheiros num site ativo, pratique numa cópia local. Instale o WordPress localmente via Local by Flywheel ou XAMPP, copie o tema e os plugins e experimente sem o risco de quebrar a produção. Meia hora gasta a configurar um ambiente local poupa horas a restaurar um site ativo.

• Se precisa de compreender rapidamente a estrutura de um tema desconhecido, comece com o What the File.
• Se está à procura de uma frase, classe ou função específica, a sua ferramenta é o String Locator.
• Se está a editar código pela primeira vez, domine o acesso FTP ao seu alojamento e configure um site de teste local antes de fazer a sua primeira edição em produção.

Instale ambos os plugins num site de teste e pratique a localização e edição de ficheiros num ambiente seguro. E diga-nos nos comentários qual foi a ferramenta que acabou por lhe salvar o dia.