CNN Brasil Docs

Menu

Últimas publicações

Boas Práticas com PHPCS no WordPress

Por

João Carvalho

em

1. Objetivo

Esta documentação descreve as melhorias implementadas no fluxo de verificação de padrão de código PHP no projeto, utilizando PHPCS, hooks de pré-commit e scripts auxiliares, além de consolidar boas práticas para desenvolvimento WordPress. O objetivo é garantir qualidade, consistência e manutenibilidade do código do projeto.

2. Implementações

2.1 Hooks de Pré-Commit

  • O hook de pré-commit roda automaticamente o script phpcs-pre-commit.sh antes de qualquer commit.
  • Função principal: garantir que todos os arquivos PHP modificados sigam o padrão de código definido.
  • Benefícios:
    • Evita envio de código fora do padrão para o repositório.
    • Permite detecção antecipada de inconsistências.

Exemplo de configuração do hook (em .git/hooks/pre-commit):

#!/bin/sh
# Executa o PHPCS apenas nos arquivos alterados
bash .scripts/phpcs-pre-commit.sh

Exemplo de uso no fluxo de trabalho:

# Modificação de arquivos PHP via terminal ou IDE
git add plugins/cnn-editorial-analyzer/cnn-editorial-analyzer.php

# Tentativa de commit
git commit -m "Corrige validação de inputs no plugin Editorial Analyzer"

Nesse momento, o hook será executado automaticamente:

  • Se o código não estiver de acordo com os padrões, o commit será bloqueado e o desenvolvedor verá as recomendações do PHPCS no terminal.
  • Se o código estiver correto (ou após correções com composer phpcs-style-fix), o commit será concluído normalmente.

2.2 Scripts Composer

Verificar recomendações de estilo

Exemplos de uso:

  • composer phpcs-style
    • Verifica apenas as linhas alteradas nos arquivos incluídos no commit, utilizando o phpcs-changed
  • composer phpcs-style plugins/cnn-editorial-analyzer/cnn-editorial-analyzer.php
    • Verifica somente as linhas alteradas de um único arquivo incluído no commit, utilizando o phpcs-changed.

Executa a verificação de arquivos PHP modificados adicionados ao commit, garantindo que estejam de acordo com o padrão de código definido:

bash .scripts/phpcs-diff-check.sh

Aplicar recomendações de estilo automaticamente

  • composer phpcs-style-fix
    • Permite corrigir automaticamente todos arquivos adicionados ao commit
  • composer phpcs-style-fix plugins/cnn-editorial-analyzer/cnn-editorial-analyzer.php
    • Permite corrigir automaticamente um arquivo específico adicionados ao commit

⚠️ Importante: o fixer atua sobre o arquivo inteiro, não apenas nas alterações recentes. Isso ocorre porque, ao modificar apenas linhas específicas, o fixer não teria o contexto necessário das demais partes do arquivo para garantir a consistência da formatação:

bash .scripts/phpcs-diff-fix.sh

Esses scripts permitem integração direta com o fluxo de desenvolvimento, evitando a execução manual de comandos complexos e garantindo consistência no código.

2.3 PHPCS Diffs

  • O script foi configurado para analisar apenas arquivos PHP modificados (git diff).
  • Benefícios:
    • Redução significativa do tempo de execução.
    • Foco apenas nas alterações recentes, mantendo a produtividade do desenvolvedor.

2.4 Novas Regras de Padrão de Código

As regras abaixo foram configuradas para garantir consistência, legibilidade e aderência aos padrões VIP e PSR-12 no código PHP do projeto:

Padrões VIP e WordPress

  • WordPress-VIP-Go e WordPressVIPMinimum: seguem recomendações de código do VIP Coding Standards.

Formatação e estilo (PSR-12)

  • Aplica regras de formatação e estilo do PSR-12.
  • Padroniza espaçamento, indentação e limites de linha.

Nomenclatura

  • Variáveis e funções devem estar em camelCase.
  • Classes e métodos seguem padrões claros de identificação.

DocBlocks e comentários

  • Funções e classes devem ter DocBlocks com @param e @return, melhorando documentação e tipagem.
  • Obs: Use extensões da IDE para facilitar o preenchimento das informações

Arrays

  • Uso de [] obrigatório, evitando array() antigo.
  • Padronização de indentação em arrays multilinha.
  • Espaçamento interno consistente dentro de [].

Limites de linhas

  • Limite recomendado: 120 caracteres.
  • Limite absoluto: 180 caracteres.

Estruturas de controle

  • Padronização de if, for, while e switch.
  • Uso obrigatório de elseif em vez de else if.
  • Proíbe múltiplas instruções na mesma linha.
  • Espaçamento interno consistente e alinhamento correto das chaves.

Classes e funções

  • Alinhamento, posição de chaves e espaçamento validados.
  • Declarações multilinha de funções validadas quanto à indentação.

Indentação e espaços

  • Tabs proibidos, uso de espaços obrigatórios.
  • Controle de indentação em blocos de código e escopos.
  • Espaçamento entre argumentos em funções validado.

3. Boas Práticas para WordPress

3.1 Padrões de Desenvolvimento

  • Namespaces e PSR-4 para autoload de classes.
  • Classes específicas com sufixos claros: Entity, Repository, Service.
  • Funções e variáveis em camelCase.

3.2 Segurança

  • Sempre sanitizar e validar inputs (sanitize_text_field, wp_kses, etc.).
  • Escapar saídas (esc_html, esc_attr, wp_kses_post).
  • Usar nonces para validação de formulários.

3.3 Manutenção e Testes

  • Cobertura mínima de testes unitários e de integração para funcionalidades críticas.
  • Revisões de código obrigatórias em Pull Requests.
  • Documentação clara dos hooks e endpoints.

3.4 Performance

  • Evitar queries diretas sem necessidade.
  • Cachear resultados quando possível (transients, object cache, Redis).
  • Minimizar hooks e filtros desnecessários.
  • Nunca implementar consultas ou lógicas em um construtor