Como analisar estaticamente projetos PHP com PHPStan

PHPStan é um sistema de análise estática para projetos PHP. Ele encontra bugs em sua base de código, inspecionando os arquivos de origem. Você não precisa executar seu código ou escrever testes manualmente para descobrir problemas!

O termo “ análise estática ” é definido como código de depuração sem realmente executá-lo. É mais frequentemente usado com linguagens interpretadas, como PHP, pois os problemas que encontra tendem a surgir no estágio de compilação em linguagens compiladas.

A análise estática tende a fornecer os melhores resultados quando executada em uma base de código bem estruturada e fortemente tipada. A documentação do PHPStan informa que o “ código moderno orientado a objetos ” é o que mais se beneficia, pois esses projetos fornecem ao PHPStan mais informações com as quais trabalhar.

Adicionando PHPStan ao seu projeto

Para executar o PHPStan, você &’ precisará ter o PHP 7.1 ou mais recente. Este requisito se aplica apenas à versão do PHP usada para executar o próprio PHPStan. A ferramenta é capaz de analisar arquivos de origem visando versões mais antigas do PHP.

É recomendado que você use o Composer para adicionar PHPStan como uma dependência:

 compositor requer --dev phpstan / phpstan 

O binário PHPStan será adicionado ao seu projeto em vendor / bin / phpstan. Agora você pode usá-lo para analisar sua base de código pela primeira vez:

 vendor / bin / phpstan analisar src 

O comando mostrado acima executará os testes do PHPStan &’ s em todos os arquivos de origem em seu diretório src. Dependendo do tamanho da sua base de código, isso pode levar alguns minutos para ser concluído.

Você verá uma mensagem verde “ [OK] Sem erros ” mensagem se todos os testes passarem. Caso contrário, a lista de erros encontrados será exibida. Siga as orientações mostradas para resolver cada erro antes de executar novamente o PHPStan.

Tipos e níveis de erro

PHPStan inclui uma infinidade de verificações cobrindo uma ampla variedade de possíveis problemas de base de código. Alguns dos mais comuns que você encontrará incluem o seguinte:

• Digite os problemas do sistema – Atribuir um valor inválido a uma propriedade digitada ou passar parâmetros digitados incorretamente a um método. Isso também inclui questões contratuais, como uma classe implementando incorretamente uma interface.
• Invocações de função – Passar muitos ou poucos parâmetros ao chamar uma função ou método (por exemplo, 3 em vez de 4).
• Classes, métodos e funções desconhecidos – Tentando usar algo que não existe na base de código.
• Acesso a variáveis ​​indefinidas / possivelmente indefinidas – Tentar usar uma variável que não está definida em um determinado escopo, ou aquela que nem sempre tem um valor, mas é usada em um contexto onde um é assumido.
• Verificação de código morto – Sinalização de código inútil, como comparações booleanas que sempre resolverão para o mesmo valor e ramificações de código que nunca serão executadas (por exemplo, código após uma instrução de retorno dentro de funções).

As regras são classificadas em 9 “ níveis ” diferentes, rotulados de 0 a 8. O nível especial máximo atua como um apelido para o nível mais alto possível. Com o tempo, o PHPStan pode adicionar níveis numéricos adicionais, portanto, usar o máximo garante que você sempre obtenha as verificações mais rigorosas possíveis.

Por padrão, o PHPStan executa o nível 0. Isso inclui apenas o mais fundamental dos testes. É uma boa ideia fazer com que sua base de código passe cada nível individualmente antes de avançar para o próximo. Projetos maduros provavelmente encontrarão outro conjunto de problemas a cada novo nível.

Para alterar o nível que o PHPStan usa, você pode passar o parâmetro da linha de comando --level:

vendor / bin / phpstan analise src - nível 8

Além das verificações integradas, as extensões PHPStan estão disponíveis para adicionar ainda mais funcionalidades. Você também pode escrever suas próprias regras do zero. Isso é útil quando você está descontinuando uma funcionalidade que os desenvolvedores não devem mais usar em nenhum código novo. Abordaremos a criação de regras personalizadas em um artigo futuro.

Configurando PHPStan

Além da experimentação inicial, usar a interface de linha de comando do PHPStan &’ pode rapidamente se tornar cansativo. É melhor adicionar um arquivo de configuração ao seu projeto, que pode então ser comprometido com o controle de origem para todos os seus desenvolvedores usarem.

PHPStan usa o formato de arquivo de configuração Neon, que tem uma sintaxe muito semelhante ao YAML. Crie um arquivo phpstan. neon no diretório raiz do seu projeto. Este arquivo é carregado automaticamente sempre que o PHPStan é iniciado, então agora você pode executar o comando de análise sem mais argumentos:

 vendor / bin / phpstan analisar 

Para substituir o arquivo de configuração que é usado, passe o sinalizador --configuration:

 vendor / bin / phpstan analyze --configuration /phpstan-config. neon

Agora você precisa preencher seu arquivo phpstan. neon com algum conteúdo. Um bom ponto de partida pode ser assim:

Parâmetros

: nível: 0 caminhos: - src

Este arquivo de configuração básica deve fornecer a mesma saída que a invocação da linha de comando mostrada anteriormente. Você pode adicionar diretórios adicionais para verificar como novas linhas na seção de caminhos. Para excluir arquivos e diretórios, adicione-os a uma folha excludes_analyse na mesma seção de parâmetros.

Ignorando erros

Ocasionalmente, o PHPStan pode revelar um problema que é inevitável. Se houver um problema que você não possa resolver imediatamente, ignore-o explicitamente para permitir que os testes passem.

Isso é particularmente importante quando você deseja passar para outro nível de verificação ou está usando o PHPStan em um ambiente de CI em que uma execução com falha interromperá a implantação da compilação. Mesmo assim, não tome esse curso de ação levianamente – você só deve escolher ignorar um erro relatado se tiver certeza de que será seguro fazê-lo.

Depois de tomar a decisão, adicione uma nova seção ignoreErrors dentro dos parâmetros do seu arquivo de configuração. Você deve definir a mensagem para corresponder, como uma regex, e os caminhos para aplicar a exclusão a:

Parâmetros

: nível: 0 caminhos: - src ignoreErrors: - mensagem: '/ String do tipo de retorno do método ExampleClass :: example () não é covariante (. *).' caminho: src / ExampleClass. php

Você pode opcionalmente especificar caminhos como uma matriz de caminhos, substituindo a única chave de caminho mostrada acima.

Regras opcionais

A rigidez de

PHPStan &’ s pode ser ajustada por uma série de variáveis ​​de configuração. Isso permite que você ajuste as verificações feitas fora do sistema de níveis descrito acima. Alguns deles são potencialmente controversos ou improváveis ​​de se alinharem a todos os guias de estilo privados, portanto, eles estão desativados por padrão.

Algumas configurações que podem valer a pena ativar incluem:

• checkAlwaysTrueInstanceof – Sinalizadores de uso de instanceof que sempre serão avaliados como verdadeiros.
• checkAlwaysTrueStrictComparison – Sinalizadores quando uma expressão usando === ou! == sempre será avaliada como verdadeira.
• checkFunctionNameCase – Garante que a capitalização dos nomes de função corresponda à sua definição quando chamada em toda a base de código.
• polluteScopeWithLoopInitialAssignments – Quando definido como falso (é verdadeiro por padrão), as variáveis ​​declaradas nas instruções de loop iniciais (por exemplo, $ i em $ para ($ i = 1; $ i < 10; $ i ++)) são impedidas de serem acessadas externamente o bloco de código do loop, evitando possível poluição do escopo pai.
• reportStaticMethodSignatures – Impõe a verificação completa de tipo para parâmetros e tipos de retorno em métodos estáticos quando substituídos por uma classe filha.

Detalhes completos sobre essas configurações opcionais – e muitos mais – pode ser encontrado na referência de configuração do PHPStan ’.

Conclusão

Esse é o fim da nossa introdução ao PHPStan. Isso ajuda você a ter confiança em sua base de código e destaca possíveis problemas antes que se tornem um problema na produção.

O PHPStan é tão rápido de configurar que não há realmente nenhuma razão para não usá-lo, especialmente ao trabalhar com uma base de código moderna fortemente tipada. No entanto, não se iluda pensando que ele pode substituir o teste manual. O PHPStan pode se orgulhar de uma grande variedade de verificações, mas não consegue identificar problemas lógicos e não entende as regras de negócios do seu projeto. É apenas mais um recurso em sua caixa de ferramentas ao avaliar a integridade de uma base de código, servindo junto com companheiros confiáveis, como testes de unidade e testes de funcionalidade ponta a ponta.