Как документировать загруженную структуру XML с помощью phpDOC

Не надо 🙂 Скорее всего, ваш 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 в массив Автомобильs:

$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 в массив Автомобильс и наоборот:

/**
* 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[] говорит, что возвращаемое значение является массив а также (следовательно, труба «|») массив Автомобильs, обозначается парой квадратных скобок позади нее (обозначающей массив).

     * @return array|Car[]

Это даст вам завершение кода снова. И не только это, в значительной части вашего приложения вы знаете, как иметь дело с Автомобиль объекты, и это не зависит от XML, а отношения между XML и автомобилями интересны только для той части вашей программы, которая должна переводить / конвертировать / отображать между ними.

Надеюсь, это поможет.

Вы можете найти код, а также интерактивный онлайн-пример здесь: https://eval.in/439670