Download the PHP package shiftby/metayaml without Composer
On this page you can find all versions of the php package shiftby/metayaml. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download shiftby/metayaml
More information about shiftby/metayaml
Files in shiftby/metayaml
Package metayaml
Short Description Using [Yaml|Xml|json] schemas files to validate [Yaml|Xml|json]
License MIT
Homepage http://github.com/romaricdrigon/MetaYaml
Informations about the package metayaml
MetaYaml
A [put your file type here]
schema validator using [put another file type here]
files.
At the moment, file type can be Json, Yaml, or XML. It can generate a documentation about the schema, or a XSD file (experimental).
The name comes from the fact that it was initially made to implement a pseudo-schema for Yaml files.
- Installation
- Basic usage
- How to write a schema
- Introduction
- Schema structure
- Schema nodes
- More information
- Documentation generator
- Notes on XML support
- XSD generator
- Test
- Extending
- Thanks
Installation
It is a standalone component:
- the core requires PHP >= 5.3.3
- to use the YamlLoader, you will need the Symfony component Yaml (standalone component, does not require Symfony2)
- to launch the tests, you'll need atoum
To install via composer just do composer require romaricdrigon/metayaml
Basic usage
You have to create a MetaYaml object, and then pass it both the schema and your data as multidimensional php arrays:
You can use any of the provided loaders to obtain these arrays (yep, you can validate XML using a schema from an Yaml file!).
Some loader examples:
How to write a schema
Introduction
A schema file will define the array structure (which elements are allowed, where), some attributes (required, can be empty...) and the possible values for these elements (or their type).
Here's a simple example of a schema, using Yaml syntax:
And a valid Yaml file :
We will continue with Yaml examples; if you're not familiar with the syntax, you may want to take a look at its Wikipedia page.
Of course the same structure is possible with Json or XML, because the core is the same. Take a look at examples in test/data/
folder.
Schema structure
A schema file must have a root
node, which will describe the first-level content.
You can optionally define a prefix
; by default it is _
(_type
, _required
...).
You have to define a partials
node if you want to use this feature (learn more about it below).
A basic schema file:
Schema nodes
Each node in the schema must have a _type
attribute.
Here I define a node called paragraph
whose content is some text:
Those types are available:
text
: scalar valuenumber
: numeric valueboolean
: boolean valuepattern
: check if the value matches the regular expression provided in_pattern
, which is a PCRE regexenum
: enumeration ; list accepted values in_values
nodearray
: array; define children in a _children node; array's children must have determined named keys; any extra key will cause an errorprototype
: define a repetition of items whose name/index is not important. You must give children's type in_prototype
node.choice
: child node can be any of the nodes provided in_choices
. Keys in_choices
array are not important (as long as they are unique). In each choice, it's best to put the discriminating field in first.partial
: "shortcut" to a block described inpartials
root node. Provide partial name in_partial
You can specify additional attributes:
- general attributes:
_required
: this node must always be defined (by default false)_not_empty
for text, number and array nodes: they can't be empty (by default false). Respective empty values are''
,0
(as a string, an integer or a float),array()
. To test fornull
values, use_required
instead._strict
with text, number, boolean and enum will enforce a strict type check (respectively, with a string, an integer or a float, a boolean, any of these values). Be careful when using these with a parser which may not be type-aware (such as the XML one; Yaml and json should be ok)_description
: full-text description, cf. Documentation generator
- only for array nodes:
_ignore_extra_keys
: the node can contain children whose keys are not listed in_children
; they'll be ignored
- only for prototype nodes:
min_items
: the prototype node should contain at least 'min' elementsmax_items
: the opposite, the max number of elements in the prototype node (by default 200)
Here's a comprehensive example:
More information
For more examples, look inside test/data
folder.
In each folder, you have an .yml file and its schema. There's also a XML example.
If you're curious about an advanced usage, you can check data/MetaSchema.json
: schema files are validated using this schema (an yep, the schema validates successfully itself!)
Documentation generator
Each node can have a _description
attribute, containing some human-readable text.
You can retrieve the documentation about a node (its type, description, other attributes...) like this:
It returns an associative array formatted like this:
If the targeted node is inside a choice, the result will differ slightly:
This behavior allow us to handle imbricated choices, without loosing data (you have an array level for each choice level, and you can check the flag _is_choice
)
If you pass an invalid path (e.g. no node with the name you gave exist), it will throw an exception.
Notes on XML support
In XML, you can store a value in a node within a child element, or using an attribute. This is not possible in an array; the only way is to use a child.
Thus, the following conventions are enforced by the XML loader:
- elements AND attributes are stored as child, using element name and content, or attribute name and value, as respectively key and value
- if a node has an attribute and a child node with the same name, the attribute will be overwritten
- if a node has both attribute(s) and a text content, text content will be stored under key
_value
- multiple child node with the same name will be overwritten, only the last will be retained; except if they have a
_key
attribute, which will be used thus - namespaces are not supported
- empty nodes are skipped
Let's take an example:
will give us this array:
XSD generator
Please note this feature is still experimental!
MetaYaml can try to generate a XML Schema Definition from a MetaYaml schema. You may want to use this file to pre-validate XML input, or to use in another context (client-side...). The same conventions (cf. above) will be used.
Usage example :
A few limitations, some relative to XML Schema, apply:
root
node must be anarray
- an element can't have a name beginning by a number
- all first-level nodes will be mandatory (but they may be empty)
choice
node are not supportedpattern
may have a slightly different behavior due to implementations differencesprototype
children nodes type will not be validatedstrict
mode does not existsignore_extra_keys
attribute will cause all children nodes not to be validated
Test
The project is fully tested using atoum.
To launch tests, just run in a shell ./bin/test -d test
Extending
You may want to write your own loader, using anything else.
Take a look at any class in Loader/ folder
, it's pretty easy: you have to implement the LoaderInterface, and may want to extend Loader class (so you don't have to write loadFromFile()
).
Thanks
Thanks to Riad Benguella and Julien Bianchi for their help & advice.
Top