Modernização de código legado em WordPress

Código WordPress legado é aquele em que ninguém consegue prever o que uma alteração vai partir. A idade não é o problema: o problema é a falta de medição. Este guia trata de produzir primeiro essas medições e só depois substituir o código numa ordem em que cada passo possa ser desfeito.

Os sites de que falamos reconhecem-se depressa: construídos entre 2015 e 2020, um tema clássico com um functions.php que passou as duas mil linhas, vários plugins à medida sem repositório upstream e uma tabela wp_options que ninguém olhou desde o lançamento. Normalmente continuam a funcionar. O que deixou de funcionar foi a capacidade de os alterar sem sustos.

O WordPress 7.1.1 saiu a 17 de setembro de 2026. A distância entre essa versão e uma stack de 2018 raramente está no núcleo. Está na versão de PHP por baixo, nos scripts que o tema coloca em fila e numa base de dados que passou anos a acumular linhas de plugins que já não existem.

Saiba mais sobre o desenvolvimento WordPress profissional na WPPoland.

#1. Como auditar um WordPress legado

Comece pelos números que se podem ler num site em produção, não por uma opinião sobre o código.

#Versão mínima e recomendada de PHP para WordPress

O mínimo e a recomendação são coisas diferentes. O trunk do WordPress continua a fixar $required_php_version = '7.4' em src/wp-includes/version.php, enquanto a página de requisitos recomenda PHP 8.3 ou superior e MariaDB 10.11 ou MySQL 8.0. Ou seja: o núcleo arranca em 7.4, e arrancar em 7.4 significa fazê-lo sem patches de segurança.

O que decide a migração são as datas do php.net, não uma percentagem de melhoria prometida:

Um plano que aponte para 8.2 tem cerca de três meses de margem. Aponte para 8.3 ou 8.4.

Um site em 7.4, 8.0 ou 8.1 não recebeu nenhuma versão nova quando foram corrigidas as vulnerabilidades críticas do PHP de 21 de outubro de 2026. Os passos para esse site estão em o que fazer com o PHP2Shell num site WordPress.

#Como registar funções descontinuadas em produção sem WP_DEBUG

Esta é a parte que a maioria das auditorias faz mal. O núcleo dispara do_action( 'deprecated_function_run', ... ) dentro de _deprecated_function() antes de verificar WP_DEBUG; a única coisa condicionada é a chamada a trigger_error(). O mesmo vale para deprecated_hook_run, deprecated_argument_run, deprecated_file_included, deprecated_class_run e deprecated_constructor_run. Um mu-plugin pequeno dá-lhe um inventário real do tráfego em produção sem mostrar nada no ecrã:

<?php
// mu-plugins/deprecation-log.php
$hooks = array(
	'deprecated_function_run',
	'deprecated_hook_run',
	'deprecated_argument_run',
	'deprecated_file_included',
	'deprecated_class_run',
	'deprecated_constructor_run',
);

foreach ( $hooks as $hook ) {
	add_action(
		$hook,
		static function () use ( $hook ) {
			error_log( $hook . ' ' . wp_json_encode( func_get_args() ) );
		},
		10,
		4
	);
}

Deixe-o a correr durante um ciclo de negócio completo. Uma importação semanal ou uma página de relatório trimestral tocam em código descontinuado que nenhum rastreio do front-end alcança.

#Como verificar os checksums do WordPress com WP-CLI

wp core verify-checksums e wp plugin verify-checksums comparam o que está instalado com os hashes do WordPress.org. Num site com uma década de história, isto encontra quase sempre um plugin corrigido à mão por alguém que já não está na equipa. Esses ficheiros são os que regridem na atualização seguinte, e são os primeiros que devem entrar em controlo de versões.

#Quantas versões de jQuery carrega um WordPress antigo

Antes de culpar o jQuery, conte quantas cópias existem. O núcleo regista exatamente uma: script-loader.php declara jquery-core na versão 3.7.1 e jquery-migrate na 3.4.1, com jquery como alias que depende de ambos. Se numa página aparecem várias versões, vêm de plugins e temas que colocam em fila a sua própria cópia com outro handle, ou que escrevem uma tag <script src> diretamente no rodapé. wp_scripts()->queue diz-lhe qual é qual num minuto. Remover o registo da jQuery do núcleo para forçar uma cópia de CDN é precisamente a alteração que parte o painel de administração: deixe o handle do núcleo em paz e elimine os duplicados.

O jquery-migrate merece uma decisão à parte. Tirá-lo da fila é uma linha, e se a consola se encher de erros a seguir, esses erros são a lista real de padrões de jQuery 1.x que ainda restam no tema.

#Análise de compatibilidade PHP com PHPCompatibilityWP

O PHPCompatibilityWP existe para que os sniffs não assinalem os polyfills que o núcleo já traz:

vendor/bin/phpcs -p wp-content/themes wp-content/plugins \
  --standard=PHPCompatibilityWP \
  --extensions=php \
  --runtime-set testVersion 8.3-

Sem testVersion, o resultado diz muito pouco. Com ele, obtém uma lista de ficheiros ordenada pelo que o separa da versão a que quer chegar.

O inventário que deve ter no fim da primeira semana tem quatro colunas: versão de PHP atual, descontinuações por endpoint, ficheiros que falham o checksum e erros de PHPCS por plugin. Tudo o que vem depois é priorizado a partir dessa tabela.

Atualização de 28 de outubro de 2026. O PHPCompatibilityWP mostra o que deixa de funcionar numa versão mais recente do PHP. Grande parte das correções pode ser automatizada com o Rector. Segundo as notas de lançamento, a versão 2.8, de 26 de outubro de 2026, é cerca de 26% mais rápida do que a 2.7 e, em PHP 8.3 ou superior com a extensão PHPStan Turbo, cerca de três vezes mais rápida. As regras chegam agora ao resultado numa única passagem e são testadas quanto à idempotência, pelo que uma segunda execução no mesmo ficheiro já não altera nada. Num projeto antigo, a documentação do Rector recomenda ->withPhpLevel(), subindo o nível um passo de cada vez, em vez do ->withPhpSets() completo de uma só vez. Corra cada passagem num ramo próprio e reveja o diff antes de o publicar.

#2. Como refatorizar o WordPress com o padrão strangler fig

Não tente mudar tudo de uma vez. O strangler fig de Martin Fowler, escrito em 2004 e revisto em agosto de 2024, é a única estratégia de reescrita que mantém de pé um site que fatura: coloque o sistema novo ao lado do antigo, envie uma fatia do tráfego para o novo e deixe o antigo encolher até não restar nada para cortar.

O WordPress oferece duas costuras naturais para isto, e ambas estão no núcleo.

#Fase 1: atualizar o núcleo e a infraestrutura

Antes de mexer nos templates, ponha a infraestrutura em condições: PHP num ramo com suporte, WordPress na última versão estável, MySQL 8.0 ou MariaDB 10.11 segundo a página de requisitos, HTTPS em todo o site e cópias de segurança que alguém já tenha efetivamente restaurado.

#Fase 2: migrar templates rota a rota

A primeira costura é template_include. É um filtro, por isso uma única rota pode passar para o código novo enquanto todas as outras continuam a entrar pelos templates antigos. Isso basta para levar a página de contacto, a secção de recrutamento ou um tipo de conteúdo para um template reescrito com os seus próprios recursos, e para o devolver ao lugar com uma linha se a conversão cair.

A segunda é o suporte híbrido de templates de blocos. locate_block_template(), em src/wp-includes/block-template.php, sai cedo a menos que current_theme_supports( 'block-templates' ) seja verdadeiro e, quando esse suporte está declarado, só considera templates de blocos com especificidade igual ou superior à do template PHP que a hierarquia já encontrou. Na prática:

add_action(
	'after_setup_theme',
	static function () {
		add_theme_support( 'block-templates' );
	}
);

A partir daí, um ficheiro templates/page-contact.html dentro do tema clássico fica com essa rota exata. single.php, archive.php e os restantes continuam iguais. Este é o mecanismo que transforma “migrar para blocos” numa série de entregas pequenas, em vez de um fim de semana com um plano de reversão que ninguém testou.

Ordene as fatias por risco, não por entusiasmo. Uma boa primeira fatia é um template com tráfego real, um resultado mensurável e nenhum checkout lá dentro. Uma má primeira fatia é a página inicial, porque lhe dá o maior raio de impacto possível no dia em que menos conhece o código novo.

#Fase 3: retirar os templates PHP antigos

Estrangule os templates PHP antigos até que o site inteiro funcione sobre a stack moderna. Duas regras fazem com que isto se aguente. Cada fatia leva os seus próprios recursos, para que o template novo não herde sem querer a folha de estilos global antiga. E o código antigo é apagado na mesma entrega que o reforma, porque um template morto que fica no repositório vai ser editado por alguém antes de seis meses.

#3. Como limpar a base de dados de um WordPress antigo

Quase todas as queixas de “a base de dados está lenta” num WordPress antigo reduzem-se a três coisas, e só uma tem a ver com o tamanho.

#Como reduzir o autoload de wp_options

O autoload é o que se paga em cada pedido. Desde o WordPress 6.6, a coluna autoload já não guarda apenas yes e no. A nota de desenvolvimento da Options API introduziu on, off, auto-on, auto-off e auto, e wp_filter_default_autoload_value_via_option_size(), em src/wp-includes/option.php, recusa carregar automaticamente qualquer valor serializado que ultrapasse o filtro wp_max_autoloaded_option_size, com 150000 bytes por omissão. Essa proteção atua quando a opção é escrita. Não faz nada com o blob que um plugin desinstalado lá deixou em 2019.

Leia a lista real com SQL, não com o painel de um plugin:

SELECT option_name, LENGTH(option_value) AS bytes, autoload
FROM wp_options
WHERE autoload IN ('yes', 'on', 'auto-on', 'auto')
ORDER BY bytes DESC
LIMIT 25;

Esses quatro valores são os que wp_load_alloptions() trata como carregados automaticamente. Isto importa, porque wp option list --autoload=on --format=total_bytes no WP-CLI só corresponde a autoload='on' OR autoload='yes'. Num site com a 6.6 ou posterior, onde as opções novas entram como auto, esse comando indica uma pegada de autoload menor do que aquela que paga em cada carregamento de página. Use a consulta, ou leia o número do WP-CLI sabendo o que fica de fora.

#Como limpar a postmeta órfã

A postmeta órfã é uma contagem, não um mistério. Conte-a antes de decidir que importa:

SELECT COUNT(*)
FROM wp_postmeta pm
LEFT JOIN wp_posts p ON p.ID = pm.post_id
WHERE p.ID IS NULL;

As linhas sem post sobrevivente podem ser apagadas, e mesmo assim faz-se primeiro um dump da base de dados. A meta que pertence a um plugin que já retirou é uma passagem à parte e mais cuidadosa: agrupe por meta_key, compare os prefixos com os plugins que continua a usar e apague por chave.

As revisões antigas são o terceiro bloco, e o valor de post_type mantém-se em inglês mesmo num site em português:

DELETE FROM wp_posts
WHERE post_type = 'revision'
AND post_date < DATE_SUB(NOW(), INTERVAL 6 MONTH);

#Índices de wp_postmeta, InnoDB e utf8mb4

Os índices são a parte que ninguém lê. src/wp-admin/includes/schema.php dá à wp_postmeta uma chave primária sobre meta_id, uma chave post_id e uma chave meta_key truncada a 191 caracteres, porque o utf8mb4 usa quatro bytes por caractere e o limite histórico de índice era de 767 bytes. Não há índice composto sobre (post_id, meta_key). Uma consulta que filtra pelas duas colunas, que é o que faz um template de arquivo carregado de meta em cada linha, não consegue usar um único índice para ambas. Num site grande, a solução é um índice composto adicionado por migração, não mais uma camada de cache por cima.

Mais duas verificações entram na mesma passagem. Confirme que todas as tabelas são InnoDB, porque uma tabela MyISAM herdada de uma importação do tempo do MySQL 5.1 bloqueia ao escrever e ignora as transações. E confirme que o conjunto de caracteres é utf8mb4: o núcleo escolhe utf8mb4_unicode_520_ci em determine_charset() quando o servidor o suporta, mas uma base criada antes do WordPress 4.2 e migrada com mysqldump continuará em utf8 e continuará a perder em silêncio os caracteres fora do plano básico.

#4. Como modernizar CSS e JavaScript num tema legado

O front-end de um WordPress legado não costuma ser lento por causa da framework que usa. É lento porque nada no tema sabe o que o resto coloca em fila.

#Como dividir um style.css monolítico em módulos

Um tema legado com um único style.css editado à mão e sem bundler não tem forma de entregar uma alteração delimitada. Que o resultado seja Tailwind, CSS modules ou propriedades personalizadas importa muito menos do que conseguir responder a “que seletores precisa este template”. Uma estrutura que permite responder a isso é parecida com esta:

styles/
├── critical.css (inline no <head>)
├── components/
│   ├── header.css (em todas as páginas)
│   ├── blog.css (só nas páginas do blog)
│   └── product.css (só nas páginas de produto)
└── utilities.css (classes utilitárias partilhadas)

Assim que existe um build, o carregamento de recursos por template torna-se possível, e é esse carregamento por template que mexe no caminho de renderização, não a escolha de framework.

#Como carregar scripts com defer e async no WordPress

Use a estratégia de carregamento que o núcleo já traz. Desde o WordPress 6.3, wp_enqueue_script() aceita um array no último parâmetro:

wp_enqueue_script(
	'site-main',
	get_theme_file_uri( 'build/main.js' ),
	array(),
	filemtime( get_theme_file_path( 'build/main.js' ) ),
	array(
		'strategy'  => 'defer',
		'in_footer' => true,
	)
);

A armadilha está documentada na nota de desenvolvimento da 6.3 e implementada em WP_Scripts::filter_eligible_strategies(): o núcleo percorre a árvore de dependências e, se algum script em fila que depende do seu não estiver também diferido, o seu é emitido como bloqueante. Pode pôr defer num handle, não ver nenhum atributo defer no HTML e não ter nada no log. O núcleo escreve data-wp-strategy na tag sempre que foi registada uma estratégia diferida, tenha sido degradada ou não, por isso procurar apenas esse atributo devolve todos os scripts diferidos. O sinal de degradação é uma tag com data-wp-strategy e sem o defer ou async correspondente. Basta um único plugin antigo que coloque em fila um script bloqueante dependente do seu bundle para deitar abaixo a alteração inteira.

Esse mesmo ficheiro rejeita ainda uma estratégia num handle alias, e é por isso que wp_script_add_data( 'jquery', 'strategy', 'defer' ) não faz nada de útil: jquery não tem src.

#Como eliminar o jQuery de um tema legado

O processo é gradual e apoia-se no inventário da secção 1:

1. Listar os handles em fila com wp_scripts()->queue e separar a jQuery do núcleo das cópias duplicadas.
2. Identificar que plugins dependem do handle jquery.
3. Tirar o jquery-migrate da fila e tratar os erros da consola como a lista de trabalho.
4. Substituir as funcionalidades simples por JavaScript nativo.
5. Retirar a dependência quando já não restar nada que a peça.

#5. Como proteger um WordPress antigo

O código legado não é inseguro por ser antigo. É inseguro porque as superfícies que expõe foram configuradas quando os valores por omissão eram outros.

#Ferramentas de análise de segurança para WordPress

Vale mais uma verificação de checksums agendada, um registo de descontinuações e alertas de integridade de ficheiros do que um scanner que devolve uma pontuação de gravidade. As ferramentas habituais para o resto da passagem são o PHPStan para análise estática de PHP, o npm audit para dependências JavaScript e o WPScan para vulnerabilidades já publicadas.

#Como restringir a API REST do WordPress

A API REST não se pode desligar, e os snippets que dizem fazê-lo são piores do que não tocar em nada: o núcleo usa-a para o editor de blocos, o Site Health e as palavras-passe de aplicação. O que pode fazer é exigir autenticação para tudo o que não seja explicitamente público:

add_filter(
	'rest_authentication_errors',
	static function ( $result ) {
		if ( ! empty( $result ) || is_user_logged_in() ) {
			return $result;
		}

		return new WP_Error(
			'rest_not_logged_in',
			__( 'O acesso à API REST requer autenticação.' ),
			array( 'status' => 401 )
		);
	}
);

Depois teste sem sessão iniciada as partes do site que dependem dela: formulários de comentários, blocos de pesquisa, formulários de contacto montados sobre endpoints REST e qualquer consumidor headless. Num site corporativo de marketing, este filtro costuma ser inofensivo. Num site com uma funcionalidade interativa para visitantes anónimos, vai parti-la, e é melhor descobri-lo em staging.

Saiba o que já está restringido antes de acrescentar regras. O endpoint de utilizadores é um susto recorrente, mas WP_REST_Users_Controller aplica has_published_posts nos pedidos de coleção sempre que quem chama não passa em current_user_can( 'list_users' ), o que cobre tanto visitantes sem sessão como contas com poucas permissões. Os tipos de conteúdo que aceita são get_post_types( array( 'show_in_rest' => true ) ), não os públicos, e as duas listas não coincidem. Assim, o endpoint devolve autores que publicaram num tipo exposto em REST, não todas as contas. A enumeração de autores num site corporativo costuma escapar pelos redirecionamentos de /?author=1 e pelos arquivos de autor, não pela REST.

As palavras-passe de aplicação, além disso, são só para HTTPS: wp_is_application_passwords_supported() devolve is_ssl() || 'local' === wp_get_environment_type(). Um site antigo que ainda serve o painel de administração com conteúdo misto sobre HTTP simples não as oferece, e é por isso que as integrações nesses sites acabam por partilhar a palavra-passe real de um administrador. Corrigir o certificado é a correção de segurança; a palavra-passe de aplicação é a consequência.

#Como atualizar as dependências de um WordPress antigo

Cada biblioteca de terceiros é atualizada ou substituída:

• Bibliotecas PHP com vulnerabilidades publicadas
• Componentes JavaScript com CVE ativos
• Fontes e recursos carregados a partir de CDN de terceiros
• Integrações com APIs já descontinuadas

Faça ao mesmo tempo o inventário de plugins, porque cada plugin que retira é uma superfície que deixa de ter de manter.

#6. Como migrar para o Gutenberg a partir de um tema clássico

#Compatibilidade entre um tema legado e o Gutenberg

Em temas construídos entre 2015 e 2018, o suporte ao Gutenberg ativa-se por partes. add_theme_support( 'block-templates' ) é o interruptor que abre a migração template a template da secção 2; o resto são ajustes do editor:

add_action('after_setup_theme', function() {
    // Suporte básico de blocos
    add_theme_support('wp-block-styles');
    add_theme_support('align-wide');
    add_theme_support('responsive-embeds');

    // Paleta de cores do tema legado
    add_theme_support('editor-color-palette', [
        ['name' => 'Primário', 'slug' => 'primary', 'color' => '#1a1a2e'],
        ['name' => 'Secundário', 'slug' => 'secondary', 'color' => '#16213e'],
    ]);
});

O esquema do theme.json vai na versão 3. Não existe uma versão 4, por isso qualquer exemplo que a declare fará com que o núcleo ignore o ficheiro.

#Como migrar do Elementor ou do Divi para o Gutenberg

A migração do Elementor, Divi ou Visual Composer para o Gutenberg segue um processo estruturado:

1. Inventário: documentar cada página e o seu construtor atual
2. Priorização: começar pelas páginas com mais tráfego
3. Conversão: recriar os layouts com padrões de blocos
4. Verificação: comparar visual e funcionalmente
5. Ativação: mudar página a página com redirecionamentos de teste
6. Limpeza: desativar o page builder antigo quando todas as páginas estiverem migradas

Verifique a versão do construtor na API de plugins do wordpress.org (api.wordpress.org/plugins/info/1.0/elementor.json para o Elementor, que a 12 de outubro de 2026 publica a 4.3.4 como estável) e não no readme.txt do repositório, que fica desatualizado.

#7. Como medir o sucesso de uma modernização WordPress

Não prometa percentagens antes de medir. O que se pode fixar antes de começar é o instrumento com que cada coisa vai ser verificada, e o valor de partida do site tal como está hoje.

Do lado do negócio, o único número honesto antes de começar é o que já tem: tráfego orgânico, conversão e custo de manutenção atuais. A comparação faz-se depois, contra essa mesma linha de base e com a janela de medição decidida de antemão.

#8. Auditoria e modernização de WordPress com a WPPoland

Na WPPoland trabalhamos o resgate de sites WordPress, e sempre por esta ordem.

1. Due diligence e auditorias: entregamos o inventário técnico da secção 1, com prioridades e o custo estimado de cada intervenção.

2. Lançamentos incrementais: modernizamos por etapas, cada uma com o seu critério de aceitação e a sua forma de reverter.

3. Objetivos medidos, não prometidos: acordamos que métrica se mexe, com que instrumento se mede e em que janela, antes de tocar no código. O que não se puder medir não entra no âmbito.

4. Transferência de conhecimento: documentamos o processo e formamos a sua equipa para que mantenha o código modernizado por conta própria.

#9. Por onde começar a modernizar um WordPress legado

Um site WordPress legado não é automaticamente um peso morto. O peso morto é a dívida técnica que ninguém gere, e a diferença entre os dois casos está em saber se alguém consegue dizer quanto custa uma alteração antes de a fazer.

A sequência deste guia é deliberada. Meça a distância de PHP face às datas do php.net, recolha descontinuações do tráfego real com os hooks que o núcleo já dispara, verifique os ficheiros contra os checksums e só depois estrangule os templates rota a rota com template_include ou block-templates. Corrija o autoload e os índices da postmeta, porque estão em cada pedido. Corrija o carregamento de scripts, porque o núcleo lhe dá o mecanismo e os plugins antigos tiram-lho em silêncio. Tudo o resto é uma preferência enquanto isso não estiver feito.

Se o site continua com uma stack de 2018, a primeira entrega não é código. É um documento: versão de PHP, registo de descontinuações, falhas de checksum, lista de plugins com responsável e os templates que carregam o tráfego. Se quiser esse plano escrito para o seu repositório, fale connosco sobre modernização e desenvolvimento em WordPress.

O seu site empresarial está parado em 2018? Escreva à WPPoland para uma auditoria e comece pelo inventário, não pela reescrita.

#Recursos relacionados

• Desenvolvimento WordPress profissional: modernização empresarial
• Otimização de velocidade WordPress: desempenho após a modernização
• Auditoria de segurança WordPress: segurança para código legado
• Redesign de sites WordPress: modernização visual completa
• Migração do WordPress para Astro e Next.js: arquiteturas modernas depois da refatorização