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

#Como instalar WordPress em 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.

#WP_ENVIRONMENT_TYPE e constantes de segurança 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.

#Como configurar o lint 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.

#Como ativar o WP_DEBUG sem mostrar 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.

#Como criar blocos WordPress com create-block

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.

#Desativar emojis e XML-RPC 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.

#Como configurar o Composer 2 para gerir plugins e dependências WordPress

O Composer 2 gere pacotes PHP, plugins, temas e ferramentas de desenvolvimento de forma determinística em toda a equipa de engenharia. No desenvolvimento profissional de WordPress, as dependências nunca devem ser guardadas diretamente no controlo de versões como arquivos zip descarregados manualmente do diretório de plugins. Utilizar o Composer permite declarar versões exatas, automatizar atualizações de segurança em pipelines de CI e manter o repositório git limpo.

Plugins e temas disponíveis em WordPress.org podem ser instalados diretamente via Composer através do repositório público WPackagist (wpackagist.org). O pacote composer/installers assegura que os pacotes do tipo wordpress-plugin sejam colocados em wp-content/plugins/ e os do tipo wordpress-muplugin em wp-content/mu-plugins/, em vez de terminarem na pasta padrão vendor/.

Um ficheiro composer.json testado em produção para um projeto WordPress moderno define restrições rigorosas de plataforma PHP, configura os instaladores necessários e inclui dependências essenciais de desenvolvimento:

{
  "name": "wppoland/projeto-wordpress",
  "description": "Configuração para programadores WordPress com Composer 2",
  "type": "project",
  "license": "GPL-2.0-or-later",
  "repositories": [
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    }
  ],
  "require": {
    "php": ">=8.2",
    "composer/installers": "^2.3"
  },
  "require-dev": {
    "squizlabs/php_codesniffer": "^3.11",
    "wp-coding-standards/wpcs": "^3.1",
    "phpstan/phpstan": "^1.12",
    "szepeviktor/phpstan-wordpress": "^1.3",
    "roave/security-advisories": "dev-latest"
  },
  "config": {
    "allow-plugins": {
      "composer/installers": true,
      "dealerdirect/phpcodesniffer-composer-installer": true
    },
    "optimize-autoloader": true,
    "sort-packages": true
  },
  "scripts": {
    "phpcs": "phpcs --standard=WordPress src/",
    "phpcbf": "phpcbf --standard=WordPress src/",
    "phpstan": "phpstan analyse --level=6 src/"
  }
}

Faça commit do ficheiro composer.lock no git. O ficheiro lock garante que todos os programadores da equipa e todos os executores de CI correm exatamente as mesmas versões de pacotes até ao hash de commit. Nos servidores de produção, execute composer install --no-dev --optimize-autoloader durante o deploy. Isto ignora ferramentas exclusivas de desenvolvimento, gera um classmap autoloader otimizado e evita a presença de pacotes de análise no servidor web público.

#Análise estática de código e normas PHP com PHPCS e PHPStan

Enquanto o pacote @wordpress/scripts assegura a qualidade de JavaScript e CSS, a base de código PHP do lado do servidor exige o mesmo rigor. Executar análise estática e verificações de estilo localmente evita que erros de sintaxe, consultas SQL inseguras, saídas de dados sem escape ou nonces em falta cheguem à revisão de código.

#Aplicação de normas WordPress Coding Standards com PHPCS

O ecossistema WordPress mantém normas oficiais de código (WPCS) através do PHP_CodeSniffer. Estas regras verificam convenções de nomenclatura do core, formatação de arrays e vulnerabilidades críticas de segurança, tais como dados em bruto da superglobal $_POST ou ausência de funções de sanitização como sanitize_text_field() e esc_html().

Crie um ficheiro phpcs.xml.dist na raiz do seu repositório:

<?xml version="1.0"?>
<ruleset name="WordPress Project Standards">
  <description>Normas PHPCS para projetos WordPress.</description>
  <file>./src</file>
  <arg name="basepath" value="."/>
  <arg name="colors"/>
  <arg name="extensions" value="php"/>
  <arg name="parallel" value="8"/>

  <rule ref="WordPress-Core"/>
  <rule ref="WordPress-Docs"/>
  <rule ref="WordPress.Security.EscapeOutput"/>
  <rule ref="WordPress.Security.ValidatedSanitizedInput"/>

  <exclude-pattern>*/vendor/*</exclude-pattern>
  <exclude-pattern>*/node_modules/*</exclude-pattern>
  <exclude-pattern>*/build/*</exclude-pattern>
</ruleset>

Execute composer run phpcs localmente antes de abrir um pull request. Havendo violações de formatação, execute composer run phpcbf para corrigir automaticamente espaços, indentação e docblocks sem alterar a lógica da aplicação.

#Análise estática aprofundada com PHPStan e phpstan-wordpress

O PHPCS avalia estrutura e estilo, mas não analisa a consistência de tipos nem a validade do fluxo de chamadas. O PHPStan examina o código PHP sem o executar, detetando métodos inexistentes, tipos incompatíveis em parâmetros e ramos de execução inalcançáveis. Como o WordPress depende fortemente de hooks dinâmicos e variáveis globais, a extensão szepeviktor/phpstan-wordpress fornece ao PHPStan as assinaturas de funções do core, propriedades de WP_Post e argumentos de filtros.

Configure o ficheiro phpstan.neon.dist no nível de regras 6:

includes:
  - vendor/szepeviktor/phpstan-wordpress/extension.neon

parameters:
  level: 6
  paths:
    - src/
  excludePaths:
    - vendor/
    - node_modules/
    - build/

A inclusão do PHPStan no seu pipeline de integração contínua garante que refatorar a assinatura de uma função ou renomear um callback de hook não cause falhas inesperadas no ambiente de produção.

#Como configurar o Xdebug 3 para Docker e depuração passo a passo no IDE

Confiar apenas em instruções var_dump() ou ficheiros de log atrasa a resolução de problemas ao depurar filtros complexos, endpoints da REST API ou transações na base de dados. O Xdebug 3 disponibiliza depuração passo a passo, inspeção da pilha de chamadas e observação de variáveis em tempo real no Visual Studio Code ou PhpStorm.

Em ambientes Docker modernos como o wp-env ou configurações com Docker Compose, o Xdebug 3 é executado dentro do contentor da aplicação e comunica de volta com o seu IDE na máquina do programador. Utilize a configuração moderna de modos do Xdebug:

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug,develop
xdebug.start_with_request=trigger
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.discover_client_host=0

Definir xdebug.start_with_request=trigger é essencial para a produtividade da equipa. Se o Xdebug for acionado em cada pedido HTTP recebido, o tempo de carregamento das páginas aumenta substancialmente. No modo trigger, o depurador só é ativado quando o browser envia o cookie XDEBUG_SESSION ou um parâmetro na query string, o que pode ser gerido facilmente através de extensões de browser como o Xdebug Helper.

No Visual Studio Code, configure o ficheiro .vscode/launch.json com o mapeamento correto de caminhos entre o sistema operativo do computador e o sistema de ficheiros do contentor:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html/wp-content/plugins/meu-plugin": "${workspaceFolder}"
      }
    }
  ]
}

O mapeamento de caminhos garante que os breakpoints definidos no editor coincidam com as linhas em execução dentro do contentor. Nunca ative o Xdebug num servidor de staging ou de produção; a penalização no desempenho reduz a capacidade de resposta e expõe variáveis internas do servidor.

#Constantes avançadas de wp-config para segurança e base de dados

O ficheiro wp-config.php rege o comportamento do runtime antes de o WordPress carregar temas e plugins. Para além dos seletores habituais de depuração, um programador experiente define limites de memória, segurança de cookies, execução de rotinas cron e parâmetros de reparação da base de dados.

#Limites de memória e processos em segundo plano

Por omissão, o WordPress aloca 40 MB de memória PHP para pedidos normais no frontend. Lojas WooCommerce com tráfego elevado, esquemas densos de blocos e pedidos à REST API ultrapassam esse valor rapidamente, originando erros fatais de exaustão de memória. Estabeleça limites explícitos no ficheiro wp-config.php:

define( WP_MEMORY_LIMIT, 256M );
define( WP_MAX_MEMORY_LIMIT, 512M );

A constante WP_MAX_MEMORY_LIMIT entra em vigor nas rotinas da administração e em tarefas pesadas em segundo plano, como o redimensionamento de imagens, importações massivas e migrações de dados.

#Desacoplamento do WP-Cron do tráfego de visitantes HTTP

Por padrão, o WordPress dispara tarefas agendadas durante os carregamentos de página efetuados pelos utilizadores. Em sites de baixo tráfego, as publicações agendadas e rotinas de manutenção acumulam atrasos. Em sites de tráfego intenso, múltiplos pedidos simultâneos geram processos duplicados de cron, provocando picos de ligação à base de dados.

Desative o cron acionado por visitantes no ficheiro wp-config.php:

define( DISABLE_WP_CRON, true );
define( WP_CRON_LOCK_TIMEOUT, 60 );

Em seguida, configure o agendador crontab do sistema operativo no servidor ou num contentor dedicado para invocar o WP-CLI a cada cinco minutos:

*/5 * * * * wp cron event run --due-now --path=/var/www/html > /dev/null 2>&1

#Permissões do sistema de ficheiros e recuperação de tabelas

Quando o WordPress solicita credenciais de FTP durante o carregamento de ficheiros multimédia ou atualizações, alguns programadores optam erradamente por aplicar permissões 777 a pastas inteiras. A abordagem correta é definir explicitamente o método de ficheiros:

define( FS_METHOD, direct );
define( FS_CHMOD_DIR, 0755 );
define( FS_CHMOD_FILE, 0644 );

Em situações de anomalia grave na base de dados, o WordPress disponibiliza uma ferramenta nativa de reparação acessível no endereço /wp-admin/maint/repair.php. Ative-a exclusivamente durante a intervenção técnica:

define( WP_ALLOW_REPAIR, true );

Remova a constante WP_ALLOW_REPAIR logo após concluir a manutenção. Mantê-la ativa permite que qualquer visitante não autenticado execute processos de reparação e otimização na base de dados.

#Checklist antes de lançar um site WordPress

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.

Um setup de programador sem higiene de segredos continua a falhar uma auditoria de segurança WordPress: chaves locais, .env partilhado e clones de staging são os buracos habituais.