Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123361
Precedence: bulk
MIME-Version: 1.0
References: <CAPzBOBMpOztgNQx35ZnP4c5ZHV-Ax1ETH0=YMzVT9Hq9cdyyDQ@mail.gmail.com>
 <35f6f3ce-fc7d-4911-8a1a-a06f8e17fe71@barneylaurance.uk>
In-Reply-To: <35f6f3ce-fc7d-4911-8a1a-a06f8e17fe71@barneylaurance.uk>
Date: Sun, 19 May 2024 09:45:26 +0200
Message-ID: <CAPzBOBO=CCrAD0XsPjVVawTrCNmXOUax=YwiMM73eYDiuzfxZg@mail.gmail.com>
Subject: Re: [PHP-DEV] [Discussion] "Internal" attribute and warning
To: Barney Laurance <barney@barneylaurance.uk>
Cc: internals@lists.php.net
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
From: landers.robert@gmail.com (Robert Landers)

On Sat, May 18, 2024 at 10:33=E2=80=AFPM Barney Laurance
<barney@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