1 |
Using Symfony YAML |
2 |
================== |
3 |
|
4 |
The Symfony YAML library is very simple and consists of two main classes: one |
5 |
to parse YAML strings (`sfYamlParser`), and the other to dump a PHP array to |
6 |
a YAML string (`sfYamlDumper`). |
7 |
|
8 |
On top of these two core classes, the main `sfYaml` class acts as a thin |
9 |
wrapper and simplifies common uses. |
10 |
|
11 |
Reading YAML Files |
12 |
------------------ |
13 |
|
14 |
The `sfYamlParser::parse()` method parses a YAML string and converts it to a |
15 |
PHP array: |
16 |
|
17 |
[php] |
18 |
$yaml = new sfYamlParser(); |
19 |
$value = $yaml->parse(file_get_contents('/path/to/file.yaml')); |
20 |
|
21 |
If an error occurs during parsing, the parser throws an exception indicating |
22 |
the error type and the line in the original YAML string where the error |
23 |
occurred: |
24 |
|
25 |
[php] |
26 |
try |
27 |
{ |
28 |
$value = $yaml->parse(file_get_contents('/path/to/file.yaml')); |
29 |
} |
30 |
catch (InvalidArgumentException $e) |
31 |
{ |
32 |
// an error occurred during parsing |
33 |
echo "Unable to parse the YAML string: ".$e->getMessage(); |
34 |
} |
35 |
|
36 |
>**TIP** |
37 |
>As the parser is reentrant, you can use the same parser object to load |
38 |
>different YAML strings. |
39 |
|
40 |
When loading a YAML file, it is sometimes better to use the `sfYaml::load()` |
41 |
wrapper method: |
42 |
|
43 |
[php] |
44 |
$loader = sfYaml::load('/path/to/file.yml'); |
45 |
|
46 |
The `sfYaml::load()` static method takes a YAML string or a file containing |
47 |
YAML. Internally, it calls the `sfYamlParser::parse()` method, but with some |
48 |
added bonuses: |
49 |
|
50 |
* It executes the YAML file as if it was a PHP file, so that you can embed |
51 |
PHP commands in YAML files; |
52 |
|
53 |
* When a file cannot be parsed, it automatically adds the file name to the |
54 |
error message, simplifying debugging when your application is loading |
55 |
several YAML files. |
56 |
|
57 |
Writing YAML Files |
58 |
------------------ |
59 |
|
60 |
The `sfYamlDumper` dumps any PHP array to its YAML representation: |
61 |
|
62 |
[php] |
63 |
$array = array('foo' => 'bar', 'bar' => array('foo' => 'bar', 'bar' => 'baz')); |
64 |
|
65 |
$dumper = new sfYamlDumper(); |
66 |
$yaml = $dumper->dump($array); |
67 |
file_put_contents('/path/to/file.yaml', $yaml); |
68 |
|
69 |
>**NOTE** |
70 |
>Of course, the Symfony YAML dumper is not able to dump resources. Also, |
71 |
>even if the dumper is able to dump PHP objects, it is to be considered |
72 |
>an alpha feature. |
73 |
|
74 |
If you only need to dump one array, you can use the `sfYaml::dump()` static |
75 |
method shortcut: |
76 |
|
77 |
[php] |
78 |
$yaml = sfYaml::dump($array, $inline); |
79 |
|
80 |
The YAML format supports two kind of representation for arrays, the expanded |
81 |
one, and the inline one. By default, the dumper uses the inline |
82 |
representation: |
83 |
|
84 |
[yml] |
85 |
{ foo: bar, bar: { foo: bar, bar: baz } } |
86 |
|
87 |
The second argument of the `dump()` method customizes the level at which the |
88 |
output switches from the expanded representation to the inline one: |
89 |
|
90 |
[php] |
91 |
echo $dumper->dump($array, 1); |
92 |
|
93 |
- |
94 |
|
95 |
[yml] |
96 |
foo: bar |
97 |
bar: { foo: bar, bar: baz } |
98 |
|
99 |
- |
100 |
|
101 |
[php] |
102 |
echo $dumper->dump($array, 2); |
103 |
|
104 |
- |
105 |
|
106 |
[yml] |
107 |
foo: bar |
108 |
bar: |
109 |
foo: bar |
110 |
bar: baz |