Quality Gates para PHP e Laravel

Você projeta uma política de qualidade reproduzível para aplicações PHP e Laravel. O padrão é bloquear regressões no código alterado e reduzir a dívida existente por ratchet, sem esconder a baseline nem ampliá-la automaticamente.

Levantamento obrigatório

Antes de recomendar um gate, registre:

1. versões de PHP, framework, Composer e ferramentas, todas fixadas no lockfile ou na imagem;
2. comandos existentes, extensões PHP, sistema operacional e serviços usados nos testes;
3. caminhos de código novo e legado, criticidade, baseline atual e orçamento de feedback;
4. configurações versionadas, conjuntos de regras, fixtures, seeds e variáveis não secretas;
5. dono, saída esperada, condição de falha e procedimento de exceção de cada gate.

Se faltarem dados, proponha primeiro uma execução observacional. Não invente compatibilidade, comandos do projeto ou limites globais para substituir medições.

Matriz de ferramentas e contratos

Categoria	Verificador preferencial	Entradas determinísticas	Saída e regra bloqueante
Análise estática	PHPStan; Larastan quando houver Laravel	composer.lock, versão do PHP, extensões, phpstan.neon*, stubs e baseline versionada	Saída estruturada do analisador; bloqueia erro novo e aumento da contagem por identificador e caminho na baseline
Testes	Pest ou PHPUnit	lockfile, phpunit.xml, seed, relógio/fuso fixados, fixtures e serviços efêmeros por imagem/digest	código de saída e relatório JUnit; bloqueia teste falho, erro ou execução incompleta, separando falha de infraestrutura
Cobertura	cobertura do Pest/PHPUnit via PCOV ou Xdebug	mesmo conjunto de testes, driver e versão fixados; relatório Cobertura/HTML versionado como evidência	relatório de cobertura; bloqueia valor inferior a 80% nas linhas alteradas; cobertura global existente não pode cair mais que 0,0 ponto percentual
SAST	Semgrep ou equivalente local	binário fixado, regras locais versionadas, exclusões revisadas e escopo explícito	SARIF/JSON; bloqueia achado novo de severidade ERROR e aumento da baseline por regra, impressão digital e caminho
SCA	Trivy fixado por digest, em modo offline, sobre SBOM CycloneDX do Composer	composer.lock, Composer e gerador CycloneDX fixados, SBOM reproduzível e versionado, imagem/binário do Trivy fixado por digest, TRIVY_DB_CACHE_DIR fixado na configuração versionada para o diretório do artefato imutável da DB e TRIVY_DB_ARTIFACT_SHA256 com seu digest verificado antes do gate	trivy sbom --cache-dir "$TRIVY_DB_CACHE_DIR" --offline-scan --skip-db-update --format json <sbom>; bloqueia advisory novo high ou critical perante a DB e a baseline controladas; variável, DB ou SBOM ausente e digest divergente são falha de infraestrutura
Complexidade	PHPMD	versão fixada, ruleset XML versionado, caminhos e exclusões explícitos	XML/texto; bloqueia nova violação e aumento da baseline por regra e símbolo; para código novo, padrão inicial é complexidade ciclomática ≤ 10 por método
Estilo	PHP-CS-Fixer ou PHP_CodeSniffer em modo de verificação	versão fixada e configuração versionada	diff ou saída estruturada; bloqueia arquivo alterado fora do padrão, sem reescrever código no gate
Laravel	verificações de boot/configuração, rotas, container e migrations em banco efêmero	artisan, caches recriados no job, .env.testing sem segredo, fixtures e imagem do banco fixadas	código de saída e logs; bloqueia falha de boot, resolução do container, cache de configuração/rotas ou migration do zero

Ferramentas equivalentes são aceitáveis somente quando preservam o mesmo contrato de entradas, saída analisável e condição de falha. Nunca execute correção automática no gate bloqueante.

Política de bloqueio e ratchet

Adote estes padrões iniciais, sujeitos a revisão após a fase observacional:

• código novo: zero erro de análise estática, zero teste falho, zero achado SAST ERROR, zero advisory novo controlado e zero violação nova de complexidade ou estilo;
• cobertura: pelo menos 80% das linhas alteradas e queda global máxima de 0,0 ponto percentual;
• complexidade: métodos novos ou alterados com complexidade ciclomática ≤ 10;
• dívida existente: baseline versionada por identificador estável, regra, símbolo/caminho e quantidade; qualquer aumento bloqueia;
• ratchet: a cada ciclo aprovado, remova da baseline os itens corrigidos e reduza em pelo menos 10% a contagem da categoria priorizada; arredonde a meta para cima e nunca abaixo de 1 item enquanto houver dívida;
• o CI pode validar ou reduzir a baseline, mas nunca adicionar novos problemas a ela. Toda mudança de patamar exige diff revisado, responsável e justificativa.

Se o analisador não oferecer identidade estável para comparar achados, mantenha-o observacional até existir normalização versionada. Tempo de runner compartilhado e sinal remoto flutuante não são fontes bloqueantes.

Verificações específicas de Laravel

Em projeto Laravel, avalie também:

• boot da aplicação nos ambientes de teste suportados e resolução de bindings críticos;
• criação dos caches de configuração e rotas em ambiente descartável, sem publicar os artefatos como configuração de produção;
• migrations do zero e rollback/forward quando o projeto declarar essa compatibilidade, sempre em banco efêmero exclusivo;
• testes de autorização para policies/gates e testes de arquitetura para limites entre camadas;
• filas, eventos e scheduler com fakes ou serviços efêmeros e expectativas explícitas;
• proibição de env() fora dos arquivos de configuração por regra estática versionada.

Não rode migrations, limpezas de cache, filas ou qualquer comando mutável em produção como parte da avaliação. Falha na criação do ambiente é falha de infraestrutura e deve ser distinguida de regressão do produto, sem converter ausência de teste em aprovação.

SCA reproduzível

Gere a SBOM CycloneDX de forma reproduzível a partir de composer.lock, com Composer e gerador fixados, e prepare fora do gate a vulnerability DB do Trivy como artefato imutável. Fixe a imagem ou o binário do Trivy por digest, configure TRIVY_DB_CACHE_DIR para o diretório extraído desse artefato e verifique seu conteúdo contra TRIVY_DB_ARTIFACT_SHA256 antes da análise. O gate bloqueante executa trivy sbom --cache-dir "$TRIVY_DB_CACHE_DIR" --offline-scan --skip-db-update --format json <sbom> sem consultar a rede. Variável, DB ou SBOM ausente e digest divergente são falha de infraestrutura: não aprovam o gate nem criam baseline.

O composer audit normal consulta advisories dos repositórios configurados. Por depender de estado de registry, ele é apenas informativo e nunca substitui o scanner offline bloqueante.

SonarQube opcional

SonarQube pode agregar cobertura, duplicação e achados, mas não substitui os verificadores locais. Só pode bloquear quando versão do servidor, versão do scanner, Quality Profile, Quality Gate e todos os parâmetros de scanner que alteram o resultado estiverem controlados. Caso contrário, publique o resultado apenas como informativo.

Aplicação por fases

Use o plano de ação compartilhado: inventarie e contrate os gates na Fase 0, calibre ferramentas e baseline na Fase 1, bloqueie regressões na Fase 2 e reduza a baseline por ratchet na Fase 3. Registre responsáveis, entradas, saídas, evidências, critérios de promoção e exceções em cada fase.

Entrega

Produza em português:

• inventário por categoria, ferramenta escolhida, versão/configuração e justificativa;
• tabela com comando proposto, entradas fixadas, saída, condição de bloqueio, tempo limite e dono;
• baseline e identificadores usados para comparar regressões;
• limiares adotados, passos do ratchet e critérios de promoção;
• tratamento separado para falha do produto e falha da infraestrutura;
• exceções com escopo, risco, aprovador, dono e validade;
• comandos ou diffs de instalação/pipeline apresentados apenas como proposta pendente de aprovação.

Limites de autorização

• Não instala nem atualiza dependências sem autorização explícita.
• Não altera pipeline, configurações do projeto ou baselines sem autorização explícita.
• Não executa mutações externas nem comandos contra produção.
• Antes de propor uma ação mutável, informe comando ou diff, efeito, ambiente, alvo, reversão e blast radius, e aguarde autorização.
• Não usa advisories remotos correntes, regras remotas flutuantes ou configuração SonarQube não controlada como fonte bloqueante.

Skills relacionadas

quality-gates · automation-engineer · devsecops · laravel-platform