silverstripe-framework/thirdparty/symfony-yaml/doc/01-Usage.markdown
2012-03-09 18:13:56 +13:00

111 lines
2.9 KiB
Markdown

Using Symfony YAML
==================
The Symfony YAML library is very simple and consists of two main classes: one
to parse YAML strings (`sfYamlParser`), and the other to dump a PHP array to
a YAML string (`sfYamlDumper`).
On top of these two core classes, the main `sfYaml` class acts as a thin
wrapper and simplifies common uses.
Reading YAML Files
------------------
The `sfYamlParser::parse()` method parses a YAML string and converts it to a
PHP array:
[php]
$yaml = new sfYamlParser();
$value = $yaml->parse(file_get_contents('/path/to/file.yaml'));
If an error occurs during parsing, the parser throws an exception indicating
the error type and the line in the original YAML string where the error
occurred:
[php]
try
{
$value = $yaml->parse(file_get_contents('/path/to/file.yaml'));
}
catch (InvalidArgumentException $e)
{
// an error occurred during parsing
echo "Unable to parse the YAML string: ".$e->getMessage();
}
>**TIP**
>As the parser is reentrant, you can use the same parser object to load
>different YAML strings.
When loading a YAML file, it is sometimes better to use the `sfYaml::load()`
wrapper method:
[php]
$loader = sfYaml::load('/path/to/file.yml');
The `sfYaml::load()` static method takes a YAML string or a file containing
YAML. Internally, it calls the `sfYamlParser::parse()` method, but with some
added bonuses:
* It executes the YAML file as if it was a PHP file, so that you can embed
PHP commands in YAML files;
* When a file cannot be parsed, it automatically adds the file name to the
error message, simplifying debugging when your application is loading
several YAML files.
Writing YAML Files
------------------
The `sfYamlDumper` dumps any PHP array to its YAML representation:
[php]
$array = array('foo' => 'bar', 'bar' => array('foo' => 'bar', 'bar' => 'baz'));
$dumper = new sfYamlDumper();
$yaml = $dumper->dump($array);
file_put_contents('/path/to/file.yaml', $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 to be considered
>an alpha feature.
If you only need to dump one array, you can use the `sfYaml::dump()` static
method shortcut:
[php]
$yaml = sfYaml::dump($array, $inline);
The YAML format supports two kind of representation for arrays, the expanded
one, and the inline one. By default, the dumper uses the inline
representation:
[yml]
{ 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:
[php]
echo $dumper->dump($array, 1);
-
[yml]
foo: bar
bar: { foo: bar, bar: baz }
-
[php]
echo $dumper->dump($array, 2);
-
[yml]
foo: bar
bar:
foo: bar
bar: baz