O que há de novo no PHPStan 1.0?

O PHPStan ganhou um lançamento importante no início de novembro de 2021 com novos recursos, regras extras e muitas otimizações de desempenho. Isso significa que o principal analisador estático de PHP agora é considerado estável e vem com uma promessa de compatibilidade com versões anteriores para atualizações futuras.

Como é um grande obstáculo, o PHPStan 1.0 também traz algumas mudanças importantes que podem afetar as varreduras existentes. Isso inclui regras extras e alguns parâmetros de configuração substituídos ou removidos.

O novo nível 9

O PHPStan verifica o código-fonte do PHP para encontrar problemas em potencial sem realmente executar o código. Juntamente com os testes de unidade e de ponta a ponta, isso dá visibilidade da qualidade do seu código, identificando problemas antes que os usuários os encontrem.

Os níveis de PHPStan são usados ​​para configurar a rigidez do analisador. A série de lançamento v0.x oferecia oito níveis, com 0 o mais relaxado e 8 o mais rígido. Embora seja preferível usar o nível mais estrito possível para a melhor cobertura, níveis menos rigorosos podem ajudá-lo a apresentar o PHPStan a uma base de código imperfeita.

O PHPStan 1.0 adiciona o nível 9 como uma nova opção. Inclui todas as regras do nível 8 e inferior, bem como uma verificação extra: comparações estritas de tipo misto.

Publicidade

O tipo misto chegou ao PHP 8.0 como uma forma de digitar explicitamente “ any ” valor. Como misto é essencialmente equivalente a um valor não digitado, não é seguro fazer suposições sobre a aparência de um valor de tipo misto.

O nono nível do

PHPStan &’ o aplicará estritamente, relatando um erro se você tentar usar ativamente um valor misto em seu código. Acessar uma propriedade ou chamar um método não é permitido, pois você não pode saber se eles existirão. Você só pode passar valores por meio de outras dicas de tipo misto quando esta regra está ativa.

Para aceitar o novo comportamento, você precisará alterar o nível: 8 para o nível: 9 em seu arquivo de configuração phpstan. neon. PHPStan também suporta level: max como um apelido para o nível mais alto. Se você já estiver usando o max, você obterá automaticamente o nível 9 ao atualizar para o PHPStan 1.0.

Melhor conscientização em blocos de tentativa e pega-final

PHPStan agora tem melhor inferência de tipo e reconhecimento de variável para blocos try-catch-finally. Ele usará a tag @throws docblock para verificar os tipos de exceção lançados por cada função em sua base de código. Esse entendimento é usado para informar verificações de disponibilidade de variáveis ​​dentro de blocos try-catch.

Aqui está um exemplo que demonstra por que isso é importante:

/ ** * @throws DemoException * / function first & # 40; & # 41; & # 123; lançar DemoException & # 40; & # 41 ;; & # 125;   / ** * @throws OtherException * / function second & # 40; & # 41; & # 123; throw OtherException & # 40; & # 41 ;; & # 125;   tente & # 123; $ primeiro = primeiro & # 40; & # 41 ;; $ segundo = segundo & # 40; & # 41 ;; & # 125; capturar & # 40; DemoException $ ex & # 41; & # 123; error_log & # 40; $ segundo & # 41 ;; & # 125; capturar & # 40; \ Exception $ ex & # 41; & # 123; error_log & # 40; " Exceção geral " & # 41 ;; & # 125;

O primeiro blog pega acessa $ segundo, mas ele não existirá quando DemoException for capturado. PHPStan v1.0 usa a instrução @throws para perceber isso, para que você seja informado quando seus blocos catch referenciarem variáveis ​​possivelmente indefinidas. Funções sem anotações @throws geralmente se comportam da mesma maneira que antes.

Como resultado dessa alteração, o parâmetro opcional polluteCatchScopeWithTryAssignments foi removido. Isso costumava permitir que você acesse as variáveis ​​definidas em um bloco try dentro da captura a seguir; não é mais necessário, pois o PHPStan agora pode determinar quais variáveis ​​estão disponíveis.

Detecção de código não utilizado

O PHPStan ficou melhor em encontrar e relatar algumas formas de código não utilizado em seu projeto. Ele destacará as propriedades, métodos e constantes da classe privada que nunca são chamados ou acessados.

Publicidade

A presença deles é quase sempre não intencional. Se você quiser manter o código morto por mais tempo, pode tentar comentá-lo ou adicionar o comentário @ phpstan-ignore-next-line para ignorar a verificação.

Melhorias nos valores lembrados

v1.0 melhora a consistência da memória do PHPStan para os valores de retorno da função. É mais adequado para compreender quando uma função é chamada uma segunda vez, oferecendo uma melhor antecipação de valores de retorno idênticos.

Isso leva a uma detecção aprimorada de código morto quando uma condição é repetida várias vezes. O PHPStan avisará quando um bloco se tornar redundante porque a execução foi encerrada por um branch anterior com a mesma condição:

if & # 40; $ demo- > isActive & # 40; & # 41; & # 41; & # 123; return; & # 125;   if & # 40; $ demo- > isActive & # 40; & # 41; & # 41; & # 123; recordDemoActivity & # 40; & # 41 ;; & # 125;

O segundo bloco nunca será executado, pois o primeiro sempre termina. No entanto, existe uma suposição em jogo: isActive () deve sempre retornar o mesmo valor durante o tempo de vida de $ demo. Em termos mais concretos, isActive () precisa ser uma função pura em que entradas repetidas sempre produzem saídas idênticas.

O PHPStan assume que as funções são puras por padrão. Nos casos em que não forem, você pode adicionar a anotação @ phpstan-impure em um bloco de documentos acima da definição da função. Isso desativará a memória do valor de retorno para essa função. Você precisaria usar isso no exemplo acima se isActive () pudesse retornar um valor diferente para cada chamada, o que significa que a primeira verificação poderia ser igual a falsa e permitir que o segundo branch fosse executado.

/ ** @ phpstan-impure * / publicfunction isActive & # 40; & # 41 ;: bool & # 123; return & # 40; date & # 40; " Y " & # 41; === " 2021 " & # 41 ;; & # 125;

Outras melhorias de regra

Várias novas regras foram adicionadas aos níveis existentes de 1 a 6. Estas incluem verificações para substituir constantes e propriedades, tentar estender uma classe final e detecção de sempre verdadeiro e condições de loop while-false.

Publicidade

Tipos agora são verificados para dicas de tipo ausentes recursivamente. Isso significa que as definições do PHPDoc como array < array > não serão aceitos porque não têm uma definição de tipo interna. Você também precisará digitar a dica dos valores esperados dos elementos da matriz de segundo nível, como array < array < string > & gt ;.

Além de verificar o conteúdo de origem, o PHPStan 1.0 também analisa a validade geral dos arquivos . php. O nível 0 obtém uma verificação de espaços em branco e BOM de arquivo à esquerda e à direita, como caracteres mal colocados antes ou depois de <? Php ...? > O par de tags pode causar uma saída inesperada no tempo de execução.

Desempenho e estabilidade

O desempenho foi aprimorado em várias áreas, otimizando operações específicas e resolvendo alguns vazamentos de memória. Isso deve contribuir para varreduras mais rápidas e confiáveis ​​de bases de código maiores.

Como a v1.0 é considerada uma versão estável formal, ela vem com a garantia de que as versões menores futuras (1.1, 1.2, 1.3, etc.) serão compatíveis com versões anteriores. Embora ir de v0.x para v1.0 possa exigir alguns ajustes de configuração, você terá um caminho de migração mais fácil no futuro.

Os desenvolvedores de extensões PHPStan e conjuntos de regras personalizadas também se beneficiam de uma base de código mais estável que é menos provável de ser alterada. A documentação do desenvolvedor também foi expandida, incluindo uma cobertura mais acessível da criação de regras personalizadas. Deve ser mais fácil começar ao implementar as próprias regras de sua equipe em sua análise de PHPStan.

Publicidade

Embora isso seja um bom presságio para suporte futuro, tanto os usuários quanto os desenvolvedores de extensão enfrentam mudanças significativas na mudança para a v1.0. Vários parâmetros de configuração de varredura foram renomeados ou alterados, com o bootstrap se tornando bootstrapFiles e excludes_analyse substituído por excludePaths.

Internamente, a API de extensões foi amplamente revisada, portanto, muitas classes e métodos foram alterados ou removidos. A lista completa de alterações incompatíveis com versões anteriores está disponível no changelog v1.0.

Resumo

O PHPStan v1.0 amadurece o projeto otimizando o desempenho, adicionando novas regras e abordando algumas irregularidades de detecção. A evolução do PHPStan nos últimos anos contribuiu para a mudança mais ampla da comunidade PHP para abraçar os conceitos de linguagem digitada. A adição de recursos como propriedades digitadas e tipos de união produziu uma linguagem que é capaz de suportar inspeção externa avançada, bem como introspecção interna detalhada por meio de reflexão.

A promoção para uma versão estável semver deve ajudar a encorajar a adoção do PHPStan em toda a comunidade. Migrar para a nova versão deve ser bastante fácil para projetos modernos que já estão usando um nível de regra estrito do PHPStan.

Você pode atualizar para o PHPStan v1.0 hoje, executando composer require phpstan / phpstan em seus projetos. É aconselhável ler primeiro as notas da versão para identificar as alterações importantes que você precisa resolver. A presença de regras extras em cada nível existente pode fazer com que sua base de código comece a falhar nos testes, mesmo que seja aprovada com PHPStan v0.x. Você pode desativar as novas regras temporariamente adicionando-as à sua linha de base para que sejam excluídas dos resultados da verificação.