docs: deprecated attribute support and compatibility matrix

[vinceAmstoutz]

Cover PHP 8.4 native #[\Deprecated] attribute detection (via the phpstan/phpstan-deprecation-rules extension, not PHPStan core) and add a compatibility table summarising which mechanisms emit a runtime deprecation and which are caught by PHPStan.

[vinceAmstoutz]

@ondrejmirtes I tested in a project and the #[\Deprecated] attribute works perfectly with phpstan/phpstan-deprecation-rules, but unfortunately it's not documented. I hope this PR will help.

[ondrejmirtes]

My first impression here is that this addition to the README is completely unnecessary.

The Deprecated attribute isn't really usable, it's only allowed above functions, methods and only most recently above traits.

[vinceAmstoutz]

The current README only mentions @deprecated annotations, so users have no way to know that PHP 8.4's #[\Deprecated] attribute is also supported by the extension.
And even if the attribute currently only works on functions, methods and traits, I don't see why that makes it not worth documenting.

When I presented this extension at a talk, a Symfony core team member directly asked me whether trigger_deprecation() was detected — which shows the confusion is real. Documenting that #[\Deprecated] works and trigger_deprecation() doesn't would save that question from being asked repeatedly.

WDYT?

[vinceAmstoutz]

ping @mtarld

[ondrejmirtes]

Fair, but I'd reword it. I don't entirely agree with the framing. the fact that trigger_deprecation is not detected is a direct consequence of https://phpstan.org/user-guide/troubleshooting-types#what-phpstan-doesn%E2%80%99t-do.

Detection of #[\Deprecated] is provided by this extension

That's kind of half-true. PHPStan itself reads this attribute and propagates it into various isDeprecated method implementations in its reflection API. So in theory you don't need to install phpstan-deprecation-rules and you can write your own rules or Restricted Usage Extensions that would ask reflection objects about isDeprecated().