Using YAML in Your PHP Projects

Share this article

Test fixtures, configuration files, and log files all need to be both human and machine readable. YAML (YAML Ain’t Markup Language) is a less-verbose data serialization format than XML and has become a popular format among software developers mainly because it is human-readable. YAML files are simply text files that contain data written according to YAML syntax rules and usually have a .yml
file extension. In this article, you will learn the basics of YAML and how you can integrate a PHP YAML parser into your projects.

Understanding YAML Syntax

YAML supports advanced features like references and custom data types, but as a PHP developer, most of the time you’ll be interested in how YAML represents enumerated arrays (sequences in YAML terminology) and associative arrays (mappings). The following is how to represent an enumerated array in YAML:
- 2
- "William O'Neil"
- false
Each element of the array is presented after a hyphen and a space. It’s syntax for representing values is similar to that of PHP (quoting strings, etc.) The above is equivalent to the following PHP:
<?php
array(2, "William O'Neil", false);
Generally, each element will appear on it’s own line in YAML, but enumerated arrays can also be expressed on a single line using brackets:
[ 2, "William O'Neil", false ]
The following code shows how to represent an associative array in YAML:
id:       2
name:     "William O'Neil"
isActive: false
First the element’s key is stated followed by a colon and one or more spaces, and then the value is stated. Having just one space after the colon is sufficient, but you can use more spaces for the sake of better readability if you like. The equivalent PHP array of the above YAML is:
<?php
array("id" => 2, "name" => "William O'Neil", "isActive" => false);
And similar to enumerated arrays, you can express associative arrays on a single line using braces:
{ id: 2, name: "William O'Neil”, isActive: false }
With one or more spaces for indentation, you can represent a multi-dimensional array like so:
author:
  0: { id: 1, name: "Brad Taylor", isActive: true }
  1: { id: 2, name: "William O'Neil", isActive: false }
Note that although the second level arrays are enumerated arrays, I have used the syntax for mappings (colons) instead of the syntax for sequences (hyphens) for clarity. The above YAML block is equivalent to the following PHP:
<?php
array(
    "author" => array(
        0 => array("id" => 1, "name" => "Brad Taylor", "isActive" => true),
        1 => array("id" => 2, "name" => "William O'Neil", "isActive" => false)
    )
);
YAML also allows representing a collection of data elements in the same document without requiring a root node. The following example is the contents of article.yml which shows several multi-dimensional arrays in the same file.
author:
  0: { id: 1, name: "Brad Taylor", isActive: true }
  1: { id: 2, name: "William O'Neil", isActive: false }

category:
  0: { id: 1, name: "PHP" }
  1: { id: 2, name: "YAML" }
  2: { id: 3, name: "XML" }

article:
  0:
    id:      1
    title:   "How to Use YAML in Your Next PHP Project"
    content: >
               YAML is a less-verbose data serialization format.
               It stands for "YAML Ain't Markup Language".
               YAML has been a popular data serialization format among
               software developers mainly because it's human-readable.
    author:  1
    status : 2

articleCategory:
  0: { articleId: 1, categoryId: 1 }
  1: { articleId: 1, categoryId: 2 }
While most of YAML’s syntax is intuitive and easy to remember, there is one important rule to which you should pay attention. Indentation must be done with one or more spaces; tabs are not allowed. You can configure your IDE to insert spaces instead of tabs when you press tab key, which is a common configuration among software developers to make sure code is properly indented and displayed when it’s viewed in other editors. You can learn the more complex features and syntax that YAML supports by reading the official documentation
, the Symfony reference, or Wikipedia.

YAML Need Not Be an Alternative to XML

If you’re researching YAML with your favorite search engine, you will undoubtedly find discussion on “YAML vs XML”, and naturally when you first experience YAML, you would tend to prefer it over XML mainly because its easier to read and write. However, YAML should be another tool in your developer arsenal and need not be an alternative to XML. Here are some advantages of YAML and XML. Advantages of YAML
  • Less-verbose, easy to compose, and more readable
  • Need not have tree structure with a single parent node
Advantages of XML
  • More built-in PHP support compared to YAML
  • XML has been the de facto standard for inter-application communication and is widely recognized
  • XML tags can have attributes providing more information about the enclosed data
Despite its verbosity, XML is more readable and maintainable when the hierarchy of elements is deep compared to YAML’s space-oriented hierarchy representation. Considering the advantages of both languages, YAML seems to be more suitable for collections of different data sets and when humans are also among the data consumers.

Choosing a PHP YAML Parser

A YAML parser is expected to have two functionalities, some sort of load function that converts YAML into an array, and a dump function that converts an array into YAML. Currently PHP’s YAML parser is available as a PECL extension and is not bundled with PHP. Alternatively, there are parsers written in pure PHP which would be slightly slower compared to the PECL extension. The following are a few YAML parsers available for PHP: PECL extension
  • Is not bundled with PHP
  • Will need root access to the server to install
Symfony 1.4 YAML Component
  • Implemented in PHP
  • Will work in PHP 5.2.4+
  • Need to extract from Symfony framework
Symfony 2 YAML Component
  • Implemented in PHP
  • Will work in PHP 5.3.2+
SPYC
  • Implemented in PHP
  • Will work in PHP 5+
My preferred choice is the Symfony 1.4 YAML Component because of its portability (it works with PHP 5.2.4+ versions) and maturity (Symfony 1.4 is a well established PHP framework). Once you’ve extracted the YAML component from the Symfony archive, YAML classes are available under lib/yaml. The static methods load() and dump() are available with the sfYaml class. Editor Note Oct 28 2012: The accompanying code on GitHub has been updated to use Composer for obtaining the PHPUnit and Symfony 1.4 YAML Component dependencies.

Integrating a PHP YAML Parser into Your Project

Whenever you integrate a third-party class or library into your PHP project, it’s good practice to create a wrapper and a test suite. This let’s you later change the third party library with minimal changes to your project code (project code should only refer the wrapper) and with the assurance that change won’t brake any functionality (test suites will tell you). Following is the test case (YamlParserTest.php) I created for my wrapper class (YamlParser.php
). You need knowledge of PHPUnit to run and maintain the test case. You can add more tests if you’d like, for wrong file names and file extensions other than .yml, and other tests based on the scenarios you encounter in your project.
<?php
require_once "YamlParser.php";

class YamlParserTest extends PHPUnit_Framework_TestCase
{
    private $yamlParser;

    public function setup() {
        $this->yamlParser = new YamlParser();
    }

    public function testMainArrayKeys() {
        $parsedYaml    = $this->yamlParser->load("article.yml");
        $mainArrayKeys = array_keys($parsedYaml);
        $expectedKeys  = array("author", "category", "article", "articleCategory");

        $this->assertEquals($expectedKeys, $mainArrayKeys);

    }

    public function testSecondLevelElement() {
        $parsedYaml    = $this->yamlParser->load("article.yml");
        $actualArticle = $parsedYaml["article"][0];
        $title         = "How to Use YAML in Your Next PHP Project";
        $content = "YAML is a less-verbose data serialization format. "
                 . "It stands for "YAML Ain't Markup Language". "
                 . "YAML has been a popular data serialization format among "
                 . "software developers mainly because it's human-readable.n";

        $expectedArticle = array("id" => 1, "title" => $title, "content" => $content, "author" => 1, "status" => 2);

        $this->assertEquals($expectedArticle, $actualArticle);
    }

    /**
     * @expectedException YamlParserException
     */
    public function  testExceptionForWrongSyntax() {
        $this->yamlParser->load("wrong-syntax.yml");
    }
}
And here is the wrapper class:
<?php
require_once "yaml/sfYaml.php";

class YamlParser
{
    public function load($filePath) {
        try {
            return sfYaml::load($filePath);
        }
        catch (Exception $e) {
            throw new YamlParserException(
                $e->getMessage(), $e->getCode(), $e);
        }
    }

    public function dump($array) {
        try {
            return sfYaml::dump($array);
        }
        catch (Exception $e) {
            throw new YamlParserException(
                $e->getMessage(), $e->getCode(), $e);
        }
    }
}

class YamlParserException extends Exception
{
    public function __construct($message = "", $code = 0, $previous = NULL) {
        if (version_compare(PHP_VERSION, "5.3.0") < 0) {
            parent::__construct($message, $code);
        }
        else {
            parent::__construct($message, $code, $previous);
        }
    }
}

Summary

So now you have the knowledge of what YAML is, how to represent PHP arrays in YAML, and how to integrate a PHP YAML parser into your projects. By spending little more time with YAML syntax, you will be able grasp the powerful features it offers. You may also consider exploring the Symfony 1.4 and 2 frameworks that use YAML extensively. And if you’re interested in playing with the code from this article, it’s available on GitHub. Image via Fotolia

Frequently Asked Questions (FAQs) about Using YAML in PHP Projects

What are the benefits of using YAML in PHP projects?

YAML, which stands for “YAML Ain’t Markup Language,” is a human-friendly data serialization standard that can be used in conjunction with PHP. It offers several benefits. Firstly, it’s easy to understand and write, making it a great choice for configuration files or data exchange between languages with different data structures. Secondly, it supports complex data structures, allowing for more sophisticated data representation. Lastly, it integrates seamlessly with PHP, thanks to the PECL extension for YAML.

How do I install the YAML PECL extension in PHP?

To install the YAML PECL extension, you need to use the PECL installer command in your terminal or command prompt. The command is pecl install yaml. After running this command, you should add extension=yaml.so to your php.ini file to enable the extension. Remember to restart your server after making these changes.

How can I parse a YAML file in PHP?

Parsing a YAML file in PHP is straightforward with the YAML PECL extension. You can use the yaml_parse_file() function, which takes the path to the YAML file as an argument and returns an array representing the YAML data. Here’s an example:

$data = yaml_parse_file('/path/to/yaml/file.yaml');
print_r($data);

How can I generate YAML from PHP arrays?

You can generate YAML from PHP arrays using the yaml_emit() function provided by the YAML PECL extension. This function takes a PHP array as an argument and returns a string containing the YAML representation of the array. Here’s an example:

$array = ['key' => 'value'];
$yaml = yaml_emit($array);
echo $yaml;

How can I handle errors when parsing YAML in PHP?

When parsing YAML in PHP, errors can be handled using the yaml_last_error_msg() function. This function returns a string describing the last error that occurred during parsing. Here’s an example:

$data = @yaml_parse_file('/path/to/yaml/file.yaml');
if (!$data) {
echo 'Error: ', yaml_last_error_msg();
}

Can I use YAML with Symfony?

Yes, Symfony provides a YAML component that you can use to parse and dump YAML files. The Symfony YAML component is a robust and flexible solution for dealing with YAML in PHP, and it’s a great choice if you’re already using Symfony for your project.

How can I validate YAML syntax?

There are several online tools available that can validate YAML syntax for you. These tools will check your YAML code for errors and help you debug any issues. Some popular options include YAML Lint and YAML Validator.

Can I use YAML for configuration files in PHP?

Yes, YAML is a popular choice for configuration files in PHP projects. Its human-friendly syntax makes it easy to read and write, and its support for complex data structures allows for sophisticated configuration options.

How can I convert JSON to YAML in PHP?

Converting JSON to YAML in PHP can be done in two steps. First, decode the JSON into a PHP array using json_decode(). Then, emit the array as YAML using yaml_emit(). Here’s an example:

$json = '{"key": "value"}';
$array = json_decode($json, true);
$yaml = yaml_emit($array);
echo $yaml;

How can I convert YAML to JSON in PHP?

Converting YAML to JSON in PHP can also be done in two steps. First, parse the YAML into a PHP array using yaml_parse(). Then, encode the array as JSON using json_encode(). Here’s an example:

$yaml = 'key: value';
$array = yaml_parse($yaml);
$json = json_encode($array);
echo $json;

Gayanath JayarathneGayanath Jayarathne
View Author

Gayanath is a professional PHP developer who engages in open source and freelance PHP projects. His passion on guiding newcomers into the PHP world has made him to create PHPKnowHow, a beginners PHP tutorial site. Apart from coding and writing, his time is spent on traveling and movies.

Intermediate
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week