README

一个使用 [在此处放置你的文件类型] 文件进行验证的 [在此处放置另一个文件类型] 架构验证器。
目前，文件类型可以是 Json、Yaml 或 XML。它可以生成关于架构的文档或 XSD 文件（实验性）。

名称来源于它最初是为了实现 Yaml 文件的伪架构而制作的。

安装

基本用法
如何编写架构

简介
架构结构
架构节点
更多信息

文档生成器
关于 XML 支持的说明
XSD 生成器
测试
扩展
感谢

安装

它是一个独立组件

核心需要 PHP >= 5.3.3
要使用 YamlLoader，您需要 Symfony 组件 Yaml（独立组件，不需要 Symfony2）
要运行测试，您需要 atoum

通过 composer 安装，只需执行 composer require romaricdrigon/metayaml

基本用法

您必须创建一个 MetaYaml 对象，然后将架构和您的数据（作为多维 php 数组）传递给它

use RomaricDrigon\MetaYaml\MetaYaml;

// create object, load schema from an array
$schema = new MetaYaml($schema);

/*
    you can optionally validate the schema
    it can take some time (up to a second for a few hundred lines)
    so do it only once, and maybe only in development!
*/
$schema->validateSchema(); // return true or throw an exception

// you could also have done this at init
$schema = new MetaYaml($schema, true); // will load AND validate the schema

// finally, validate your data array according to the schema
$schema->validate($data); // return true or throw an exception

您可以使用提供的任何加载器来获取这些数组（是的，您可以使用来自 Yaml 文件的架构来验证 XML！）。

一些加载器示例

use RomaricDrigon\MetaYaml\MetaYaml;
use RomaricDrigon\MetaYaml\Loader\YamlLoader;
use RomaricDrigon\MetaYaml\Loader\XmlLoader; // JsonLoader is already available

// create one loader object
$loader = new JsonLoader(); // Json (will use php json_decode)
$loader = new YamlLoader(); // Yaml using Symfony Yaml component
$loader = new XmlLoader(); // Xml (using php SimpleXml)

// the usage is the same then
$array = $loader->load('SOME STRING...');
// or you can load from a file
$array = $loader->loadFromFile('path/to/file');

如何编写架构

简介

架构文件将定义数组结构（哪些元素是允许的，在哪里），一些属性（必需的，可以空...）以及这些元素的可能的值（或它们的类型）。

以下是一个简单的架构示例，使用 Yaml 语法

root: # root is always required (note no prefix here)
    _type: array # each element must always have a '_type'
    _children: # array nodes have a '_children' node, defining their children
        flowers:
            _type: array
            _required: true # optional, default false
            _children:
                rose:
                    _required: true
                    _type: text
                violet:
                    _type: text
                # -> only rose and violet are allowed children of flowers

以下是一个有效的 Yaml 文件

flowers:
    rose: "a rose"
    violet: "a violet flower"

我们将继续使用 Yaml 示例；如果您不熟悉语法，您可能想看看它的 Wikipedia 页面。当然，使用 Json 或 XML 也可以有相同的结构，因为核心是相同的。请查看 test/data/ 文件夹中的示例。

架构结构

架构文件必须有一个 root 节点，该节点将描述第一级内容。您可以选择定义一个 prefix；默认为 _（_type、_required...）。

如果您想使用此功能，必须定义一个 partials 节点（有关更多信息，请参阅以下内容）。

一个基本的架构文件

root:
    # here put the elements who will be in the file
    # note that root can have any type: an array, a number, a prototype...
prefix: my_ # so it's gonna be 'my_type', 'my_required', 'my_children'...
partials:
    block:
        # here I define a partial called block

架构节点

架构中的每个节点都必须有一个 _type 属性。这里我定义了一个名为 paragraph 的节点，其内容是一些文本

paragraph:
    _type: text

以下类型可用

text：标量值
number：数值
boolean：布尔值
pattern：检查值是否与在 _pattern 中提供的正则表达式匹配，_pattern 是一个 PCRE 正则表达式
enum：枚举；在 _values 节点中列出接受值
array：数组；在 _children 节点中定义子节点；数组的孩子必须具有确定的命名键；任何额外的键都会导致错误
prototype：定义一个不重要的名称/索引的项目的重复。您必须在_prototype节点中给出子类型的定义。
choice：子节点可以是_choices中提供的任意节点。在_choices数组中的键不重要（只要它们是唯一的）。在每个选择中，最好首先放置区分字段。
partial：“快捷方式”到在partials根节点中描述的块。在_partial中提供部分名称。

您可以指定其他属性

通用属性
_required：此节点必须始终定义（默认为false）
_not_empty用于文本、数字和数组节点：它们不能为空（默认为false）。相应的空值是''、0（作为字符串、整数或浮点数）、array()。要测试null值，请使用_required代替。
_strict与文本、数字、布尔值和枚举一起使用将强制执行严格的类型检查（分别与字符串、整数或浮点数、布尔值、这些值中的任何值一起使用）。当与可能不是类型感知的解析器（如XML解析器；Yaml和json应该是可以的）一起使用时，请小心使用这些。
_description：全文描述，参看文档生成器
仅适用于数组节点
_ignore_extra_keys：节点可以包含不在_children中列出的键的子节点；它们将被忽略
仅适用于原型节点
min_items：原型节点应至少包含'min'个元素
max_items：相反，原型节点中的最大元素数量（默认为200）

这里有一个综合示例

root:
    _type: array
    _children:
        SomeText:
            _type: text
            _not_empty: true # so !== ''
        SomeEnum:
            _type: enum
            _values:
                - windows
                - mac
                - linux
        SomeNumber:
            _type: number
            _strict: true
        SomeBool:
            _type: boolean
        SomePrototypeArray:
            _type: prototype
            _prototype:
                _type: array
                _children:
                    SomeOtherText:
                        _type: text
                        _is_required: true # can't be null
        SomeParagraph:
            _type: partial
            _partial: aBlock # cf 'partials' below
        SomeChoice:
            _type: choice
            _choices:
                1:
                    _type: enum
                    _values:
                        - windows
                        - linux
                2:
                    _type: number
                # so our node must be either #1 or #2
        SomeRegex:
            _type: pattern
            _pattern: /e/
partials:
    aBlock:
        _type: array
        _children:
            Line1:
                _type: text

文档生成器

每个节点都可以有一个_description属性，包含一些可读文本。您可以像这样检索有关节点（其类型、描述、其他属性）的文档

// it's recommended to validate the schema before reading documentation
$schema = new MetaYaml($schema, true);

// get documentation about root node
$schema->getDocumentationForNode();

// get documentation about a child node 'test' in an array 'a_test' under root
$schema->getDocumentationForNode(array('a_test', 'test'));

// finally, if you want to unfold (follow) all partials, set second argument to true
$schema->getDocumentationForNode(array('a_test', 'test'), true);
// watch out there's no loop inside partials!

它返回一个格式如下关联数组

array(
    'name' => 'test', // name of current node, root for first node
    'node' => array(
        '_type' => 'array',
        '_children' => ... // and so on
    ),
    'prefix' => '_'
)

如果目标节点位于选择中，则结果会有所不同

array(
    'name' => 'test', // name of current node, from the choice key in the schema
    'node' => array(
        '_is_choice' => 'true', // important: so we know next keys are choices
        0 => array(
            '_type' => 'array' // and so on, for first choice
        ),
        1 => array(
            '_type' => 'text' // and so on, for second choice
        ),
        // ...
    ),
    'prefix' => '_'
)

此行为允许我们处理嵌套的选择，而不会丢失数据（对于每个选择级别，都有一个数组级别，并且您可以检查_is_choice标志）

如果传递无效的路径（例如，没有您给出的名称的节点），它将抛出异常。

关于 XML 支持的说明

在XML中，您可以在子元素或使用属性中存储节点内的值。在数组中不可能这样做；唯一的方法是使用子节点。

因此，XML加载器强制执行以下约定

元素和属性作为子节点存储，使用元素名称和内容，或属性名称和值，分别作为键和值
如果节点有一个属性和一个具有相同名称的子节点，则属性将覆盖它
如果节点既有属性又有文本内容，则文本内容将存储在键_value下
具有相同名称的多个子节点将被覆盖，仅保留最后一个；除非它们有_key属性，然后将被这样使用
不支持命名空间
跳过空节点

让我们举一个例子

<fleurs>
    <roses couleur="rose">
        <opera>une rose</opera>
        <sauvage>
            <des_bois>une autre rose</des_bois>
            <des_sous_bois sauvage="oui">encore</des_sous_bois>
        </sauvage>
    </roses>
    <tulipe>je vais disparaitre !</tulipe>
    <tulipe>deuxieme tulipe</tulipe>
    <fleur couleur="violette" sauvage="false" _key="violette">une violette</fleur>
</fleurs>

将给我们这个数组

array('fleurs' =>
    'roses' => array(
        'couleur' => 'rose',
        'sauvage' => array(
            'des_bois' => 'une autre rose',
            'des_sous_bois' => array(
                'sauvage' => 'oui',
                '_value' => 'encore'
            )
        )
    ),
    'tulipe' => 'deuxieme tulipe',
    'violette' => array(
        'couleur' => 'violette',
        'sauvage' => 'false',
        '_value' => 'une violette'
    )
)

XSD 生成器

请注意，此功能仍然是实验性的！

MetaYaml可以尝试从一个MetaYaml模式生成一个XML模式定义。您可能希望使用此文件来预先验证XML输入，或在其他上下文中使用（客户端...）。将使用相同的约定（参见图表）。

使用示例

use RomaricDrigon\MetaYaml\MetaYaml\XsdGenerator;

// create a XsdGenerator object (requires Php XMLWriter from libxml, enabled by default)
$generator = new XsdGenerator();

// $schema is the source schema, php array
// second parameter to soft-indent generated XML (default true)
$my_xsd_string = $generator->build($schema, true);

存在一些限制，其中一些与XML Schema相关

root节点必须是一个数组
一个元素不能以数字开头
所有第一级节点都是必填的（但它们可能是空的）
不支持choice节点
由于实现差异，pattern可能具有略微不同的行为
prototype子节点类型将不会被验证
没有strict模式
ignore_extra_keys属性将导致所有子节点都不进行验证

测试

该项目已使用atoum完全测试。要启动测试，请在shell中运行./bin/test -d test

扩展

您可能想编写自己的加载器，使用任何其他工具。
查看Loader/文件夹中的任何类，它很简单：您需要实现LoaderInterface接口，并且可能希望扩展Loader类（这样您就不必编写loadFromFile()）。

感谢

感谢Riad Benguella和Julien Bianchi的帮助和建议。

顶部

fiasco / 元yaml

维护者

详细信息