Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:101306
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.128.177 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <CADyq6sLwcqaVYYC_bUrrHR4-19v5JwNT4pneAGv8aTM2_oBHpw@mail.gmail.com>
References: <CAH0Uv3ErvVo5qPotvrHby7AKrzUQix_YuDU5dbQWos8bvCASqw@mail.gmail.com>
 <CANUQDChCkt0CzYHeJoRN+d7_wWBe82-J5MJEgXWFj9qTBMz4Zg@mail.gmail.com> <CADyq6sLwcqaVYYC_bUrrHR4-19v5JwNT4pneAGv8aTM2_oBHpw@mail.gmail.com>
Date: Mon, 11 Dec 2017 08:46:09 +0100
Message-ID: <CADyq6sLzCfQG02F3uUg-0FfLWeND8KGyokcWp8X487WbuQV2yA@mail.gmail.com>
To: Niklas Keller <me@kelunik.com>
Cc: Andreas Hennings <andreas@dqxtech.net>, PHP Internals List <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="f403045e756660764305600bba7e"
Subject: Re: [PHP-DEV] ReflectionContext for imports and namespace
From: ocramius@gmail.com (Marco Pivetta)

--f403045e756660764305600bba7e
Content-Type: text/plain; charset="UTF-8"

Indeed that already exists at
https://github.com/Roave/BetterReflection/blob/2.0.1/docs/features.md#analysing-types-from-docblocks
- relatively new lib, so it probably didn't get noticed upfront in here.

It would probably be a good idea to address the fact that the current
reflection API causes autoloading and evaluation of the loaded files before
denying API improvement attempts upfront though: that limitation is
unrelated with what Andreas is proposing, in my opinion.

On 11 Dec 2017 08:36, "Niklas Keller" <me@kelunik.com> wrote:

Andreas Hennings <andreas@dqxtech.net> schrieb am Mo., 11. Dez. 2017, 01:39:

> TLDR:
> I propose to introduce a new class \ReflectionContext (or perhaps
> \ReflectionScope?), to give information about imported aliases and the
> namespace.
>
>
> ## Background / motivation
>
> Some libraries that parse doc comment annotations, e.g. phpDocumentor,
> need to know the class aliases and the namespace that are active in
> the place (scope) where the class, function or method is declared.
>
> E.g. phpDocumentor has this class:
>
> https://github.com/phpDocumentor/TypeResolver/blob/
552bf401d264a443819a66233932be6a23f59d78/src/Types/Context.php
>
> To get this information, they parse the PHP file where the class is
> defined:
>
> https://github.com/phpDocumentor/TypeResolver/blob/
552bf401d264a443819a66233932be6a23f59d78/src/Types/ContextFactory.php
>
> It would be much more pleasant if PHP would provide this information
> through the reflection API.
> A custom library should not need to do an expensive and fragile
> parsing job for information that is already known.
>
> Also, this external parsing might not cover all cases, depending how
> it is implemented. E.g. local namespace scopes in curly brackets. (Who
> uses those, btw?)
>
>
> ## Proposal
>
> Make information about class aliases (imported through use statements)
> and the active namespace available through the reflection API.
>
> $reflClass = new \ReflectionClass(C::class);
> $reflContext = $reflClass->getContext();
> $aliases = $reflContext->getAliases();
>
>
> ## Details
>
> class ReflectionContext {
>
>   function getNamespace() : string {..}
>
>   /**
>    * @return string[]
>    *   Format: $[$alias] = $qcn
>    */
>   function getAliases() : string[] {..}
>
>   /**
>    * @return string|null
>    *   The qcn of the class, or null if it is a built-in type like
> "string".
>    */
>   function resolveAlias($alias) : ?string {..}
> }
>
> The $reflClass->getContext()->getNamespace() is the same as
> $reflClass->getNamespace().
>
> But having it all in the $context object allows this object to be
> passed around to components that need it.
>
>
> ## Open questions
>
> In a method doc comment, we also want to resolve the "self" keyword.
> For this, the class name is needed as well, not just external imports
> and namespace.
>
> Maybe also introduce \RefllectionMethod::getContext()? Not sure.
>
> Should it be "context" or "scope"? It is not the same. Maybe "scope"
> leads to the wrong expectations.
>

Documentation tools shouldn't run the code IMO, that means they won't have
access to that feature.

Nikic's PHP parser already contains a tool that resolves all namespaces,
you can probably write a similar visitor for the Ast that also works for
PHPdoc blocks.

Regards, Niklas

>

--f403045e756660764305600bba7e--