[PSR-19] Differentiate between __call and __callStatic methods that return an instance of a subclass.

[Richard Quadling]

Hi.

Within the current PSR-5 and PSR-19 standards, there is no mechanism to document which method are handled by __call() and __callStatic() that return an instance of the subclass.

<?php

/**

 * Class HandlingClass

 *

 * Current design of PSR-5/PSR-19

 * @method static RickRollMe() Am I statically called? Or do I return an instance of the subclass

 * @method static RickRollYou() Am I statically called? Or do I return an instance of the subclass

 *

 * Proposed design

 * @method RickRollMe():static I am an instance method that returns an instance of the subclass

 * @method static RickRollYou():static I am a statically called method that returns an instance of the subclass

 */

abstract class HandlingClass

{

    public function __call($name, $arguments)

    {

        // I'll handle RickRollMe(): static

    }

    public static function __callStatic($name, $arguments)

    {

        // I'll handle RickRollYou(): static

    }

}

Also, now that PHP's documentation correctly places the return type in the same location as how a new developer would write it if they were to copy the signature to their code, shouldn't the standard for `@method` be the same?

Yes. I know. Not how it has been before. But we didn't have parameter type hints, return type, magic methods ... how far back do we need to go?

So, moving FORWARD to match the actual experience of a new PHP developer, not having to question why things don't match up ... a far better goal methinks.

Regards,

Richard Quadling.

[Bruce Weirdan]

On Thu, Oct 10, 2019 at 1:50 PM Richard Quadling <rqua...@gmail.com> wrote:
> * Current design of PSR-5/PSR-19
> * @method static RickRollMe() Am I statically called? Or do I return an instance of the subclass
> * @method static RickRollYou() Am I statically called? Or do I return an instance of the subclass

To reference a prior art, phpDocumentor treats `static` in `@method
static methodName()` as a return type, and to get it recognized as a
modifier you need to provide explicit return type as in `@method
static void methodName()` or `@method static static methodName()` [1].
Psalm and Phan interpret them the same way.

So your examples become:
/**
* @method static RickRollMe() I am dynamically called and return an
instance of the subclass
* @method static static RickRollYou() I am statically called and

return an instance of the subclass

*/

[1] https://github.com/phpDocumentor/phpDocumentor2/issues/822


--
Best regards,
Bruce Weirdan mailto:wei...@gmail.com