如何使用 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 数组（反之亦然）是某种概念：

/**
 * 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 提示中获益，使用返回值的数组提示类型很重要。我们再来看看fromXml()方法：

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

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

     * @return array|Car[]

这将使您再次完成代码。不仅如此，在您的应用程序的大部分中，您都知道如何处理 Car 对象，并且这与 XML 无关，并且 XML 和汽车之间的关系只对您程序的那一部分感兴趣这需要在两者之间进行翻译/转换/映射。

我希望这会有所帮助。

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