如何使用 phpDOC 记录加载的 xml 结构

Question

考虑包含复杂元素的文件 'cars.xml'：

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <car>
        <model>Volvo</model>
        <color>red</color>
    </car>
    <car>
        <model>BMW</model>
        <color>black</color>
    </car>
</root>

在 PHP 中加载后，我如何通过 phpDoc 记录 $xml 变量的结构，尤其是它可以在 IntelliJ-IDEA 中用于代码完成？

/**
 * @var ?????????? $xml
 */
$xml=simplexml_load_file('cars.xml');

Answer 1

不要 :) 您的 XML 更有可能是一个或多个对象的序列化。

因此，在您的软件中，您不会传递 XML 对象，而是仅在序列化或反序列化对象时使用它。

然后传递可能是具体类型的对象。

所以让我们把你的问题自上而下。当您想要具体类型时，为什么要关心 XML 。假设您想拥有一辆或多辆汽车，那么让我们来创造它们吧！

/**
 * Class Car
 */
class Car
{
    private $model;
    private $color;

    /**
     * Car constructor.
     *
     * @param $model
     * @param $color
     */
    public function __construct($model, $color)
    {
        $this->model = $model;
        $this->color = $color;
    }

    /**
     * @return mixed
     */
    public function getColor()
    {
        return $this->color;
    }

    /**
     * @return mixed
     */
    public function getModel()
    {
        return $this->model;
    }
}

现在这很容易。没错，就是这样：

$car = new Car('Sahara', 'Blue');

IntelliJ-IDEA 已经正确地对 $car 变量进行了类型提示。

但是等等，你没有问过 XML 吗？嗯，确实如此。好的，让我们再做一次。当我们需要它们时，让我们假装它们已经存在。例如，将 XML 转换为 Cars 的数组：

$buffer = <<<XML
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <car>
        <model>Volvo</model>
        <color>red</color>
    </car>
    <car>
        <model>BMW</model>
        <color>black</color>
    </car>
</root>
XML;

$xml = new SimpleXMLElement($buffer);

$carsArray = new CarsArray();

$cars = $carsArray->fromXml($xml);

现在又简单了。肯定的问题是 CarsArray 现在是什么？好吧，假设它是某种概念将 SimpleXMLElement 转换为 Car[ 的数组=61=]s，反之亦然：

/** * Class CarsArray */ class CarsArray { /** * @param array $cars * * @return SimpleXMLElement */ public function toXml(array $cars) { $xml = new SimpleXMLElement('<root/>'); foreach ($cars as $car) { if ($car instanceof Car) { $node = $xml->addChild('car'); $node->addChild('color', $car->getColor()); $node->addChild('model', $car->getModel()); } } return $xml; } /** * @param SimpleXMLElement $xml * * @return array|Car[] */ public function fromXml(SimpleXMLElement $xml) { $array = []; foreach ($xml->car as $car) { $array[] = new Car($car->model, $car->color); } return $array; } }

如您所见，这没什么特别的。并且已经是一个有效的例子。这是它的最后一部分：

foreach ($cars as $car) { echo "- ", $car->getModel(), "\n"; }

执行以下输出：

- Volvo - BMW

要从此处的 vartype 提示中获益，使用 return 值的数组提示类型很重要。让我们再来看看 fromXml() 方法：

/** * @param SimpleXMLElement $xml * * @return array|Car[] */ public function fromXml(SimpleXMLElement $xml) { $array = []; ...

如您所见，@return array|Car[] 表明 return 值是一个数组并且（因此竖线“|”）是一个 Cars的数组，由后面的一对方括号表示（代表数组）。

* @return array|Car[]

这将再次为您提供代码补全。不仅如此，在应用程序的很大一部分中，您知道如何处理 Car 对象，并且它独立于 XML 以及 XML 和 XML 之间的关系汽车只对您程序中需要 translate/convert/map 两者之间的部分感兴趣。

希望对您有所帮助。

您可以在此处找到代码以及交互式在线示例：https://eval.in/439670

如何使用 phpDOC 记录加载的 xml 结构

How to document loaded xml structure with phpDOC

php

xml

phpdoc

intellij-idea

phpstorm