Backward Compatibility Promise
There are multiple aspects to backward compatibility in case of PHPStan. This article talks about classes, interfaces, and methods that can be safely used by extension developers without the risk of breaking in minor versions.
To read about backward compatibility from the point of view of end users, head here.
PHPStan makes use of a lot of internal code with implementation details that are not meant to be used by third parties writing PHPStan extensions. But the internal code is available to extensions anyway because of how PHP works. To be able to develop PHPStan further, we need some wiggle room to be able to make changes to the internals.
That’s why not all the PHPStan’s internal code is supposed to be a surface area for extension developers. When the extensions are analysed by PHPStan itself, it checks whether only the intended code is used by the extension. Reported risky usages point out that such API can change in the next minor version and that it’s not covered by the backward compatibility promise.
Here’s the human-readable summary of these rules. If you want more code to be covered by this backward compatibility promise, please open a discussion.
You can browse all the backward compatibility-covered code in API Reference.
Classes #
- Non-final classes with
@apiin their PHPDoc can be extended. - Objects of classes with
@apiin their PHPDoc cannot be created vianewunless there’s also@apiabove the public constructor. This encourages using dependency injection in case the class is registered as a service in the dependency injection container. - All public methods from classes with
@apiin their PHPDoc can be called.
Interfaces #
- Interfaces with
@apiin their PHPDoc can be implemented and extended, except forPHPStan\Type\Type. Instead of implementing this interface, extend an existing implementation likePHPStan\Type\ObjectTypeand similar. - All methods from interfaces with
@apiin their PHPDoc can be called.
Methods #
- Public methods with
@apiin their PHPDoc (or in the PHPDoc of the declaring class) can be called.
Traits #
- No internal PHPStan traits can be used.