使用 docblocks 在 PHP 中记录抽象工厂方法 return 类型

Question

这个问题已经被问过一次又一次，但回复有点陈旧，我有点迫切希望能有所改变，因为回复“无法完成”。

上下文：

    class AbstractBuildObject {}
    class Hammer extends AbstractBuildObject{}
    class Nail extends AbstractBuildObject{}

    class AbstractFactory{    
        /**
          * return $type
          */
        public function build1(string $type): AbstractBuiltObject {
            return new $type();
        }

        /**
          * return any(AbstractBuiltObject)
          */
        public function build2(string $someArg): AbstractBuiltObject {
            $type = $this->decideTypeBasedOnArgsAndState($someArg);
            return new $type();
        }
    }

我试图用构建器上方的注释来表示我需要的东西。

return $type（或者理想情况下 return $type of AbstractBuiltObject 应该提示输入参数中指定了 return 类型。

在第二种情况下，any(AbstractBuiltObject) 表示抽象 class 的任何派生具体化都可能被 return 编辑。

所以我需要某种注释来实现我描述的效果。这些注释显然不起作用，我只是用它们来说明这个概念。

我知道有人可能会想使用像 return Hammer|Nail 这样的管道类型连接，但在我的例子中，每次向项目添加新的具体实现时，工厂 class 都应该修改，它在 build1 的情况下也不够具体，我确切地知道 return 类型应该是什么。

所以，简而言之，我需要它至少在 PhpStorm 中工作：

    (new AbstractFactory())->build1(Hammer::class)-> // I should have Hammer autocomplete here
    (new AbstractFactory())->build2('foo')-> // I should have autocomplete of any concretion of the abstract here

Answer 1

关于打破 SOLID 中 D 的哲学对话，如果你想要这样的东西来自动完成仅 Hammer 上可用的方法：

(new AbstractFactory())->build1(Hammer::class)->

那么您已经承诺专门为 Hammer class 编写此代码块。如果你打算这样做，那么你也可以这样做：

$hammer = (new AbstractFactory())->build1(Hammer::class);

如果你这样做，那么你也可以这样做：

/**
 * @var Hammer
 */
$hammer = (new AbstractFactory())->build1(Hammer::class);

然后您在 $hammer-> 上的自动完成应该可以工作。

Answer 2

我们采用的解决方案是这样的：

<?php
class AbstractBuiltClass {
    /**
      * @return static
      */
    public static function type(self $instance)
    // change return type to :static when #PHP72 support is dropped and remove explicit typecheck
    :self
    {
        if(!($instance instanceof static)){
            throw new Exception();
        }
        return $instance;
    }
}

class Hammer extends AbstractBuiltClass{
    function hammerMethod(){}
}

Hammer::type($factory->get(Hammer::class))->hammerMethod();

可行解决方案的竞争者：

诗篇模板注释：https://psalm.dev/docs/annotating_code/templated_annotations/非常有前途但尚未得到广泛支持
可变文档块（参见）

使用 docblocks 在 PHP 中记录抽象工厂方法 return 类型

Documenting abstract factory method return types in PHP with docblocks

php

phpstorm

phpdoc

abstract-factory