Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:101305
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain kelunik.com from 81.169.146.160 cause and error)
MIME-Version: 1.0
References: <CAH0Uv3ErvVo5qPotvrHby7AKrzUQix_YuDU5dbQWos8bvCASqw@mail.gmail.com>
In-Reply-To: <CAH0Uv3ErvVo5qPotvrHby7AKrzUQix_YuDU5dbQWos8bvCASqw@mail.gmail.com>
Date: Mon, 11 Dec 2017 07:35:52 +0000
Message-ID: <CANUQDChCkt0CzYHeJoRN+d7_wWBe82-J5MJEgXWFj9qTBMz4Zg@mail.gmail.com>
To: Andreas Hennings <andreas@dqxtech.net>
Cc: PHP Internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="001a11407d68251f7905600b96f5"
Subject: Re: [PHP-DEV] ReflectionContext for imports and namespace
From: me@kelunik.com (Niklas Keller)

--001a11407d68251f7905600b96f5
Content-Type: text/plain; charset="UTF-8"

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

>

--001a11407d68251f7905600b96f5--