Mark classes as final with an annotation

[greg0ire]

This can serve as a deprecation warning for people extending those classes.

[stof]

the convention used in Symfony when introducing those annotations is to write them as @final since 3.5.0. The DebugClassLoader of the ErrorHandler will not treat them differently, however our BC policy is different:

• @final since ... requires contributors to consider those classes as not final regarding the kind of changes allowed in them, as BC still needs to be supported until the next major version
• @final allows contributors to apply the same rules than for final classes

Our usages of @final are then mostly for cases where we still want to allow mocking that class (which is not possible for classes using the final keyword in PHP) and we convert the @final since ... annotations into either an actual final keyword or a @final annotation when preparing the next major version.

Note that this distinction between @final and @final since ... also exists for @internal and @internal since ... (even though @internal is then a lot more common, as there is no alternative using a PHP keyword)

[greg0ire]

OK… right now I don't think we have any @final since or @internal since inside Doctrine, so I'd stick with this for the sake of consistency. Whether we need to switch to something more complicated would need to be discussed separately. Anyway, in Doctrine, I don't think we consider @final reason enough to allow BC-breaking changes, otherwise adding @final should be considered a breaking change.

[stof]

In Symfony, we indeed don't allow adding @final or @internal in minor versions (on existing code from previous releases, of course), as that would remove them from the BC guarantees. they are always added first with the since <version> variant first