The YAML Format
Most configuration files in symfony are in the YAML format. According to the official YAML website, YAML is "a human friendly data serialization standard for all programming languages".
YAML is a simple language that describes data. Like PHP, it has a syntax for simple types like strings, booleans, floats, or integers. But unlike PHP, it makes a difference between arrays (sequences) and hashes (mappings).
This section describes the minimum set of features you will need to use YAML as a configuration file format in symfony, although the YAML format is capable of describing much more complex nested data structures.
Scalars
The syntax for scalars is similar to the PHP syntax.
Strings
A string in YAML
'A singled-quoted string in YAML'
tip
In a single quoted string, a single quote '
must be doubled:
'A single quote '' in a single-quoted string'
"A double-quoted string in YAML\n"
Quoted styles are useful when a string starts or ends with one or more relevant spaces.
tip
The double-quoted style provides a way to express arbitrary strings, by
using \
escape sequences. It is very useful when you need to embed a
\n
or a unicode character in a string.
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:
| \/ /| |\/| | / / | | | |__
Alternatively, strings can be written with the folded style, denoted by >
,
where each line break is replaced by a space:
> This is a very long sentence that spans several lines in the YAML but which will be rendered as a string without carriage returns.
note
Notice the two spaces before each line in the previous examples. They won't appear in the resulting PHP strings.
Numbers
# an integer 12
# an octal 014
# a hexadecimal 0xC
# a float 13.4
# an exponent 1.2e+34
# 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:
2001-12-14t21:59:43.10-05:00
# simple date 2002-12-14
Collections
A YAML file is rarely used to describe a simple scalar. Most of the time, it describes a collection. A collection can be either a sequence or mapping of elements. Sequences and mappings are both converted to PHP arrays.
Sequences use a dash followed by a space (-
):
- PHP - Perl - Python
This is equivalent to the following PHP code:
array('PHP', 'Perl', 'Python');
Mappings use a colon followed by a space (:
) to mark each key/value pair:
PHP: 5.2 MySQL: 5.1 Apache: 2.2.20
which is equivalent to the following PHP code:
array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');
note
In a mapping, a key can be any valid YAML scalar.
The number of spaces between the colon and the value does not matter, as long as there is at least one:
PHP: 5.2 MySQL: 5.1 Apache: 2.2.20
YAML uses indentation with one or more spaces to describe nested collections:
"symfony 1.0": PHP: 5.0 Propel: 1.2 "symfony 1.2": PHP: 5.2 Propel: 1.3
This YAML is equivalent to the following PHP code:
array( 'symfony 1.0' => array( 'PHP' => 5.0, 'Propel' => 1.2, ), 'symfony 1.2' => array( '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 tabulations.
you can nest sequences and mappings as you like or you can nest sequences and mappings like so:
'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
([]
):
[PHP, Perl, Python]
A mapping can be written as a comma separated list of key/values within curly
braces ({}
):
{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }
You can also mix and match styles to achieve better readability:
'Chapter 1': [Introduction, Event Types] 'Chapter 2': [Introduction, Helpers]
"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 (#
):
# 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 simply ignored by the YAML parser and do not need to be indented according to the current level of nesting in a collection.
Dynamic YAML files
In symfony, a YAML file can contain PHP code that is evaluated just before the parsing occurs:
1.0: version: <?php echo file_get_contents('1.0/VERSION')."\n" ?> 1.1: version: "<?php echo file_get_contents('1.1/VERSION') ?>"
Be careful to not mess up with the indentation. Keep in mind the following simple tips when adding PHP code to a YAML file:
The
<?php ?>
statements must always start the line or be embedded in a value.If a
<?php ?>
statement ends a line, you need to explicitly output a new line ("\n").
A Full Length Example
The following example illustrates the YAML syntax explained in this section:
"symfony 1.0": end_of_maintenance: 2010-01-01 is_stable: true release_manager: "Gregoire Hubert" description: > This stable version is the right choice for projects that need to be maintained for a long period of time. latest_beta: ~ latest_minor: 1.0.20 supported_orms: [Propel] archives: { source: [zip, tgz], sandbox: [zip, tgz] } "symfony 1.2": end_of_maintenance: 2008-11-01 is_stable: true release_manager: 'Fabian Lange' description: > This stable version is the right choice if you start a new project today. latest_beta: null latest_minor: 1.2.5 supported_orms: - Propel - Doctrine archives: source: - zip - tgz sandbox: - zip - tgz
This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License license.