Skip to content

Advanced YAML component usage #6582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 21, 2016
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 58 additions & 9 deletions components/yaml/introduction.rst
Original file line number Diff line number Diff line change
Expand Up @@ -169,12 +169,6 @@ array to its YAML representation:

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

.. note::

Of course, the Symfony Yaml dumper is not able to dump resources. Also,
even if the dumper is able to dump PHP objects, it is considered to be a
not supported feature.

If an error occurs during the dump, the parser throws a
:class:`Symfony\\Component\\Yaml\\Exception\\DumpException` exception.

Expand All @@ -185,7 +179,10 @@ If you only need to dump one array, you can use the

use Symfony\Component\Yaml\Yaml;

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

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 inline
Expand All @@ -201,7 +198,7 @@ representation to the inline one:

.. code-block:: php

echo $dumper->dump($array, 1);
echo Yaml::dump($array, 1);

.. code-block:: yaml

Expand All @@ -210,7 +207,7 @@ representation to the inline one:

.. code-block:: php

echo $dumper->dump($array, 2);
echo Yaml::dump($array, 2);

.. code-block:: yaml

Expand All @@ -219,6 +216,58 @@ representation to the inline one:
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::

// use 8 spaces for indentation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's be less radical and use the 2 spaces indentation. This is closer to reality (Drupal for instance uses 2 spaces in Yaml).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well it also helps to distringuish from the 2 which is used as the inline level.

echo Yaml::dump($array, 2, 8);

.. code-block:: yaml

foo: bar
bar:
foo: bar
bar: baz

Invalid Types and Object Serialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default the YAML component will encode any "unsupported" type (i.e.
resources and objects) as ``null``.

Instead of encoding as ``null`` you can choose to throw an exception if an invalid
type is encountered in either the dumper or parser as follows::

// throw an exception if a resource or object is encoutered
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

encountered

Yaml::dump($data, 2, 4, true);

// throw an exception if an encoded object is found in the YAML string
Yaml::parse($yaml, true);

However, you can activate object support using the next argument::

$object = new \stdClass();
$object->foo = 'bar';

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

$parsed = Yaml::parse($dumped, false, true);
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.

.. warning::

Object seialization is specific to this implementation, other PHP YAML
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: "serialization"

parsers will likely not recognize the ``php/object`` tag and non-PHP
implementations certainly won't - use with discretion!

.. _YAML: http://yaml.org/
.. _Packagist: https://packagist.org/packages/symfony/yaml
.. _`YAML 1.2 version specification`: http://yaml.org/spec/1.2/spec.html