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, 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;

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

许可

MIT 许可证。