Posted on: April 09, 2026 01:03 AM
Posted by: Renato
Views: 66
Introducing Safe and Progressive Strict Type Adoption Rule
Apresentando a Regra de Adotação Segura e Progressiva de Tipos Estritos
A diretiva declare(strict_types=1) do PHP é uma ferramenta poderosa para prevenir bugs sutis. No entanto, a maioria dos projetos maduros e existentes não a utiliza de forma consistente, quando utiliza. Por quê? Porque adicioná-la automaticamente a todos os seus arquivos de uma vez fará sua aplicação explodir: espere milhares de erros. Isso deixa você com a tarefa de corrigir arquivos à mão, um por um, e dependendo de os membros da equipe lembrarem de adicioná-la em novos arquivos. Sem um processo seguro e automatizado, a adoção dificilmente se consolida.
Até agora. O novo SafeDeclareStrictTypesRector adiciona tipos estritos apenas a arquivos que já são seguros quanto ao tipo, tornando a adoção segura e progressiva finalmente possível e impedindo que o arquivo deixe de ser rigoroso no futuro.
Este é um post convidado por Caleb White, engenheiro e contribuidor de código aberto que colaborou com o Rector, PHPStan, framework Laravel e muitos outros projetos.
🧪 Nota: Este recurso ainda é experimental. Buscamos seu feedback em projetos reais. Algo quebrou quando não deveria? Informe-nos no GitHub.
O que é strict_types e por que você deve se importar?
Por padrão, o PHP coagirá valores escalares (bool, float, int, string, null) se houver uma incompatibilidade de tipo. Por exemplo, passar um bool para uma função que espera uma string o converterá silenciosamente em uma string:
PHP
<?php
function greet(string $name): string {
// faz algo
}
greet(true); // O PHP converte silenciosamente para "1" sem aviso ou erro
Esse comportamento "prestativo" pode mascarar bugs sérios; no exemplo acima, passar true para um método que espera um nome em string é provavelmente um erro de lógica que precisa ser corrigido, mas que poderia passar despercebido.
A tipagem estrita evita essa coerção silenciosa lançando um TypeError se os tipos não coincidirem. Para usar, coloque declare(strict_types=1); no topo do seu arquivo e o PHP forçará a correspondência exata de tipos:
PHP
<?php
declare(strict_types=1);
function greet(string $name): string {
// faz algo
}
greet(true); // TypeError: must be of type string, bool given
// Se você realmente precisar coagir valores, use casts para ser explícito e indicar intenção
greet((string) $someBool);
Claro, alguns podem argumentar contra a tipagem estrita; que não gostam de ter que ser rígidos o tempo todo e converter valores para o tipo correto (se você está tendo que converter o mesmo valor de um lado para o outro várias vezes, provavelmente está fazendo algo errado). Mas a realidade é que a tipagem estrita elimina completamente uma certa classe de bugs que, de outra forma, passariam despercebidos, e torna a coerção de tipos explícita, intencional e visível.
Aqui estão pontos importantes sobre o strict_types:
-
Ele é definido apenas para declarações de tipos escalares, o que significa que só é aplicado em:
-
Argumentos passados para funções, métodos e construtores.
-
Declarações de retorno (
return). -
Atribuições de propriedades.
-
-
A única exceção é que um valor
intpassará em uma declaração de tipofloat. -
Ele tem escopo de arquivo, o que significa que um arquivo com
strict_types=1ainda pode incluir (includeourequire) um arquivo que não seja estrito. -
Ele afeta apenas o código de chamada, portanto, uma função pode ser chamada de forma não estrita se a chamada for feita a partir de um arquivo não estrito, mesmo que a função esteja definida em um arquivo estrito.
Uma História de Terror da Vida Real
Na minha empresa, aprendemos essa lição da maneira mais difícil. Alguém da nossa equipe estava argumentando contra tipos estritos e comentou: "Nunca tive um bug que tipos estritos teriam evitado". Menos de um mês depois, o mesmo indivíduo refatorou um código e acidentalmente introduziu exatamente esse tipo de bug.
💥 Nossos números de fabricação ficaram subitamente errados.
Meu gerente e eu passamos dois dias inteiros rastreando o problema. Sem exceções. Sem erros ou avisos nos logs. O diff parecia inocente, revisei o código da última versão várias vezes antes de finalmente encontrar o culpado: um método aceitava um int em vez de um float. 😬 A refatoração coagiu silenciosamente um comprimento decimal para um número inteiro: por exemplo, 4,5 polegadas tornaram-se 4 polegadas. Isso cascateou por vários cálculos e, por fim, causou estragos em nosso sistema.
Se aquele único arquivo tivesse declare(strict_types=1), teríamos visto um TypeError imediatamente, em vez de queimar quatro dias de tempo de engenharia.
O PHP depreciou a coerção implícita de float para inteiro desde o PHP 8.1, pois resulta em perda de precisão. No entanto, esses avisos de depreciação ainda podem ser ignorados ou enviados para um arquivo de log que pode não ser visto até que seja tarde demais.
O Problema da Adoção
Se os tipos estritos são tão valiosos, por que nem todos os utilizam? A resposta é simples: ativar tipos estritos em uma base de código madura existente é doloroso.
Ferramentas existentes como o DeclareStrictTypesRector ou a regra declare_strict_types do PHP-CS-Fixer simplesmente adicionam a diretiva a cada arquivo indiscriminadamente: uma abordagem de tudo ou nada. Em uma base de código grande, isso pode introduzir milhares de TypeErrors instantaneamente.
Nenhuma equipe quer:
-
Corrigir toneladas de erros de tipo em centenas ou milhares de arquivos.
-
Correr o risco de introduzir bugs em produção alterando o comportamento.
-
Gastar semanas ou meses em uma "refatoração" que os stakeholders veem como entrega de valor zero para o negócio.
Assim, a adoção de tipos estritos estagna. As equipes sabem que deveriam usá-los, mas o caminho parece impossível. E mesmo com as melhores intenções, as equipes raramente são unificadas: alguns desenvolvedores defendem os tipos estritos, outros são indiferentes e todos ocasionalmente esquecem. Depender da disciplina manual de toda uma equipe simplesmente não escala.
Apresentando o SafeDeclareStrictTypesRector
O novo SafeDeclareStrictTypesRector adota uma abordagem fundamentalmente diferente: ele só adiciona declare(strict_types=1) a arquivos que já são seguros quanto ao tipo.
Em vez de adicionar cegamente a declaração em todos os lugares e quebrar as coisas, ele analisa cada arquivo para garantir que a ativação dos tipos estritos não mudará nenhum comportamento em tempo de execução. Se um arquivo lançasse um TypeError após a adição dos tipos estritos, o Rector o ignora completamente.
Como Funciona
Para cada arquivo, a regra examina todos os lugares onde a coerção de declaração de tipo poderia ocorrer:
-
Chamadas de função/método: todos os argumentos são compatíveis com os tipos dos parâmetros?
-
Declarações de retorno: todos os valores retornados são compatíveis com o tipo de retorno declarado?
-
Atribuições de propriedade: todos os valores atribuídos são compatíveis com as propriedades tipadas?
Para cada um destes, ele usa a inferência de tipos do PHPStan para verificar se os tipos de valores reais são estritamente compatíveis com os tipos declarados. Somente se cada ponto de coerção de tipo passar, o Rector adiciona a declaração.
PHP
<?php
// Este arquivo recebe strict_types porque já é seguro
function greet(string $name): string {
// ...
}
echo greet("Mundo"); // String passada para parâmetro string: seguro!
PHP
<?php
// Este arquivo é IGNORADO porque depende de coerção de tipo
function setQuantity(int $quantity): void {
// ...
}
setQuantity("3"); // String passada para parâmetro int: inseguro!
Conservador por Design
O verificador é intencionalmente conservador. Se não puder ter 100% de certeza de que um arquivo é seguro, ele o ignora:
-
Chamadas de métodos dinâmicos onde a reflexão não pode ser resolvida? Pula.
-
Desempacotamento de argumentos com
...$var? Pula. -
Tipos
mixedque poderiam ser qualquer coisa? Pula.
Isso significa que você pode não ter tipos estritos adicionados em todos os arquivos que poderiam tê-los, mas você nunca terminará com um arquivo quebrado.
Adoção Progressiva Tornada Possível
O verdadeiro poder do SafeDeclareStrictTypesRector é que ele permite a adoção progressiva:
-
Rode o Rector: arquivos seguros recebem
declare(strict_types=1)automaticamente. -
Esses arquivos agora estão protegidos contra futuros bugs de coerção de tipo.
-
O PHPStan capturará quaisquer novas violações, impedindo que esses arquivos voltem a ser não estritos.
-
Corrija os arquivos restantes incrementalmente conforme o tempo permitir.
-
Reexecute o Rector periodicamente para capturar arquivos que se tornaram seguros recentemente (preferencialmente em um pipeline de CI).
Essa regra também funciona em conjunto com outras regras do Rector. O Rector possui regras que adicionam tipos de parâmetros, tipos de retorno e até fazem o cast de argumentos para o tipo correto. À medida que essas regras são executadas, arquivos que antes eram inseguros tornam-se seguros. Uma vez que um arquivo é totalmente seguro quanto ao tipo, o SafeDeclareStrictTypesRector adicionará automaticamente a declaração.
Isso cria um ciclo virtuoso: o Rector adiciona tipos e casts, os arquivos tornam-se "strict-safe" e o PHPStan evita regressões. Sua base de código torna-se gradualmente mais segura ao longo do tempo com o mínimo de esforço manual.
Em nossa aplicação corporativa, a primeira execução adicionou declare(strict_types=1) a mais de 1.500 arquivos: completamente automático e com risco zero de quebra. São 1.500 arquivos agora protegidos contra a exata classe de bug que nos custou dois dias de depuração. 💪
Experimente Você Mesmo
Adicione a regra à sua configuração do Rector (rector.php):
PHP
use Rector\Config\RectorConfig;
use Rector\TypeDeclaration\Rector\StmtsAwareInterface\SafeDeclareStrictTypesRector;
return RectorConfig::configure()
->withRules([
SafeDeclareStrictTypesRector::class,
]);
Em seguida, execute o Rector: veja como os arquivos seguros recebem automaticamente a diretiva, enquanto os arquivos inseguros permanecem intocados. Sem quebras. Sem riscos. Apenas melhoria automática.
Conclusão
Tipos estritos não deveriam ser uma escolha de tudo ou nada. Com o SafeDeclareStrictTypesRector, você pode adotar o declare(strict_types=1) de forma progressiva, automática e segura.
Cada arquivo que recebe tipos estritos é mais um arquivo protegido contra bugs silenciosos de coerção de tipo. Esses bugs podem custar dois dias de depuração como custaram para nós, ou podem custar muito mais.
Comece a proteger sua base de código hoje. 🛡️
Donate to Site
Renato
Developer