README

为 Symfony 提供简单的 XML 响应格式化器。

这有什么用吗？

总有一天，可能会有人告诉我整个类都是不必要的，如果我更了解 Symfony，我可以通过更简单的方法来完成这个任务。但这可能要等到我为这个项目投入了一千个小时之后才会发生。但无论如何，请告诉我！

重点

这个类是为了能够从动作中返回一个数组，并将其渲染成 XML。这应该和你可以返回一个数组并将其渲染成 JSON 一样简单。动作（控制器……你喜欢什么术语）不需要知道响应的格式，就像它不需要知道请求的格式一样。

我正在使用这个与 AOL/ATC。ATC 本身基于 Aura.Router。在 ATC 中，我有一个自定义的展示器，一旦确定调用者需要 XML 响应，就简单地这样做

$xr = new XmlResponse();

// changing the default root element
$xr->root_element_name = $view;

// data must be set after the root element
$response = $xr->setData($data);

return $response;

在上面的代码中，$data 是一个数组，$view 是一个字符串。

如果默认根元素名称（"document"）是可以接受的，则可以进一步简化为

$response = new XmlResponse($data);
return $response;

或者

return new XmlResponse($data);

或者

// using the static create() method
$response = XmlResponse::create($data);
return $response;

静态 create() 方法和构造函数都接受额外的可选参数来指定状态码和头数组。（默认状态码为 200。）

// specifying optional return code and headers
$response = new XmlResponse($data, null, 202, array('Foo-Header' => 'bar'));
return $response;

数据数组

传递给这个类的数据应该是一个关联数组。每个数组键代表一个 XML 标签名，数组值代表 XML 标签的内容。

$data = array(
    'foo' => 'bar',
    'argle' => 'bargle'
);
$response = new XmlResponse($data);
return $response;

上面的数组将生成以下 XML 输出

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <foo>bar</foo>
  <argle>bargle</argle>
</document>

属性

你可以通过传递一个特殊构造的数组来指定标签的属性。在这个数组中，每个属性应该表示为一个键值对，键以 '@' 预先指定。标签的实际值应该有一个键，该键重复原始键名。所有属性键值对都必须在实际值条目之前。

请注意，这是一个动作提供 XML 属性的边界。如果这个数组被渲染成 JSON 而不是 XML，那么它可能无法使用。这种设计是存在缺陷的，并且在未来需要进行更改。

$data = array(
    'foo' => array(
        '@buzz' => 'boom',
        '@bing' => 'bam',
        'foo' => 'bar'       // same key name as parent
    ),
    'argle' => 'bargle'
);
$response = new XmlResponse($data);
return $response;

上面的数组将生成以下 XML 输出

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <foo buzz="boom" bing="bam">bar</foo>
  <argle>bargle</argle>
</document>

重复元素

XML 可以有重复的元素。

<?xml version="1.0" encoding="UTF-8"?>
<document>
  <lorem>ipsum</lorem>
  <files>
    <file><name>file1.txt</name><size>10K</size></file>
    <file><name>file2.txt</name><size>20K</size></file>
    <file><name>file3.txt</name><size>8K</size></file>
  </files>
  <et>dolore</et>
</document>

PHP 数组（和 JavaScript 对象）不支持这种结构，除非使用一些非常复杂的结构。为了支持重复字段，请使用 XmlRepeater 类。XmlRepeater 作为一个装饰器作用于 XmlResponse 类。

你可以添加任意数量的 XmlRepeater 实例。每个实例都接受一个占位符、一个元素名称和一个数据数组。该类将数组转换成 XML，将其包装在具有给定名称的元素中，并将其插入到 XmlResponse 结果中，以替换占位符。

// associative array for XmlResponse
$data = [
    'lorem' => 'ipsum',
    'files' => '@filesPlaceHolder@'
    'et' => 'dolore'
];

// indexed array for the repeating data
$file_array = [
    ['name' => 'file1.txt', 'size' => '10K'],
    ['name' => 'file2.txt', 'size' => '20K'],
    ['name' => 'file3.txt', 'size' => '8K']
];

$repeater = new XmlRepeater('@filesPlaceHolder@', 'file', $file_array);

$response = new XmlResponse($data);
$response->addDecorator($repeater);
return $response;

上面的代码将生成包含 "files" 元素内重复 "file" 元素的上述 XML 文档。

许可

根据MIT许可协议授权。