How is @internal inheritance supposed to work

[TRowbotham]

Take the following example:

https://psalm.dev/r/724600be11

The abstract BasicToken class is labeled as @internal to indicate that other packages should not extend the class. The Identifier and Delimiter classes extend BasicToken and are intended to be consumed by other packages. When the token is typed with the Token interface, there is no warning reported, however, after checking the type of the token using instanceof, psalm reports

ERROR: InternalMethod - 31:24 - The method FirstParty\BasicToken::getValue is internal to FirstParty but called from

Can @internal not be used in this way?

Even though instanceof validates the token type as Identifier or Delimiter, those classes still implement the Token interface and thus satisfy the contract, so the getValue method should still be non-internal per the interface, no?

[weirdan]

That's a good question, however I think having the interface in there just obscures things. To put the question more squarely, should a method, inherited from internal class by a non-internal class be considered internal? (https://psalm.dev/r/963f6d0a52)

[weirdan]

Does either of them actually undestand @internal?

[TRowbotham]

Looks like Phan does

https://phan.github.io/demo/?code=%3C%3Fphp+declare%28strict_types+%3D+1%29%3B%0A%0Anamespace+FirstParty+%7B%0A++++%2F**+%40internal+*%2F%0A++++class+BasicToken+%7B++++++++%0A++++++++public+function+getValue%28%29%3A+string+%7B%0A++++++++++++return+%27a%27%3B+++%0A++++++++%7D%0A++++%7D%0A%0A++++class+Identifier+extends+BasicToken+%7B%7D%0A%7D%0A%0Anamespace+ThirdParty+%7B%0A%09new+%5CFirstParty%5CBasicToken%28%29%3B%0A++++new+%5CFirstParty%5CIdentifier%28%29%3B%0A%7D

PHPStan, not so much 😢
https://phpstan.org/r/2589db84-112e-4836-ab4a-55eb368e54cf

phpstan/phpstan#1178 is the feature request for @internal in PHPStan it seems

[TRowbotham]

Phan's documentation on @internal for reference https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#internal

[TRowbotham]

Is marking the base class' constructor @internal, as opposed to the whole class, more appropriate to convey that the class should not be extended or created by other packages, while still allowing use of inherited methods by non-internal derived classes?

Perhaps @TysonAndre has an opinion or can provide more info on how Phan interprets @internal on classes and its affect on derived classes.

[TysonAndre]

Phan isn't treating extending a class marked with /** @internal */ differently from using/accessing that class. A @final phpdoc annotation might be more appropriate for classes that shouldn't be extended.

Any element marked as @internal and accessed outside of its exact namespace (disallowing both child and parent namespaces) will result in Phan emitting an issue.

---

The abstract BasicToken class is labeled as @internal to indicate that other packages should not extend the class.

EDIT: never mind, misread that, you mean classes from other packages (namespaces)

It looks like psalm supports (a non-standard phpdoc tag) /** @final */ https://github.com/vimeo/psalm/blob/master/docs/running_psalm/issues/InvalidExtendClass.md - I don't think I've gotten around to supporting @final. Phan currently doesn't since it was non standard.

https://pear.php.net/package/PhpDocumentor/docs/latest/phpDocumentor/tutorial_tags.final.pkg.html - most uses of final for api documentation were removed when php 5 added a keyword for final, though it may make sense to still use that for purposes of static analysis (e.g. for a library waiting until a major release to make a method final, and accounting for php deliberately forbidding abstract final class, etc)

Phan currently expects exact matches on all namespace parts for the @internal annotation, though there's a ticket in the backlog to look into letting A\B access A or A\B\C (and vice versa), but not \ or A\Other