Le format YAML

La plupart des fichiers de configuration dans symfony sont dans le format YAML. Selon le site officiel YAML, YAML est "un être humain respectueux de la sérialisation standard des données pour tous les langages de programmation".

YAML est un langage simple qui décrit les données. Comme PHP, il a une syntaxe pour les types simples comme les chaînes, les booléens, les décimaux ou les entiers. Mais contrairement à PHP, il fait une différence entre les tableaux (séries) et les hachages (mappings).

Cette section décrit l'ensemble minimum des dispositifs que vous devrez employer pour utilser YAML comme format des fichiers de configuration dans symfony, bien que le format de YAML soit capable de décrire des structures de données beaucoup plus complexes.

Les scalaires

La syntaxe des scalaires est similaire à la syntaxe PHP.

Les chaines

Une chaine en YAML

'Une chaine avec des simples guillemets en YAML'

'Une simple guillemet '' dans une chaine avec des simples guillemets'

"Une chaine avec des doubles guillemets en YAML\n"

Une chaine avec des guillemets sont utiles quand une chaîne commence ou se termine par un ou plusieurs espaces pertinents.

Lorsqu'une chaîne contient des sauts de ligne, vous pouvez utiliser le style littéral, grâce à un pipe (|), pour indiquer que la chaîne va s'étaler sur plusieurs lignes. Dans les littéraux, les nouvelles lignes sont conservées :

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

Alternativement, les chaînes peuvent être écrites avec le style plié, dénoté par >, où chaque saut de ligne est remplacé par un espace :

>
  Il s'agit d'une très longue phrase
  qui s'étend sur plusieurs lignes dans le fichier YAML
  mais qui seront rendus sous forme de chaîne 
  sans retour à la ligne.

Nombres

# un entier
12

# un octal
014

# un hexadécimal
0xC

# un décimal
13.4

# un exposant
1.2e+34

# infini
.inf

Null

Les valeur Null en YAML peut être exprimé avec null ou ~.

Booléens

Les booléens en YAML sont exprimés avec true et false.

Dates

YAML utilise le standard ISO-8601 pour exprimer les dates :

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

# une simple date
2002-12-14

Collections

Un fichier YAML est rarement utilisé pour décrire un simple scalaire. La plupart du temps, il décrit une collection. Une collection peut être soit une série ou un mapping d'élément. Les séries et les mappings sont tous les deux convertis en tableaux PHP.

Les séries utilisent le tiret suivi d'un espace (-) :

- PHP
- Perl
- Python

L'équivalent en code PHP est le suivant :

array('PHP', 'Perl', 'Python');

Les mappings utilisent les deux-points suivi d'un espace (:) pour marquer chaque paire clé/valeur :

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

Qui est équivalent au code PHP suivant :

array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');

Le nombre d'espace entre les deux-points et la valeur n'a pas d'importance, tant qu'il y en a au moins un :

PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

YAML utilise l'indentation avec un ou plusieurs espaces pour décrire les collections imbriquées :

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

Ce YAML est équivalent au code PHP suivant :

array(
  'symfony 1.0' => array(
    'PHP'    => 5.0,
    'Propel' => 1.2,
  ),
  'symfony 1.2' => array(
    'PHP'    => 5.2,
    'Propel' => 1.3,
  ),
);

Il y a une chose importante que vous devez vous rappeler lorsqu'on utilise l'indentation dans un fichier YAML : une indentation doit être faite avec un ou plusieurs espaces, mais jamais avec les tabulations.

Vous pouvez inclure des mappings dans des séries si vous le souhaitez ou vous pouvez inclure des séries dans des mapping comme ceci :

'Chapitre 1':
  - Introduction
  - Types
'Chapitre 2':
  - Introduction
  - Helpers

YAML peut aussi utiliser des styles de flux pour des collections, en utilisant des indicateurs explicites plutôt que l'identation pour dénoter le périmètre.

Une série peut être écrite comme une liste séparée par des virgules entre crochets ([]) :

[PHP, Perl, Python]

Un mapping peut être écrit comme une liste clés/valeurs séparée par des virgules au sein d'accolades ({}) :

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

Vous pouvez également mélanger les styles pour parvenir à une meilleure lisibilité :

'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 }

Commentaires

Les commentaires peuvent être ajoutés en YAML en les préfixant avec un signe dièse (#) :

# Commentaire sur une ligne
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Commentaire en fin de ligne
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

Fichiers YAML dynamiques

Dans symfony, un fichier YAML peut contenir du code PHP qui est évaluée juste avant que le parsing soit lancé :

1.0:
  version: <?php echo file_get_contents('1.0/VERSION')."\n" ?>
1.1:
  version: "<?php echo file_get_contents('1.1/VERSION') ?>"

Faites attention à ne pas casser l'indentation. Gardez à l'esprit les conseils suivants lors de l'ajout du code PHP dans un fichier YAML :

• Les déclarations <?php ?> doivent toujours commencer une ligne ou être intégré à une valeur.

• Si une déclaration <?php ?> finit une ligne, vous devez explicitement produire une nouvelle ligne ("\n").

Un long exemple complet

L'exemple suivant illustre la syntaxe YAML expliqué dans cette section :

"symfony 1.0":
  end_of_maintainance: 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_maintainance: 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