README

再也不用手动操作 XML 了！（希望如此。）

请注意：LaravelXML 可能存在一些问题。请随意提出 pull requests！

本包针对 Laravel 框架。在某些时候可能会创建一个独立的版本。

尝试过将各种类型的值转换为 XML 吗？也许你需要一个“导出为 XML”的功能。如果你有，那么你可能会知道 XML 可能会非常 痛苦。

LaravelXML 旨在解决这个问题。轻松地修改对象将如何以及何时被转换。你甚至可以编写自己的代码来扩展它！这有多酷？

如果你的应用程序中使用了 XML，那么 LaravelXML 是你的一个不错的选择！

先决条件

要使用 LaravelXML，实际上没有具体的先决条件。只需确保你已经安装了 xml PHP 扩展！你可以通过运行 php -i | grep xml 来检查是否已安装，并查看是否有任何返回结果。如果运行该命令后没有显示任何内容，你需要安装 XML 扩展。

你还需要有 PHP 7.0 或更高版本。

安装

安装快速简单。你只需要运行

composer require fetchleo/laravel-xml dev-master

目前还没有稳定的版本。我打算再做一些测试，直到我确信一切正常后再发布版本。

完成之后，请确保在你的 config/app.php 中注册包的服务提供者，添加以下行

FetchLeo\LaravelXml\XmlServiceProvider::class

实际上你不需要做任何事情！当然，你可以随时修改配置，这将在下面介绍。

配置

如果你想要发布 LaravelXML 的配置文件，只需运行

php artisan vendor:publish --tag=laravel-xml

使用

默认情况下，LaravelXML 应该可以正常工作！不需要立即设置任何奇怪设置。除非你喜欢这样做，那么请继续阅读。

转换值

LaravelXML 提供了一种快速将值转换为 XML 的方法。请注意，由于某些限制，某些类型的值不能单独转换。然而，它们可以包含在可以转换的其他值中。

这些不能单独转换的类型包括

• 整数（或双精度/浮点数）
• 字符串

这意味着除非它们包含在其他可以转换的值（如数组等）中，否则它们不能被转换。因此，调用 Xml::convert(1) 会抛出异常。这将在不久的将来进行更改！你将能够为这些类型指定自己的转换器。也可以提供默认的转换器。

无论如何，接下来...

要将值转换为 XML，只需调用 Xml::convert($value)，确保导入 FetchLeo\LaravelXml\Facades\Xml。在底层，LaravelXML 正在尝试为该值定位适当的转换器。如果没有找到合适的转换器，则会抛出异常。你可以指定并创建自己的转换器；请继续阅读了解如何操作！

自定义转换器

除了内置的转换器之外，你还可以创建自己的转换器。

首先，你应该创建一个新的类，该类实现 FetchLeo\LaravelXml\Contracts\Converter 接口。

它可能看起来像这样

<?php

namespace My\App\Namespace;

use FetchLeo\LaravelXml\Contracts\Converter;    
use SimpleXMLElement;
use FetchLeo\LaravelXml\Exceptions\CantConvertValueException;
    
class MyCustomConverter implements Converter 
{
    /**
     * Convert a value to XML.
     *
     * @param Model $value
     * @param SimpleXMLElement $element
     * @return SimpleXMLElement
     * @throws CantConvertValueException
     */
     public function convert($value, SimpleXMLElement $element) : SimpleXMLElement;
     
     /**
      * Determine if this converter can convert the given value.
      *
      * @param mixed $value
      * @param $type
      * @return bool
      */
      public function canConvert($value, $type) : bool;
}

然后，您可以在您的 config/laravel-xml.php 文件中配置新的转换器。 请注意：如果您没有这个文件，请运行 php artisan vendor:publish --provider=FetchLeo\LaravelXml\XmlServiceProvider。

您需要做的是进入 converters 中的 custom 数组。然后，您需要添加一个新条目。键应该是类似于 models 或 objects 或 arrays 或 collections 或任何东西！注意：目前，转换器只能处理一种类型的值（除了字符串和数字，您选择的任何东西。）这可能在将来改变。

值应该是您新类的名称。如果您使用 Laravel 的 IOC 容器注册了别名，您可以使用别名，如果您愿意的话。例如

'custom' => [
    // ...
    'models' => 'My\App\Namespace\MyCustomConverter'
]

除了指定相同泛型类型的所有值的转换器外，您还可以为某些类指定某些转换器！所以，如果您只想让类型为 My\App\Namespace\CustomThing 的值应用转换器，您可以有

'custom' => [
    // ...
    'My\App\Namespace\CustomThing' => 'My\App\Namespace\MyCustomConverter'
]

这将告诉 LaravelXML：“嘿，只有当我给你这个类型的值时，才使用这个转换器！”LaravelXML 足够智能，如果找不到合适的自定义转换器，就会回退到默认转换器。

注册您的转换器

如果您想为您的转换器使用一个自定义名称，而不是手动在 IOC 容器中注册它，您可以这样做

app('laravelxml.converters.manager')->register('name-here', $converterInstance)

LaravelXML 会为您完成所有工作；它负责将一切绑定到容器中，因此您不必担心这些事情。

智能键

LaravelXML 足够智能，能够动态地假设应该使用哪些键，如果不存在合适的键。这个功能包含的原因是 XML 不接受数字作为键。如果您正在处理对象的数组，您肯定会遇到数字键。LaravelXML 不会因为无法使用数字键而崩溃，而是会尝试智能地确定要使用的键。这 99.99% 的时间都有效。（可能 100%）

假设您有一个具有名为 projects 的键的数组（或集合）。在该数组内部，您有许多看起来像这样的元素

[
    'id' => 42,
    'name' => 'Testing event',
    'description' => '...',
    'user' => [
        'id' => 56,
        'name' => 'John Doe',
        'email' => 'doe@some-email-provider.com'
    ]
]

现在，这个数组完全没有顶级键 任何。它只是数组中的数组！通常，如果您甚至尝试将其转换为 XML，您的浏览器会告诉您存在语法错误。为什么？因为当没有设置键时，PHP 会使用数字作为键。记住，数字不被接受作为 XML 标签名称！

因此，LaravelXML 有一个“提供键”系统。当某个基础转换器检测到数组时，它会将第三个参数传递给转换函数。第三个参数的值将作为键被该转换器使用。如果由于某种原因未设置，它将使用值类型作为“回退键”。

注意：此功能默认不包含！您有责任实现它！ 为了了解它的工作原理，请查看以下文件中的任何一个： src/FetchLeo/LaravelXml/Converters/ArrayConverter，src/FetchLeo/LaravelXml/Converters/ModelConverter，src/FetchLeo/LaravelXml/Converters/ObjectConverter

转换器列表

以下是默认提供的不同转换器表，以及它们可以处理的值类型。

结论

我希望 LaravelXML 对您的项目工作良好！我已经花费了大量时间确保它按照预期工作。当然，如果您发现任何错误，请 打开一个问题，如果您有解决方案，甚至可以创建一个 pull request！

即将推出新功能！

待办事项

• 增加将非对象类型转换为XML（字符串、数字等）的局部支持 这很可能通过向XML元素添加一个子元素来实现，其中键是值类型，值是...值。
• 向配置文件添加新设置
• 使外观绑定可选。
• 公开更多私有API方法（对于其中一些，它们不应该是私有的原因）

附言。 所有测试都通过了！