YAML V2 plugin for SPIP 3.*

Versions and compliance

This second branch of the plugin is dedicated to SPIP 3.
Compliance with SPIP 2.* has been abandoned (suppressing the plugin.xml file) and, as a consequence, PHP 4 is not supported anymore either.
SPIP minimum compliance has been set to version 3.0.0, although you’ll need to have a PHP version 5.3.3 or higher, to ensure the plugin can work properly.

By default, with no settings modification, plugin is to use the same library version the branch v1 already uses, except this one has been refreshed, as mentioned in a forthcoming section of this post.

Even if the API functions’ prototype has changed (see next section), the code to call these functions v1 is still valid and will return the same results. Although you should progressively migrate toward v2-like calls (see dedicated section).

Plugin’s API

Plugin YAML’s API (inc/yaml.php file) contains 3 main functions which are already available in v1 and, a deprecated function which is kept for compliance purposes, with branch v1.

Those 3 main functions are :

• yaml_encode($structure, $options = array()), which encodes a PHP data structure to a YAML string ;
• yaml_decode($input, $options = array()), which decodes a YAML string to a PHP data structure, often as an array ;
• yaml_decode_file($file, $options = array()), which decodes a YAML file to a PHP data structure. This function calls yaml_decode() after it extracted the file’s content.

Compared to the API v1, functions’ prototype has been modified, by adding in a systematic manner the optional $options argument, which aggregates all possible options in an array.
How to fully take advantage of it, is detailed in the section which describes the plugin’s advanced usages.

Those functions remains independent from the used YAML library. According the context — _LIB_YAML constant and $options argument’s ’library’ index — each function named $fonction sets the library $library that will be used and, calls it’s « homonym » function $library_$fonction().

Function yaml_charger_inclusions() stands deprecated in this new branch. Even if it remains possible to use it, to recursively integer decoded YAML, out of initial YAML file’s known includes, you should only use yaml_decode_file() function, providing the options with includes’ loading.

Additionally, the decoder_yaml() filter that encapsulates yaml_decode_file() and yaml_to_array() for iterators, has been kept. If decoder_yaml() filter fully takes advantage of optional $options argument, this is not the case with yaml_to_array() which, structurally, can only read the YAML string as an argument.

YAML libraries

The plugin still offers branch v1’s library : Spyc and Symfony/yaml v1 but, also lets you use latest Symfony v4’s version of the YAML component, with extension PECL, which encapsulates the C libYAML library.

Versions of Spyc and Symfony/yaml v1 has been updated and, improvements brought by SPIP to Symfony/yaml v1 have been reported.

Each library require a minimal PHP version and implement a proper sub-set of YAML 1.0, 1.1 or 1.2 specifications. Following table sums those constraints up and provides with the actual version — which is likely to evolve — of each library included in the YAML plugin (initial version 2.0.0).

(*) : The alias is used to pick out the library for the API : $options['library']’s value or, _LIB_YAML constant.

On performance’s side, shall we point out :

• C libYAML library is by far the best for performance, with benchmarks 6 to 15 times faster than others libraries.
• Symfony/yaml v1 and Spyc libraries have quite similar performances, almost correct :
• Symfony/yaml v4 is nearly 2 times slower than v1.

Besides, the YAML specifications sub-set, offered by each library, varies a lot. For SPIP’s needs, mostly linked to some configuration parameters, every library are equivalent, whatever which YAML specifications version is supported. To get an insight on the different implementations, a serie of test files (demo/$library.yaml) is furnished with the plugin. Those files come from the native Spyc library’s test file. For the other libraries, it was adapted, commenting out unsupported cases.

Shall we also point out that two important YAML features are not implemented in the plugin, because they are not available with all libraries :

• the YAML document’s 3 starting dashes « --- » and 3 final dots « ... »
• and as a consequence, the capability to encapsulate multi YAML documents into a single YAML file : a YAML file must then contain only one single YAML document.

By default, to ensure compliance with branch v1, YAML plugin uses the Symfony/yaml v1 library (alias sfyaml), which still remains a good choice.

Plugin’s maintenance

Besides the bug fixed, the plugin’s maintenance matches it’s libraries one.

The default library, Symfony/yaml v1 isn’t maintained anymore. It won’t evolve but still works with current YAML specifications and usages. It’s made of 4 files, located in the sfyaml/ plugin’s directory.

libYAML library is distributed as a PECL extension, so you can install it on Apache server. Nothing to do plugin’s side. You should prefer that one if you can install it.

The two others libraries, Spyc and Symfony/yaml v4, are both incorporated in the plugin with Composer. We’ll find them into the vendor/ directory. It’s possible to upgrade them or, go back to any prior version, using the composer.json file located in the plugin’s root directory and, activating the composer update command.

API : advanced usages

Understanding the various options

Basic usage of the API’s functions has not been modified. Although, adding an $options argument as second parameter for each API’s function makes the plugin more flexible and more accurate to work with. The available options are summarized, function by function, in the following table. An « x » indicates if the option is available for any given library.

Decode includes

Since YAML plugin v1, it’s possible to make includes in a YAML file, like this :

- 'inclure:relative_path/my_file.yaml'

This feature prevents you from duplicating lists of identical blocks in several YAML files, what the specification basically does not allow, This includes processing being quite heavy (recursively browsing the decoded data structure), it’s not applied by default while decoding the YAML but, explicitly requested.

With Bonux v1, that feature is performed by calling the yaml_charger_inclusions() API function, on the result of a decoded YAML file or string :

$configuration = yaml_charger_inclusions(yaml_decode_file($fichier));

With new version 2, we should now perform that processing another way, without calling the yaml_charger_inclusions() function — which then, stands deprecated — but by using a decode option, as shown below :

$configuration = yaml_decode_file($fichier, array('inclure' => true));

Force a library while calling

If the library used by default (_LIB_YAML constant) is not suitable for any specific call, it’s possible to force for that call, another library :

$configuration = yaml_decode_file($fichier, array('library' => 'libyaml'));

Displaying errors

By default, in SPIP Bonux v2, YAML decoding errors are not displayed anymore. To force their display, you’ll have to use ’show_error’ option, as following :

$configuration = yaml_decode_file($fichier, array('show_error' => true));

What’s next ?

• Eventually coming up with a more evolved determination logic to choose the library by default ?
• Deprecating certain libraries to keep only libYAML, if it’s installed or, one of those installed by Composer ?