The YAML Format
---------------

The Symfony :doc:`Yaml Component </components/yaml>` implements a selected subset
of features defined in the `YAML 1.2 version specification`_.

Scalars
~~~~~~~

The syntax for scalars is similar to the PHP syntax.

Strings
.......

Strings in YAML can be wrapped both in single and double quotes. In some cases,
they can also be unquoted:

.. code-block:: yaml

    A string in YAML

    'A single-quoted string in YAML'

    "A double-quoted string in YAML"

Quoted styles are useful when a string starts or end with one or more relevant
spaces, because unquoted strings are trimmed on both end when parsing their
contents. Quotes are required when the string contains special or reserved characters.

When using single-quoted strings, any single quote ``'`` inside its contents
must be doubled to escape it:

.. code-block:: yaml

    'A single quote '' inside a single-quoted string'

Strings containing any of the following characters must be quoted:
``: { } [ ] , & * # ? | - < > = ! % @`` Although you can use double quotes, for
these characters it is more convenient to use single quotes, which avoids having
to escape any backslash ``\``.

The double-quoted style provides a way to express arbitrary strings, by
using ``\`` to escape characters and sequences. For instance, it is very useful
when you need to embed a ``\n`` or a Unicode character in a string.

.. code-block:: yaml

    "A double-quoted string in YAML\n"

If the string contains any of the following control characters, it must be
escaped with double quotes:

``\0``, ``\x01``, ``\x02``, ``\x03``, ``\x04``, ``\x05``, ``\x06``, ``\a``,
``\b``, ``\t``, ``\n``, ``\v``, ``\f``, ``\r``, ``\x0e``, ``\x0f``, ``\x10``,
``\x11``, ``\x12``, ``\x13``, ``\x14``, ``\x15``, ``\x16``, ``\x17``, ``\x18``,
``\x19``, ``\x1a``, ``\e``, ``\x1c``, ``\x1d``, ``\x1e``, ``\x1f``, ``\N``,
``\_``, ``\L``, ``\P``

Finally, there are other cases when the strings must be quoted, no matter if
you're using single or double quotes:

* When the string is ``true`` or ``false`` (otherwise, it would be treated as a
  boolean value);
* When the string is ``null`` or ``~`` (otherwise, it would be considered as a
  ``null`` value);
* When the string looks like a number, such as integers (e.g. ``2``, ``14``, etc.),
  floats (e.g. ``2.6``, ``14.9``) and exponential numbers (e.g. ``12e7``, etc.)
  (otherwise, it would be treated as a numeric value);
* When the string looks like a date (e.g. ``2014-12-31``) (otherwise it would be
  automatically converted into a Unix timestamp).

When a string contains line breaks, you can use the literal style, indicated
by the pipe (``|``), to indicate that the string will span several lines. In
literals, newlines are preserved:

.. code-block:: yaml

    |
      \/ /| |\/| |
      / / | |  | |__

Alternatively, strings can be written with the folded style, denoted by ``>``,
where each line break is replaced by a space:

.. code-block:: yaml

    >
      This is a very long sentence
      that spans several lines in the YAML.

    # This will be parsed as follows: (notice the trailing \n)
    # "This is a very long sentence that spans several lines in the YAML.\n"

    >-
      This is a very long sentence
      that spans several lines in the YAML.

    # This will be parsed as follows: (without a trailing \n)
    # "This is a very long sentence that spans several lines in the YAML."

.. note::

    Notice the two spaces before each line in the previous examples. They
    won't appear in the resulting PHP strings.

Numbers
.......

.. code-block:: yaml

    # an integer
    12

.. code-block:: yaml

    # an octal
    0o14

.. code-block:: yaml

    # an hexadecimal
    0xC

.. code-block:: yaml

    # a float
    13.4

.. code-block:: yaml

    # an exponential number
    1.2e+34

.. code-block:: yaml

    # infinity
    .inf

Nulls
.....

Nulls in YAML can be expressed with ``null`` or ``~``.

Booleans
........

Booleans in YAML are expressed with ``true`` and ``false``.

Dates
.....

YAML uses the `ISO-8601`_ standard to express dates:

.. code-block:: yaml

    2001-12-14T21:59:43.10-05:00

.. code-block:: yaml

    # simple date
    2002-12-14

.. _yaml-format-collections:

Collections
~~~~~~~~~~~

A YAML file is rarely used to describe a simple scalar. Most of the time, it
describes a collection. YAML collections can be a sequence (indexed arrays in PHP)
or a mapping of elements (associative arrays in PHP).

Sequences use a dash followed by a space:

.. code-block:: yaml

    - PHP
    - Perl
    - Python

The previous YAML file is equivalent to the following PHP code::

    ['PHP', 'Perl', 'Python'];

Mappings use a colon followed by a space (``:`` ) to mark each key/value pair:

.. code-block:: yaml

    PHP: 5.2
    MySQL: 5.1
    Apache: 2.2.20

which is equivalent to this PHP code::

    ['PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20'];

.. note::

    In a mapping, a key can be any valid scalar.

The number of spaces between the colon and the value does not matter:

.. code-block:: yaml

    PHP:    5.2
    MySQL:  5.1
    Apache: 2.2.20

YAML uses indentation with one or more spaces to describe nested collections:

.. code-block:: yaml

    'symfony 1.0':
      PHP:    5.0
      Propel: 1.2
    'symfony 1.2':
      PHP:    5.2
      Propel: 1.3

The above YAML is equivalent to the following PHP code::

    [
        'symfony 1.0' => [
            'PHP'    => 5.0,
            'Propel' => 1.2,
        ],
        'symfony 1.2' => [
            'PHP'    => 5.2,
            'Propel' => 1.3,
        ],
    ];

There is one important thing you need to remember when using indentation in a
YAML file: *Indentation must be done with one or more spaces, but never with
tabulators*.

You can nest sequences and mappings as you like:

.. code-block:: yaml

    'Chapter 1':
      - Introduction
      - Event Types
    'Chapter 2':
      - Introduction
      - Helpers

YAML can also use flow styles for collections, using explicit indicators
rather than indentation to denote scope.

A sequence can be written as a comma separated list within square brackets
(``[]``):

.. code-block:: yaml

    [PHP, Perl, Python]

A mapping can be written as a comma separated list of key/values within curly
braces (``{}``):

.. code-block:: yaml

    { PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

You can mix and match styles to achieve a better readability:

.. code-block:: yaml

    'Chapter 1': [Introduction, Event Types]
    'Chapter 2': [Introduction, Helpers]

.. code-block:: yaml

    'symfony 1.0': { PHP: 5.0, Propel: 1.2 }
    'symfony 1.2': { PHP: 5.2, Propel: 1.3 }

Comments
~~~~~~~~

Comments can be added in YAML by prefixing them with a hash mark (``#``):

.. code-block:: yaml

    # Comment on a line
    "symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Comment at the end of a line
    "symfony 1.2": { PHP: 5.2, Propel: 1.3 }

.. note::

    Comments are ignored by the YAML parser and do not need to be indented
    according to the current level of nesting in a collection.

Explicit Typing
~~~~~~~~~~~~~~~

The YAML specification defines some tags to set the type of any data explicitly:

.. code-block:: yaml

    data:
        # this value is parsed as a string (it's not transformed into a DateTime)
        start_date: !!str 2002-12-14

        # this value is parsed as a float number (it will be 3.0 instead of 3)
        price: !!float 3

        # this value is parsed as binary data encoded in base64
        picture: !!binary |
            R0lGODlhDAAMAIQAAP//9/X
            17unp5WZmZgAAAOfn515eXv
            Pz7Y6OjuDg4J+fn5OTk6enp
            56enmleECcgggoBADs=

Symfony Specific Features
~~~~~~~~~~~~~~~~~~~~~~~~~

The Yaml component provides some additional features that are not part of the
official YAML specification but are useful in Symfony applications:

* ``!php/const`` allows to get the value of a PHP constant. This tag takes the
  fully-qualified class name of the constant as its argument:

  .. code-block:: yaml

      data:
          page_limit: !php/const App\Pagination\Paginator::PAGE_LIMIT

* ``!php/object`` allows to pass the serialized representation of a PHP
  object (created with the `serialize()`_ function), which will be deserialized
  when parsing the YAML file:

  .. code-block:: yaml

      data:
          my_object: !php/object 'O:8:"stdClass":1:{s:3:"bar";i:2;}'

* ``!php/enum`` allows to use a PHP enum case. This tag takes the fully-qualified
  class name of the enum case as its argument:

  .. code-block:: yaml

      data:
          # You can use the typed enum case...
          operator_type: !php/enum App\Operator\Enum\Type::Or
          # ... or you can also use "->value" to directly use the value of a BackedEnum case
          operator_type: !php/enum App\Operator\Enum\Type::Or->value

  This tag allows to omit the enum case and only provide the enum FQCN
  to return an array of all available enum cases:

  .. code-block:: yaml

      data:
          operator_types: !php/enum App\Operator\Enum\Type

  .. versionadded:: 7.1

    The support for using the enum FQCN without specifying a case
    was introduced in Symfony 7.1.

Unsupported YAML Features
~~~~~~~~~~~~~~~~~~~~~~~~~

The following YAML features are not supported by the Symfony Yaml component:

* Multi-documents (``---`` and ``...`` markers);
* Complex mapping keys and complex values starting with ``?``;
* Tagged values as keys;
* The following tags and types: ``!!set``, ``!!omap``, ``!!pairs``, ``!!seq``,
  ``!!bool``, ``!!int``, ``!!merge``, ``!!null``, ``!!timestamp``, ``!!value``, ``!!yaml``;
* Tags (``TAG`` directive; example: ``%TAG ! tag:example.com,2000:app/``)
  and tag references (example: ``!<tag:example.com,2000:app/foo>``);
* Using sequence-like syntax for mapping elements (example: ``{foo, bar}``; use
  ``{foo: ~, bar: ~}`` instead).

.. _`YAML 1.2 version specification`: https://yaml.org/spec/1.2/spec.html
.. _`ISO-8601`: https://www.iso.org/iso-8601-date-and-time-format.html
.. _`serialize()`: https://www.php.net/manual/en/function.serialize.php
