RFC
| Q |
A |
| Proposed Version(s) |
3.4.0 |
| BC Break? |
? |
Goal
Reduce the maintenance Overhead and runtime cost when deprecating elements.
Background
Since static analysis tools like psalm have become quite powerful to analyse the code before it gets executed.
Therefore we should drop every trigger_error of a E_USER_DEPRECATED where a deprecation is already caught by static analysis. We should only keep it, where static analysis tool cannot catch then (for example when config keys have changed).
Another extreme weakness of deprecation notices during runtime is, that they only occur when the code path is actually executed. This means deprecated elements may be still in use undiscovered for a long time until somebody hits the execution path by accident.
Runtime deprecations are also a horror to maintain and they usually require ugly work arounds to be added like in https://github.com/laminas/laminas-di/blob/3.4.x/phpcs.xml#L21
Considerations
Some library consumers may not use static analysis to validate their code which are then cut of from being noted about deprecations.
This is a sign of poor code quality and tech debt. We should encourage users to use static analysis instead relying on runtime behaviour.
Proposal(s)
- Drop all
trigger_error statements from the codebase where a deprecation annotation is used
- Add
@deprecated Doc-Block annotations (usually those are already present)
- Add
@see to point to an alternative or a migration guide for the user
- Encourage users to use static analysis tools like psalm or phpstan to detect usage of deprecated elements
Appendix
RFC
Goal
Reduce the maintenance Overhead and runtime cost when deprecating elements.
Background
Since static analysis tools like psalm have become quite powerful to analyse the code before it gets executed.
Therefore we should drop every
trigger_errorof aE_USER_DEPRECATEDwhere a deprecation is already caught by static analysis. We should only keep it, where static analysis tool cannot catch then (for example when config keys have changed).Another extreme weakness of deprecation notices during runtime is, that they only occur when the code path is actually executed. This means deprecated elements may be still in use undiscovered for a long time until somebody hits the execution path by accident.
Runtime deprecations are also a horror to maintain and they usually require ugly work arounds to be added like in https://github.com/laminas/laminas-di/blob/3.4.x/phpcs.xml#L21
Considerations
Some library consumers may not use static analysis to validate their code which are then cut of from being noted about deprecations.
This is a sign of poor code quality and tech debt. We should encourage users to use static analysis instead relying on runtime behaviour.
Proposal(s)
trigger_errorstatements from the codebase where a deprecation annotation is used@deprecatedDoc-Block annotations (usually those are already present)@seeto point to an alternative or a migration guide for the userAppendix