a PHP library for YAML

dallgoot — Thu, 19 Dec 2019 09:03:26 +0000

What for ?

This is to read YAML content or to generate YAML content corresponding to PHP values.
If you don't know what YAML is I suggest this Wikipedia Article

But there are already multiple libraries for YAML in PHP

Yes but some are not maintained anymore or they lack support of all features of YAML like :

multiple documents in a content

Example

---
document 1

---
document 2

Dallgoot/YAML will return an array which contains 1 YamlObject for each document.
When only one document is present only a YamlObject is returned for simplicity.

complex mappings

Mappings are usually used with simple string values as keys like

simple string : "some value"

but YAML also supports complex values for keys like

? [an, array, of, strings]
: "still some simple value"

Dallgoot/YAML provides support of complex keys by json-ing them.
These values end as a JSON string which is suitable to be used as properties of YamlObject (or standard PHP object).
They cannot be adressed specifically unless you already know their JSON evaluation but the object can be iterated by a simple foreach loop with "$key=>$value" parameters and then json_decode-d to use them as complex types.

anchors (think as pointers or variables or references) are not really supported or they're duplicated content.

Take a look at this YAML :

some key : &my_anchor some string value
another key : *my_anchor

In Dallgoot/YAML anchors are parsed as variable reference which means that "some key" and "another key" points to the same value "some string value". Changing the value on the YAMLObject changes all values from pointers to it.

comments are discarded

Unless i'm mistaken comments in YAML are usually discarded. In Dallgoot/YAML they are preserved in the YamlObject by default and can be accessed by line number or the list (PHP array) can be looped through.

Why an article on Dev.to

Developing a library is a bold exercice. It is assuming that it will be of use for many people. In that regard, it should not only do the job that it is supposed to but do it well and concerning parsers do it for every file.

At the time of writing this article the library has 374 tests and 838 assertions and has been tested on PHP versions starting from 7.1.10 to 7.4.0 however this is not enough and hence the "Beta" warning still left.

It needs YOU : that you test your YAML files against it and open a Github issue (or just leave a comment here) if you encounter any problems or malfunctions.

That's where the help of the Dev.to community will be greatly appreciated ;)

For installation, concrete use examples, in depth documentation or simply code discovery you'll find what you need in the Github Repo.
Feel free to comment here if you need help or something isn't clear enough.

dallgoot / yaml

PHP library to load and parse YAML file to PHP datatypes equivalent

Thank you for your attention and comments, critics, suggestions are welcomed.

DEV Community: dallgoot