make classes final for 2.0

[dbu]

Q	A
Bug fix?	no
New feature?	no
BC breaks?	no
Deprecations?	yes
Related tickets	fix #317
Documentation	-
License	MIT

What's in this PR?

Declaring final all classes that are marked as @final for the new major version

[xabbuh]

Have all the internal classes been internal since 1.0? Otherwise making them final would technically be a BC break too.

[dbu]

good point. the classes have been added in #128 and have been @internal since the beginning.

[ostrolucky]

What's the advantage of this? In userspace I might want to extend these classes despite that they are not covered by semver.

[dbu]

the problem with non-final classes is that people will start extending them, and then complain when things break because we change their signature. extending a class can break in so many ways when the base class does not consider BC (method name clashes, changing a method from protected to public in the base class, ...)

[ostrolucky]

You say that, but it doesn't really happen. Not for internal classes. And when it does, it's easy to quickly close such requests. It's much more likely you will receive requests to remove those finals. Look how many of such requests are in moneyphp repository.

[dbu]

i do remember a few cases where people complained when we broke stuff, and i remember tons of cases where we had huge discussions about breaking BC with changes in such classes.

looking at what i want to make final, its really things about the layout in the debug toolbar. i don't expect people to need to customize that. if they want to provide visual tweaks (like you did in #355) that's awesome and should go into this repo rather than be project specific.

[ostrolucky]

i do remember a few cases where people complained when we broke stuff

In classes marked @internal?

[dbu]

that i don't remember. but what is your goal? would you only soft-mark the classes as internal, and allow people to break the rules and when things break for them, we can tell them "told you so"?

@php-http/owners what is your take on making classes final? i prefer it, but don't have a very strong opinion...

[ostrolucky]

Yes, @internal, or @final. That is defacto symfony's approach, even though recently they started to break this symfony/symfony#25788

Yes, I don't expect need of extending these classes ever, but software engineering runs into unforeseen change of requirements all the time.

[dbu]

@xabbuh what is the current policy of symfony regarding final? i like the approach of making everything that is not meant to be extended final (which is almost everything in this bundle). there are interfaces that can be implemented if somebody needs to customize something. they can then just implement their own, or write decorators around the final classes.

i am adding the annotations in #467 for the 1.x branch, as we agree on doing that.

[xabbuh]

@dbu We don't have any strict rules but I guess nowadays new code often follows what Marco has written in https://ocramius.github.io/blog/when-to-declare-classes-final/.

[ostrolucky]

I also don't have anything against declaring classes final if they implement interface, like marco's post declares. This PR at the moment follows that

[dbu]

i changed this MR to point to the 2.x branch and cleaned it up. does one of you want to review and merge?