Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Components
  4. The Yaml Component
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • What is It?
  • Installation
  • Why?
    • Fast
    • Real Parser
    • Clear Error Messages
    • Dump Support
    • Types Support
    • Full Merge Key Support
  • Using the Symfony YAML Component
    • Reading YAML Files
    • Writing YAML Files
  • Advanced Usage: Flags
    • Object Parsing and Dumping
    • Handling Invalid Types
    • Date Handling
    • Dumping Multi-line Literal Blocks
    • Parsing PHP Constants
    • Syntax Validation
  • Learn More

The Yaml Component

Edit this page

Warning: You are browsing the documentation for Symfony 3.2, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

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 serialization standard for all programming languages. YAML is a great format for your configuration files. YAML files are as expressive as XML files and as readable as INI files.

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

Tip

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

Installation

You can install the component in 2 different ways:

  • Install it via Composer (symfony/yaml on Packagist);
  • Use the official Git repository (https://github.com/symfony/yaml).

Then, require the vendor/autoload.php file to enable the autoloading mechanism provided by Composer. Otherwise, your application won't be able to find the classes of this Symfony component.

Why?

Fast

One of the goals of Symfony Yaml is to find the right balance between speed and features. 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 YAML specification, for all your configuration needs. It also means that the parser is 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 a helpful message with the filename and the line number where the problem occurred. It eases the debugging a lot.

Dump Support

It is also able to dump PHP arrays to YAML with object support, and inline level 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 repeat yourself by referencing common configuration bits.

Using the Symfony YAML Component

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

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

Reading YAML Files

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

1
2
3
use Symfony\Component\Yaml\Yaml;

$value = Yaml::parse(file_get_contents('/path/to/file.yml'));

Caution

Because it is currently possible to pass a filename to this method, you must validate the input first. Passing a filename is deprecated in Symfony 2.2, and was removed in Symfony 3.0.

If an error occurs during parsing, the parser throws a ParseException exception indicating the error type and the line in the original YAML string where the error occurred:

1
2
3
4
5
6
7
use Symfony\Component\Yaml\Exception\ParseException;

try {
    $value = Yaml::parse(file_get_contents('/path/to/file.yml'));
} catch (ParseException $e) {
    printf("Unable to parse the YAML string: %s", $e->getMessage());
}

Writing YAML Files

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

1
2
3
4
5
6
7
8
9
10
use Symfony\Component\Yaml\Yaml;

$array = array(
    'foo' => 'bar',
    'bar' => array('foo' => 'bar', 'bar' => 'baz'),
);

$yaml = Yaml::dump($array);

file_put_contents('/path/to/file.yml', $yaml);

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

Array Expansion and Inlining

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

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

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

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

Indentation

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

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

Numeric Literals

3.2

Support for parsing integers grouped by underscores was introduced in Symfony 3.2.

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

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

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

Advanced Usage: Flags

3.1

Flags were introduced in Symfony 3.1 and replaced the earlier boolean arguments.

Object Parsing and Dumping

You can dump objects by using the DUMP_OBJECT flag:

1
2
3
4
5
$object = new \stdClass();
$object->foo = 'bar';

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

And parse them by using the PARSE_OBJECT flag:

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

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

Caution

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

Handling Invalid Types

By default the parser will encode invalid types as null. You can make the parser throw exceptions by using the PARSE_EXCEPTION_ON_INVALID_TYPE flag:

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

Similarly you can use DUMP_EXCEPTION_ON_INVALID_TYPE when dumping:

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

echo $yaml; // { foo: bar }

Date Handling

By default the YAML parser will convert unquoted strings which look like a date or a date-time into a Unix timestamp; for example 2016-05-27 or 2016-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_DATETIME flag:

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

Dumping Multi-line Literal Blocks

In YAML multiple lines can be represented as literal blocks, by default the dumper will encode multiple lines as an inline string:

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

You can make it use a literal block with the DUMP_MULTI_LINE_LITERAL_BLOCK flag:

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

Parsing PHP Constants

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

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

Syntax Validation

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

First, install the Console component:

1
$ composer require symfony/console

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

1
2
3
4
5
6
7
8
9
10
// lint.php

use Symfony\Component\Console\Application;
use Symfony\Component\Yaml\Command\LintCommand;

(new Application('yaml/lint'))
    ->add(new LintCommand())
    ->getApplication()
    ->setDefaultCommand('lint:yaml', true)
    ->run();

Then, execute the script for validating contents:

1
2
3
4
5
6
7
8
# validates a single file
$ php lint.php path/to/file.yml

# or all the files in a directory
$ php lint.php path/to/directory

# or contents passed to STDIN
$ cat path/to/file.yml | 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.yml --format json

Learn More

  • The YAML Format
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    Online exam, become Sylius certified today

    Online exam, become Sylius certified today

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Cătălin Dan, a Symfony contributor

    Thanks Cătălin Dan (@dancatalin) for being a Symfony contributor

    5 commits • 109 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia