The Yaml Component

The Yaml component loads and dumps YAML files.

What is It?

The Symfony Yaml component parses YAML strings to convert them to PHP arrays.It is also able to convert PHP arrays to YAML strings.

YAML, YAML Ain't Markup Language, is a human friendly data serializationstandard for all programming languages. YAML is a great format for yourconfiguration files. YAML files are as expressive as XML files and as readableas INI files.

The Symfony Yaml Component implements a selected subset of features defined inthe YAML 1.2 version specification.

Tip

Learn more about the Yaml component in theThe YAML Format article.

Installation

  1. $ composer require symfony/yaml

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Why?

Fast

One of the goals of Symfony Yaml is to find the right balance between speed andfeatures. It supports just the needed features to handle configuration files.Notable lacking features are: document directives, multi-line quoted messages,compact block collections and multi-document files.

Real Parser

It sports a real parser and is able to parse a large subset of the YAMLspecification, for all your configuration needs. It also means that the parseris pretty robust, easy to understand, and simple enough to extend.

Clear Error Messages

Whenever you have a syntax problem with your YAML files, the library outputs ahelpful message with the filename and the line number where the problemoccurred. It eases the debugging a lot.

Dump Support

It is also able to dump PHP arrays to YAML with object support, and inlinelevel configuration for pretty outputs.

Types Support

It supports most of the YAML built-in types like dates, integers, octals,booleans, and much more…

Full Merge Key Support

Full support for references, aliases, and full merge key. Don't repeatyourself by referencing common configuration bits.

Using the Symfony YAML Component

The Symfony Yaml component consists of two main classes:one parses YAML strings (Parser), and theother dumps a PHP array to a YAML string(Dumper).

On top of these two classes, the Yaml classacts as a thin wrapper that simplifies common uses.

Reading YAML Contents

The parse() method parses a YAMLstring and converts it to a PHP array:

  1. use Symfony\Component\Yaml\Yaml;
  2.  
  3. $value = Yaml::parse("foo: bar");
  4. // $value = ['foo' => 'bar']

If an error occurs during parsing, the parser throws aParseException exceptionindicating the error type and the line in the original YAML string where theerror occurred:

  1. use Symfony\Component\Yaml\Exception\ParseException;
  2.  
  3. try {
  4.     $value = Yaml::parse('...');
  5. } catch (ParseException $exception) {
  6.     printf('Unable to parse the YAML string: %s', $exception->getMessage());
  7. }

Reading YAML Files

The parseFile() method parses the YAMLcontents of the given file path and converts them to a PHP value:

  1. use Symfony\Component\Yaml\Yaml;
  2.  
  3. $value = Yaml::parseFile('/path/to/file.yaml');

If an error occurs during parsing, the parser throws a ParseException exception.

Writing YAML Files

The dump() method dumps any PHParray to its YAML representation:

  1. use Symfony\Component\Yaml\Yaml;
  2.  
  3. $array = [
  4.     'foo' => 'bar',
  5.     'bar' => ['foo' => 'bar', 'bar' => 'baz'],
  6. ];
  7.  
  8. $yaml = Yaml::dump($array);
  9.  
  10. file_put_contents('/path/to/file.yaml', $yaml);

If an error occurs during the dump, the parser throws aDumpException exception.

Array Expansion and Inlining

The YAML format supports two kind of representation for arrays, the expandedone, and the inline one. By default, the dumper uses the expandedrepresentation:

  1. foo: bar
  2. bar:
  3.     foo: bar
  4.     bar: baz

The second argument of the dump()method customizes the level at which the output switches from the expandedrepresentation to the inline one:

  1. echo Yaml::dump($array, 1);
  1. foo: bar
  2. bar: { foo: bar, bar: baz }

  1. echo Yaml::dump($array, 2);

  1. foo: bar
  2. bar:
  3.     foo: bar
  4.     bar: baz

Indentation

By default, the YAML component will use 4 spaces for indentation. This can bechanged using the third argument as follows:

  1. // uses 8 spaces for indentation
  2. echo Yaml::dump($array, 2, 8);
  1. foo: bar
  2. bar:
  3.         foo: bar
  4.         bar: baz

Numeric Literals

Long numeric literals, being integer, float or hexadecimal, are known for theirpoor readability in code and configuration files. That's why YAML files allow toadd underscores to improve their readability:

  1. parameters:
  2.     credit_card_number: 1234_5678_9012_3456
  3.     long_number: 10_000_000_000
  4.     pi: 3.14159_26535_89793
  5.     hex_words: 0x_CAFE_F00D

During the parsing of the YAML contents, all the _ characters are removedfrom the numeric literal contents, so there is not a limit in the number ofunderscores you can include or the way you group contents.

Advanced Usage: Flags

Object Parsing and Dumping

You can dump objects by using the DUMP_OBJECT flag:

  1. $object = new \stdClass();
  2. $object->foo = 'bar';
  3.  
  4. $dumped = Yaml::dump($object, 2, 4, Yaml::DUMP_OBJECT);
  5. // !php/object 'O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}'

And parse them by using the PARSE_OBJECT flag:

  1. $parsed = Yaml::parse($dumped, Yaml::PARSE_OBJECT);
  2. var_dump(is_object($parsed)); // true
  3. echo $parsed->foo; // bar

The YAML component uses PHP's serialize() method to generate a stringrepresentation of the object.

Caution

Object serialization is specific to this implementation, other PHP YAMLparsers will likely not recognize the php/object tag and non-PHPimplementations certainly won't - use with discretion!

Parsing and Dumping Objects as Maps

You can dump objects as Yaml maps by using the DUMP_OBJECT_AS_MAP flag:

  1. $object = new \stdClass();
  2. $object->foo = 'bar';
  3.  
  4. $dumped = Yaml::dump(['data' => $object], 2, 4, Yaml::DUMP_OBJECT_AS_MAP);
  5. // $dumped = "data:\n    foo: bar"

And parse them by using the PARSE_OBJECT_FOR_MAP flag:

  1. $parsed = Yaml::parse($dumped, Yaml::PARSE_OBJECT_FOR_MAP);
  2. var_dump(is_object($parsed)); // true
  3. var_dump(is_object($parsed->data)); // true
  4. echo $parsed->data->foo; // bar

The YAML component uses PHP's (array) casting to generate a stringrepresentation of the object as a map.

Handling Invalid Types

By default, the parser will encode invalid types as null. You can make theparser throw exceptions by using the PARSE_EXCEPTION_ON_INVALID_TYPEflag:

  1. $yaml = '!php/object \'O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}\'';
  2. Yaml::parse($yaml, Yaml::PARSE_EXCEPTION_ON_INVALID_TYPE); // throws an exception

Similarly you can use DUMP_EXCEPTION_ON_INVALID_TYPE when dumping:

  1. $data = new \stdClass(); // by default objects are invalid.
  2. Yaml::dump($data, 2, 4, Yaml::DUMP_EXCEPTION_ON_INVALID_TYPE); // throws an exception

Date Handling

By default, the YAML parser will convert unquoted strings which look like adate or a date-time into a Unix timestamp; for example 2016-05-27 or2016-05-27T02:59:43.1Z (ISO-8601):

  1. Yaml::parse('2016-05-27'); // 1464307200

You can make it convert to a DateTime instance by using the PARSE_DATETIMEflag:

  1. $date = Yaml::parse('2016-05-27', Yaml::PARSE_DATETIME);
  2. var_dump(get_class($date)); // DateTime

Dumping Multi-line Literal Blocks

In YAML, multiple lines can be represented as literal blocks. By default, thedumper will encode multiple lines as an inline string:

  1. $string = ["string" => "Multiple\nLine\nString"];
  2. $yaml = Yaml::dump($string);
  3. echo $yaml; // string: "Multiple\nLine\nString"

You can make it use a literal block with the DUMP_MULTI_LINE_LITERAL_BLOCKflag:

  1. $string = ["string" => "Multiple\nLine\nString"];
  2. $yaml = Yaml::dump($string, 2, 4, Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK);
  3. echo $yaml;
  4. //  string: |
  5. //       Multiple
  6. //       Line
  7. //       String

Parsing PHP Constants

By default, the YAML parser treats the PHP constants included in the contents asregular strings. Use the PARSE_CONSTANT flag and the special !php/constsyntax to parse them as proper PHP constants:

  1. $yaml = '{ foo: PHP_INT_SIZE, bar: !php/const PHP_INT_SIZE }';
  2. $parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
  3. // $parameters = ['foo' => 'PHP_INT_SIZE', 'bar' => 8];

Parsing and Dumping of Binary Data

You can dump binary data by using the DUMP_BASE64_BINARY_DATA flag:

  1. $imageContents = file_get_contents(__DIR__.'/images/logo.png');
  2.  
  3. $dumped = Yaml::dump(['logo' => $imageContents], 2, 4, Yaml::DUMP_BASE64_BINARY_DATA);
  4. // logo: !!binary iVBORw0KGgoAAAANSUhEUgAAA6oAAADqCAY...

Binary data is automatically parsed if they include the !!binary YAML tag(there's no need to pass any flag to the Yaml parser):

  1. $dumped = 'logo: !!binary iVBORw0KGgoAAAANSUhEUgAAA6oAAADqCAY...';
  2. $parsed = Yaml::parse($dumped);
  3. $imageContents = $parsed['logo'];

Parsing and Dumping Custom Tags

In addition to the built-in support of tags like !php/const and!!binary, you can define your own custom YAML tags and parse them with thePARSE_CUSTOM_TAGS flag:

  1. $data = "!my_tag { foo: bar }";
  2. $parsed = Yaml::parse($data, Yaml::PARSE_CUSTOM_TAGS);
  3. // $parsed = Symfony\Component\Yaml\Tag\TaggedValue('my_tag', ['foo' => 'bar']);
  4. $tagName = $parsed->getTag();    // $tagName = 'my_tag'
  5. $tagValue = $parsed->getValue(); // $tagValue = ['foo' => 'bar']

If the contents to dump contain TaggedValueobjects, they are automatically transformed into YAML tags:

  1. use Symfony\Component\Yaml\Tag\TaggedValue;
  2.  
  3. $data = new TaggedValue('my_tag', ['foo' => 'bar']);
  4. $dumped = Yaml::dump($data);
  5. // $dumped = '!my_tag { foo: bar }'

Syntax Validation

The syntax of YAML contents can be validated through the CLI using theLintCommand command.

First, install the Console component:

  1. $ composer require symfony/console

Create a console application with lint:yaml as its only command:

  1. // lint.php
  2. use Symfony\Component\Console\Application;
  3. use Symfony\Component\Yaml\Command\LintCommand;
  4.  
  5. (new Application('yaml/lint'))
  6.     ->add(new LintCommand())
  7.     ->getApplication()
  8.     ->setDefaultCommand('lint:yaml', true)
  9.     ->run();

Then, execute the script for validating contents:

  1. # validates a single file
  2. $ php lint.php path/to/file.yaml
  3.  
  4. # or validates multiple files
  5. $ php lint.php path/to/file1.yaml path/to/file2.yaml
  6.  
  7. # or all the files in a directory
  8. $ php lint.php path/to/directory
  9.  
  10. # or all the files in multiple directories
  11. $ php lint.php path/to/directory1 path/to/directory2
  12.  
  13. # or contents passed to STDIN
  14. $ cat path/to/file.yaml | php lint.php

The result is written to STDOUT and uses a plain text format by default.Add the —format option to get the output in JSON format:

  1. $ php lint.php path/to/file.yaml --format json

Tip

The linting command will also report any deprecations in the checkedYAML files. This may for example be useful for recognizing deprecations ofcontents of YAML files during automated tests.

Learn More