Escrever código para WordPress e o seu colega de equipa pedir-lhe constantemente para «limpar espaços e indentação» em cada revisão de código? Ou o seu site ir abaixo após uma atualização de plugin e não conseguir encontrar o erro nos logs porque o código foi escrito sem qualquer padrão consistente?

Este é um cenário familiar para qualquer pessoa que desenvolva para WordPress em equipa. Diferentes hábitos de formatação, alguns usam condições Yoda e outros não, e falta escape de saída em vários sítios.

O PHP CodeSniffer resolve isto automaticamente: verifica o seu código em relação às normas de codificação do WordPress diretamente no seu editor, destaca as violações e pode corrigi-las com um único comando. Abaixo encontra um guia de configuração a partir do zero para o PhpStorm 2026.

💡 Visão geral rápida:

• Instale o PHP CodeSniffer e as WordPress Coding Standards via Composer, seja no seu projeto ou globalmente
• Defina o caminho para o phpcs na configuração e adicione a norma WordPress
• Configure um interpretador PHP remoto se estiver a trabalhar através de Vagrant, Docker ou SSH
• Ative a inspeção PHP CodeSniffer Validation no PhpStorm e os erros serão destacados em tempo real
• Configure a formatação automática através do PHP Code Beautifier and Fixer para corrigir o código com um único comando

Vídeo passo a passo em inglês (os mesmos passos do texto):

Passo 1: configurar um interpretador PHP remoto

Se estiver a desenvolver com PHP local (XAMPP, MAMP, Local, servidor integrado), salte este passo. Para Vagrant, Docker ou um servidor remoto via SSH, precisa de especificar o interpretador explicitamente.

Abra Settings → PHP (Ctrl+Alt+S), clique em […] ao lado de CLI Interpreter e selecione SSH Credentials ou Docker Compose.

Preencha:

• Endereço IP do host, o mesmo utilizado para o site (ping example.dev ajudará)
• vagrant para nome de utilizador e palavra-passe (se usar Vagrant)
• /usr/bin/php, caminho para o executável PHP no servidor

Guarde e selecione o interpretador criado na lista:

O PhpStorm usará este PHP específico para executar o CodeSniffer e outras ferramentas de qualidade de código.

Passo 2: instalar o PHP CodeSniffer via Composer

A abordagem mais fiável é instalar o PHPCS como uma dependência do projeto. Adicione ao seu composer.json:

1
{
2
  "require-dev": {
3
    "squizlabs/php_codesniffer": "^3.10"
4
  }
5
}

Depois execute composer install. O PhpStorm detetará automaticamente o phpcs e o phpcbf em vendor/bin, pelo que não precisará de definir os caminhos manualmente.

Para instalação global (se precisar dela em todos os projetos):

1
composer global require "squizlabs/php_codesniffer=*"

Verifique: o executável phpcs deve estar em ~/.composer/vendor/bin/ (Linux/Mac) ou %APPDATA%/Composer/vendor/bin/ (Windows).

Passo 3: instalar as WordPress Coding Standards

As WPCS são um conjunto de regras (sniffs) para o PHPCS que verificam a conformidade especificamente com as normas do WordPress: escape de saída, condições Yoda, prefixos de funções e tudo o resto do Manual de Normas de Codificação do WordPress.

Via Composer no seu projeto:

1
composer require --dev wp-coding-standards/wpcs:"^3.0"

Ou globalmente (o método antigo e comprovado):

1
composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Certifique-se de que a norma aparece em ~/.composer/wpcs/ ou vendor/wp-coding-standards/wpcs/.

Passo 4: definir o caminho para a norma na configuração do PHPCS

Navegue até à pasta do phpcs e especifique onde as normas instaladas estão localizadas:

1
cd ~/.composer/vendor/bin
2
phpcs --config-set installed_paths ~/.composer/wpcs

Verifique se o WordPress aparece na lista de normas disponíveis:

1
phpcs -i

O resultado deve mostrar quatro normas: WordPress, WordPress-Core, WordPress-Docs e WordPress-Extra.

Passo 5: adicionar o phpcs ao PATH

Abra o ~/.bash_profile (ou ~/.zshrc para ZSH) e adicione a linha:

1
PATH=$PATH:~/.composer/vendor/bin

Reinicie o seu terminal ou execute source ~/.bash_profile. Agora o comando phpcs está disponível a partir de qualquer pasta.

Teste-o em qualquer ficheiro de tema ou plugin:

1
cd wp-content/themes/your-theme
2
phpcs --standard=WordPress functions.php

Um resultado bem-sucedido tem este aspeto:

Os erros dividem-se em dois níveis: ERROR para violações graves e WARNING para recomendações. Cada linha contém o número da regra e uma descrição do problema.

Passo 6: configurar o PHP CodeSniffer no PhpStorm

Abra Settings → PHP → Quality Tools → PHP_CodeSniffer (Ctrl+Alt+S).

Se instalou via Composer no seu projeto, o PhpStorm detetará automaticamente o phpcs em vendor/bin. Se instalou globalmente, clique em […] ao lado de Configuration e especifique o caminho para o executável: ~/.composer/vendor/bin/phpcs.

Selecione o interpretador de PHP da lista, o mesmo que configurou no passo 1.

Passo 7: ativar a inspeção de validação do PHP CodeSniffer

Vá a Settings → Editor → Inspections, expanda PHP → Quality Tools e assinale PHP_CodeSniffer validation.

No menu suspenso Norma de codificação, selecione WordPress. Guarde as definições.

A partir deste momento, o PhpStorm verifica os ficheiros PHP abertos em tempo real. As infrações são realçadas com sublinhados ondulados, tal como os erros normais do IDE. Passe o cursor sobre eles e aparece uma dica com a descrição: o que está errado e como corrigir.

Passo 8: verificar se funciona

Crie ou abra qualquer ficheiro PHP de um tema e escreva código intencionalmente fora da norma:

1
if(true){echo 'Spaces? Never heard of them';}

O PhpStorm vai sublinhar a linha: faltam espaços depois do if, à volta das chavetas e dentro da condição. Passe o cursor e verá o texto do erro e o número da regra do WordPress.

Passo 9: configurar a correção automática com o PHP Code Beautifier and Fixer

Não precisa de corrigir cada infração manualmente. O PHP Code Beautifier and Fixer (phpcbf) é instalado juntamente com o PHPCS e pode corrigir automaticamente o código de acordo com a norma selecionada.

Abra Settings → PHP → Quality Tools, na secção External Formatters selecione PHP Code Beautifier and Fixer. Agora, quando invocar Code → Reformat Code (Ctrl+Alt+L / Cmd+Option+L), o PhpStorm não só alinha a indentação com o seu próprio formatador, como também aplica as regras do WordPress através do phpcbf.

Além disso, configure o estilo de código WordPress para o formatador integrado: Settings → Editor → Code Style → PHP → Set From → Predefined Style → WordPress. Desta forma, ambas as ferramentas trabalham no mesmo sentido e não entram em conflito.

Passo 10: o que fazer em novos projetos

Para cada novo projeto WordPress, basta repetir o passo 1 (interpretador, se for remoto), o passo 6 (definir o phpcs nas definições) e o passo 7 (ativar a inspeção). Se estiver a usar o Composer no seu projeto, os passos 2 a 4 ficam resolvidos com uma única linha: composer require --dev wp-coding-standards/wpcs.

⁉️🤔 Perguntas frequentes

Qual é a diferença entre WordPress, WordPress-Core, WordPress-Docs e WordPress-Extra?

WordPress é o conjunto base de todas as regras, exceto documentação. WordPress-Core contém apenas as regras do guia de codificação oficial (indentação, nomenclatura, condições Yoda). WordPress-Extra acrescenta verificações de segurança: escape de saída, validação de dados de entrada. WordPress-Docs verifica as normas de documentação do código (PHPDoc). Na prática, utilize WordPress porque inclui o Core e o Extra.

O PhpStorm não deteta o phpcs após a instalação. O que devo fazer?

Verifique se a pasta vendor/bin (ou ~/.composer/vendor/bin) está adicionada ao PATH e contém o executável phpcs. No PhpStorm, abra Settings → PHP → Quality Tools → PHP_CodeSniffer, clique em […] e especifique manualmente o caminho para o phpcs. Após alterar o interpretador ou reinstalar dependências, poderá ser necessário repor a configuração usando o botão Reset na mesma janela.

Posso usar o PHPCS sem o Composer, apenas descarregando o arquivo phar?

Sim, mas não recomendamos. Ao instalar via Composer, o PhpStorm deteta automaticamente o phpcs, o phpcbf e todos os standards registados. Com o arquivo phar, terá de definir os caminhos manualmente e acompanhar as atualizações separadamente. Para colaboração em equipa, uma dependência do Composer no composer.json fixa a versão, para que todos os developers tenham o mesmo conjunto de regras.

Como excluo ficheiros ou pastas específicos da verificação?

Crie um ficheiro phpcs.xml na raiz do seu projeto. Pode excluir diretórios (<exclude-pattern>vendor/*</exclude-pattern>), definir o standard e alterar a gravidade de regras individuais. O PhpStorm irá detetar automaticamente este ficheiro se estiver na raiz do projeto e tiver o nome phpcs.xml ou phpcs.xml.dist.

Porque é que o PHPCS se queixa de wp_redirect() sem exit?

O standard do WordPress exige exit ou wp_die() após qualquer redirecionamento: o wp_redirect() apenas define o cabeçalho, mas não interrompe a execução do script. Sem o exit, o código após o redirecionamento continuará a ser executado, o que constitui uma falha de segurança. Utilização correta: wp_redirect( home_url() ); exit;.

O que fazer se a sua base de código já for grande e estiver apenas a implementar standards

Executar o PHPCS num projeto com milhares de violações é uma forma garantida de desmotivar a sua equipa. Comece com pouco: corrija os erros críticos (error, não warning) usando o phpcbf e, depois, baixe gradualmente o limite. Adicione um phpcs.xml com exclusões para código legado e ative novas regras, uma de cada vez, a cada mês.

Eis um plano passo a passo para implementar standards num projeto ativo:

• Execute phpcs --standard=WordPress --report=summary para ver o número total de erros.
• Corrija automaticamente tudo o que for possível: phpcbf --standard=WordPress .
• Ordene os erros restantes por gravidade, abordando primeiro os críticos.
• Adicione a verificação ao CI (GitHub Actions, GitLab CI): faça com que a build falhe em novas violações nos pull requests.

Comece com um simples composer require --dev wp-coding-standards/wpcs num projeto. Após uma semana, a equipa habituar-se-á ao realce. Após um mês, estarão habituados a código limpo. Que standard de codificação utiliza? Conte-nos nos comentários.