正确的DocBlock注释类的方法，它实现工厂设计模式

Question

正确的DocBlock评论的含义是：

• 符合PHPDoc standard

• 提供PHPStorm IDE自动填充

这是班级本身：

class Factory_DomainObjects
{
    /**
     * Build domain object
     *
     * @param $name
     *
     * @return M_UserObject|M_TransactionObject
     */
    public function build($name)
    {
        $class = 'M_' . $name . 'Object';
        return new $class();
    }
}

它根据Core_Object参数从$name层次结构中返回一个对象。

目前Core_Object层次结构如下所示：

我为@return标记提供了M_UserObject|M_TransactionObject类型说明。它为PHPStorm提供自动操作，并符合PHPdoc标准。

- 但这正是你想要的，问题是什么？
- 是和否，请继续阅读：）

问题：
如果Core_Object层次结构会变成这样的结果怎么办？

这会将@return标记说明变成混乱：

/**
 * @return M_TransactionObject|M_UserObject|M_Foo|M_Foo1|M_Foo2|M_Foo3|M_Bar|M_Bar1|M_Bar2|M_Bar3
 */

到目前为止我找到的唯一解决方法：为每个对象使用单独的build方法，即

/**
 * Build user domain object
 * 
 * @return M_UserObject
 */
public function buildUser()
{
    return new M_UserObject();
}

/**
 * Build transaction domain object
 * 
 * @return M_TransactionObject
 */
public function buildTransaction()
{
    return new M_TransactionObject();
}

您认为我的解决方法有哪些陷阱？你会建议什么？

Answer 1

这里的简单答案是您不应该从单个方法返回多个对象类型。让我详细说明一下：

当我说“类型”时，我指的是并非都以某种方式共享相同类型信息的对象。在你的情况下，他们都是CoreObject（顺便说一句，这是一个可怕的名称）。所以我只需将返回类型提示标记为CoreObject并完成它。

处理类似这样的事情的首选方法是使用接口，并让您的方法返回该接口的实现。如果您没有所有返回类型的公共接口，那么您需要实现不同的方法（至少或可能不同的工厂）。

Answer 2

目前无法实现。

观看此故障单，了解它的实施时间：http://youtrack.jetbrains.com/issue/WI-6027

如果您不希望每个类都有单独的方法，那么我可能只建议使用 PHPDoc @var注释用于局部变量（这可能非常不方便 - 取决于您的使用方式它）：

/** @var M_FooObject $myFoo */
$myFoo = $factory->build('Foo');

Answer 3

建议的方法是首先放置常规类型（如果您的工厂创建特定类型的子类型，而不是类型），然后您可以添加所有子类型（或重要类型）。

这通常对PHPStorm非常有用，并且完全没有违反PHPDoc。

/**
 * @return M_TransactionObject|M_UserObject|M_Foo|M_Foo1|M_Foo2|M_Foo3|M_Bar|M_Bar1|M_Bar2|M_Bar3
 */

这太过分了。我通常使用 @return 标签不超过三种（子）类型。我会说这是一个很好的经验法则。

例如：

 * @return M_UserObject|M_TransactionObject

在我眼里是可以的。一个类似的提示 - 移动是：

 * @return array|string[]

或

* @return Iterator|string[]

第一种类型表示已定义的用法（例如最后一行是getIterator()的{​​{1}}），替代类型对于解决IDE-Typehinting的缺陷很有用（PHPStorm从来没有那么简单）这很好。）

HTH。 @ircmaxell所写的内容并没有错，但是如果你为他的意思留下第一个返回类型（接口去那里），只要你理解替代类型仅用于类型提示，你就没问题。如果工厂方法返回许多不同的“类型”，则所有这些应该共享一个接口。这个很重要。例如，如果您看到长列表，则应该有一种类型，并且一种类型是接口。