On 18/05/2024 15:00, Robert Landers wrote:
Hello internals,
I've been thinking about having an "internal" attribute that will emit
a warning if called from outside it's left-most namespace.
Hello Robert,
It's worth looking at the prior art on this - the @internal annotation
from PHPDoc, and its implementation PSalm, PhpStorm, and also the
@psalm-internal annotation, which I added to Psalm. @internal requires
the leftmost namespace segment to match between declaration and
reference, while @psalm-internal is used with a specification of the
namespace to which the annotated element is internal, which may be a
deeply nested namespace.
I had the idea to create @psalm-internal originally because the Drupal
project was recommending plugin and site developers create independent
work within the Drupal namespace, while having certain elements
documented as internal in the Drupal\Core namespace, with breaking
changes in point releases.
Another prominent left-most namespace with code developed by people who
might like a tool to help them avoid depending on each other's internals
is League, as in https://thephpleague.com/
I think if something like this is added to the language it would be a
shame not to give it something like the flexibility of @psalm-internal,
instead of only dealing with the left-most namespace part.
See
https://docs.phpdoc.org/latest/guide/references/phpdoc/tags/internal.html
https://psalm.dev/docs/annotating_code/supported_annotations/
I'm not currently a PHPStan user, but from what I read PHPStan doesn't
have this feature but has started considering it:
https://github.com/phpstan/phpstan/issues/1178
