Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123359
Message-ID: <35f6f3ce-fc7d-4911-8a1a-a06f8e17fe71@barneylaurance.uk>
Date: Sat, 18 May 2024 20:15:06 +0100
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] [Discussion] "Internal" attribute and warning
To: internals@lists.php.net
References: <CAPzBOBMpOztgNQx35ZnP4c5ZHV-Ax1ETH0=YMzVT9Hq9cdyyDQ@mail.gmail.com>
Content-Language: en-US
In-Reply-To: <CAPzBOBMpOztgNQx35ZnP4c5ZHV-Ax1ETH0=YMzVT9Hq9cdyyDQ@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
From: barney@barneylaurance.uk (Barney Laurance)

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