RFC: @final

[theofidry]

It would be nice if the @final was included as well. Whilst it's preferable to actually mark the class as final instead of that tag, it is not always doable:

• Code for which final would be a BC break, it could help to show the intent of making it final in future versions (see https://github.com/symfony/symfony/pull/20493 for example)
• Case where there is only one class and making it final would require an interface. While doable you may be in a situation where there is not much benefit to do so yet. In that case, @final would convey the intent that if you were to need to extend that class, you should refactor and introduce an interface to implement the interface instead of extending the base class (which you can now mark as final)
• With lazy classes (notably with ProxyManager), final classes are not supported. There is a discussion to maybe support it in a specific scenario (when the class implements only 1 interface or extend 1 class without implementing any interface), it won't cover all cases. In which case you either give up on using the proxy manager and keep final, or you remove final in favour of @final to use the proxy manager

[stof]

another use case: mocking the class. Most mocking libraries rely on inheritance as mocking final classes otherwise requires complex things:

• support at the engine level to bypass the final keyword (available in HHVM's Hack, but there is no such feature in PHP)
• replacing the whole class definition by the mock, but this implies that the real class definition is never loaded in the PHP process, making process isolation of tests a hard requirement (and forcing to not mix the usage of the class and of its mock in the same test). This is what atoum is doing, but it is not possible for a generic mocking library.

[unkind]

Case where there is only one class and making it final would require an interface

For clarity, lack of interface doesn't mean that the class cannot be final. This argument looks the same as inability to proxy/mock the class.

[Fleshgrinder]

None of these arguments are valid. You are trying to work around a platform, namely PHP, limitation. A class is final if it is not meant to be extended, period. All other use cases should be added to PHP itself and not to documentation.

[theofidry]

@Fleshgrinder following your logic, we would completely remove remove all phpdoc block, since it's a limitation of dynamic languages.

[Fleshgrinder]

No, that is a deliberate design choice of the language and the annotations are meant to extend upon this. The disability to mock final classes is not such a choice, it is an overlooked feature.

[theofidry]

I fail to see the problem. Even if the feature is integrated in the next minor release, it won't be usable for all the existing code, whereas supporting it via an annotation is easy.

[Fleshgrinder]

The problem is that this standard recommendation (which will possibly never come) is the basis for all PHPDoc parsers, hence, it should be a minimal set of functionality that commonly adds value to all of them. It is meant to establish a baseline. This feature request should go to your favorite IDE vendor or documentation tool and not here.

[theofidry]

The problem is that this standard recommendation (which will possibly never come) is the basis for all PHPDoc parsers

Yes, this is precisely why I'm making this issue here and not in phpdoc. Unless it's here, any php parser or IDE will be reluctant to integrate that feature which has legitimate use cases. As I said even if the requested feature land in PHP now, it will take years before the @final tag would be completely useless. So IMO, it's reasonable to officialise this one (as it already exists in phpdocumentor) which could be valuable for a couple of years at least.

But we may simply have different views on it, that's fine, let's let the other speak as well and provide a bit more input :)

[ashnazg]

I've seen this tag occasionally mentioned in the wild, but I've never been keen on it, since, historically speaking, whenever a tag exists because the language didn't have the syntax, and then the language adds the syntax, then the code counts and the tags are redundant/ignored (e.g. @access).

Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions.

[jaapio]

I understand why this is requested. But I don't think it should be part of the current psr. I think it could be part of a future psr. But I think we should focus first to standardis the widely used tags before introducing new tags. Especially because this new tag only will make sense when all tools have support for it. I have seen more usecases for @internal so could that be a replacement of this tag?

[neuro159]

+1 to @jaapio )

[ashnazg]

Looks like a no-go.