Configuração WordPress para programadores: local, lint e blocos

A instalação de cinco minutos dá-lhe um site a correr. Não dá uma estação de trabalho de programador. Em 2026 uma configuração WordPress sólida é um stack local que se recria, um pipeline de lint alinhado com o core, depuração segura que nunca pinta erros no frontend e tooling de blocos que envia os mesmos assets que testa.

Este guia é a checklist que usamos ao provisionar um novo repositório de tema ou plugin: tipo de ambiente, wp-env, @wordpress/scripts, constantes de debug e uma camada fina de hardening em wp-config.php e mu-plugins. Em projetos com equipas em Lisboa e Porto, o mesmo .wp-env.json no git corta o debate “na minha máquina funciona”.

#Ambiente local com wp-env

Instalações manuais de Apache e PHP divergem. Uma máquina corre PHP 8.2, outra ainda tem 8.1, e os builds de blocos falham só no CI. O caminho oficial é wp-env: contentores Docker para WordPress, MySQL e ferramentas opcionais, controlados por um .wp-env.json na raiz do projeto.

Instale uma vez globalmente ou como dependência do projeto:

npm install --save-dev @wordpress/env
npx wp-env start

Configuração mínima para um plugin em desenvolvimento:

{
  "core": "WordPress/WordPress#6.7",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG": true,
    "WP_DEBUG_LOG": true,
    "WP_DEBUG_DISPLAY": false,
    "SCRIPT_DEBUG": true
  }
}

Porque isto ganha a um stack genérico no trabalho de plugins:

• A versão do core fica fixada no git, por isso “funciona na minha máquina” deixa de ser discussão.
• wp-env run cli dá WP-CLI dentro dos mesmos contentores que o browser usa.
• Testes e scripts e2e em @wordpress/scripts esperam este layout.

Combine com a documentação do ambiente de desenvolvimento do editor de blocos quando precisar de notas sobre Node, create-block e extensões de editor recomendadas.

Para trabalho de agência ainda em temas PHP clássicos, pode manter um binário PHP no host para scripts pontuais, mas mantenha o site em si no wp-env para que media, cron e rewrites coincidam com o staging.

Comandos úteis do dia a dia depois do stack estar no ar:

npx wp-env run cli wp plugin list
npx wp-env run cli wp cache flush
npx wp-env logs
npx wp-env stop

Mapeie um domínio custom no ficheiro hosts só quando o projeto precisa de cookies ou SSO que o localhost parte. Caso contrário o URL por omissão chega e mantém os certificados simples.

Quando um colega clona o repo, a nota de onboarding deve ter três linhas: instalar Docker, npm install, npx wp-env start. Qualquer coisa mais longa costuma significar que o ambiente escapou para pacotes de host não documentados.

#Tipo de ambiente e disciplina no wp-config

Desde o WordPress 5.5, WP_ENVIRONMENT_TYPE é o interruptor que cada plugin deve ler. Defina-o cedo no wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' ); // local | development | staging | production

Depois ramifique o comportamento sem inventar constantes próprias:

if ( wp_get_environment_type() === 'production' ) {
	// Cache ligado, logging verboso desligado.
} else {
	define( 'SCRIPT_DEBUG', true );
}

Constantes de hardening que pertencem a cada boilerplate de produção:

define( 'DISALLOW_FILE_EDIT', true );
define( 'FORCE_SSL_ADMIN', true );
define( 'WP_POST_REVISIONS', 5 );
define( 'AUTOMATIC_UPDATER_DISABLED', true ); // quando o deploy gere updates do core

Use DISALLOW_FILE_MODS só quando a árvore inteira é imutável e as atualizações entram por CI. Em hosts geridos que ainda patcham plugins no dashboard, essa constante vai lutar com o host.

Chaves de autenticação e salts não são decoração. Rode-as após um compromisso; todas as sessões terminam de imediato. Guarde a rotação no runbook de deploy, não num post-it.

#Linting com @wordpress/scripts

Linting é como se mantém compatível com o Gutenberg sem memorizar cada regra ESLint. O pacote @wordpress/scripts envolve webpack, Babel, ESLint, Stylelint, Jest e Playwright atrás de scripts npm familiares.

Superfície típica de package.json para um plugin de blocos:

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-css",
    "lint:pkg-json": "wp-scripts lint-pkg-json",
    "format": "wp-scripts format",
    "packages-update": "wp-scripts packages-update"
  }
}

Corra npm run lint:js no CI em cada pull request. Formate com Prettier via wp-scripts format para que os diffs sejam sobre lógica, não estilo de aspas.

O PHP ainda precisa da sua própria porta. Instale WordPress Coding Standards (WPCS) via Composer e corra PHPCS em temas e plugins. Não espere que @wordpress/scripts substitua isso; cobre a metade JS e CSS do stack.

Ordem prática de CI que apanha a maior parte das regressões:

1. composer phpcs (ou o seu wrapper PHPCS)
2. npm run lint:js e npm run lint:css
3. npm run build para um webpack partido falhar antes da review
4. Opcional: wp-env start e depois PHPUnit do plugin ou Playwright do pacote de scripts

Ignore o output gerado em build/ nas reviews de git, salvo se o projeto commit’tar assets compilados de propósito para hosts sem Node. Prefira build no CI ou no deploy. EditorConfig mais a config Prettier por omissão do pacote scripts mantém guerras de indentação fora dos pull requests.

Se um tema legado ainda envia scripts de admin da era jQuery, introduza @wordpress/scripts primeiro para blocos novos em vez de reescrever cada enqueue no dia um. Stacks mistos são aceitáveis; regras misturadas não. Uma config ESLint por diretório de pacote.

#Depuração sem vazar erros

Nunca mostre erros PHP aos visitantes. Registe-os.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // escreve em wp-content/debug.log por omissão
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Melhor: aponte WP_DEBUG_LOG para um caminho fora da document root e negue acesso HTTP a qualquer debug.log residual em wp-content. Em produção, deixe WP_DEBUG a false salvo em incidente ativo. Ligue SAVEQUERIES só para sessões curtas de profiling; custa memória e não deve ficar ligado de noite.

Complemente as constantes com ferramentas que explicam o que aconteceu:

• Query Monitor para hooks, pedidos HTTP e queries lentas na barra de admin
• Xdebug ligado ao contentor PHP do wp-env quando precisa de step-through
• DevTools do browser com SCRIPT_DEBUG para carregar scripts do core não minificados ao caçar um conflito

Quando o staging fica ecrã branco, veja debug.log, o log de erros do host e wp-env logs (se for local) antes de instalar outro plugin de “debug”. A maior parte das outages de produção por misconfiguração aparece como um fatal único no log, não como uma feature em falta.

Reproduza o bug numa instância wp-env descartável com o mesmo conjunto de plugins antes de mudar constantes em produção. Se o problema só aparece com object cache ou CDN, anote isso no ticket; o Docker local não inventa Redis por si a menos que o adicione à config do env.

#Tooling de blocos em 2026

Blocos interativos já não são projetos laterais. O caminho por omissão atual é:

1. Gere com npx @wordpress/create-block my-block --variant dynamic (ou static, conforme a estratégia de render)
2. Desenvolva contra wp-env para que o registo via block.json bata com um admin real
3. Use npm start para watch builds e npm run build para assets de produção
4. Registe o bloco em PHP com register_block_type( __DIR__ . '/build' ) quando a metadata vive em block.json

Mantenha scripts de editor e frontend separados em block.json para não enviar React só de editor a cada visitante. Prefira viewScript / viewStyle para interatividade no frontend em vez de despejar tudo num bundle.

Em temas que ainda fazem enqueue de assets clássicos, migre peças interativas novas para blocos de forma incremental. Um tema híbrido pode enviar block patterns e alguns blocos custom enquanto o resto dos templates fica em PHP. Isso é normal em 2026; um rewrite completo do Site Editor é decisão de produto, não requisito de tooling.

Quando as dependências divergem, npx wp-scripts packages-update atualiza pacotes @wordpress/* dentro da toolchain de scripts. Fixe majors em package-lock.json e reveja o lockfile nos PRs da mesma forma que atualizações Composer.

#Limpeza fina do core com um mu-plugin

Não precisa de um plugin “desativar tudo” do diretório. Um pequeno must-use mantém as regras em controlo de versão:

<?php
/**
 * Plugin Name: Lean core
 */

remove_action( 'wp_head', 'print_emoji_detection_script', 7 );
remove_action( 'wp_print_styles', 'print_emoji_styles' );
remove_action( 'wp_head', 'wp_generator' );
add_filter( 'xmlrpc_enabled', '__return_false' );

Desative XML-RPC só quando tiver a certeza de que nenhum cliente remoto o precisa. Desative scripts de emoji quando controla ícones de marca e quer menos pedidos no frontend. Deixe RSS em sites de conteúdo; sites brochure podem fechar feeds com um hook intencional, não um snippet aleatório de fórum.

#Lista de verificação de lançamento

Antes de um site de cliente ir ao ar:

1. WP_ENVIRONMENT_TYPE é production.
2. DISALLOW_FILE_EDIT é true; SSL no admin está forçado.
3. Revisões estão limitadas; display de debug está desligado.
4. Local e CI partem do mesmo .wp-env.json e passam lint e build do @wordpress/scripts.
5. Assets de blocos são builds de produção, não restos do modo watch.
6. Salts são únicos; debug.log não é acessível via web.

Uma configuração WordPress que se recria a partir do git vale mais do que um wp-config.php engenhoso sozinho. Paridade local, portas de lint e logging honesto são o que impede o trabalho de blocos e o PHP clássico de se atropelarem.

Precisa de uma revisão sénior de um stack existente ou de um plugin de blocos novo? Fale com um desenvolvedor WordPress na WPPoland.