On Sat, May 18, 2024 at 10:33 PM Barney Laurance
<bar...@barneylaurance.uk> wrote:
>
> 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
Thanks Barney,
Yeah, I think having an optional parameter to specify the namespace
the class/function is internal to would be immensely useful on
bigger/complex codebases. It'd be annoying to spell it out, but so
long as the attribute definition isn't marked as final, people would
be able to extend it with defaults:
#[Attribute]
class InternalToMyPackage extends Internal {
public function __construct() {
parent::__construct("\MyPackage\Deeply\Nested");
}
}
Robert Landers
Software Engineer
Utrecht NL
