YAML フォーマット

symfony フレームワークにおいて、設定ファイルの大半は YAML (ヤメル) フォーマットです。YAML の公式サイトによれば、YAML は「人間が読みやすいように最適化された、すべてのプログラミング言語のための標準データシリアライゼーション」です。

YAML はデータを記述するためのシンプルな言語です。PHP のように、文字列、ブール値、浮動小数点数、整数のようなシンプルなデータ型のための構文をもちます。PHP と異なる点は、配列 (シーケンス) とハッシュ (マッピング) のあいだに違いがあることです。

YAML フォーマットは複雑な入れ子のデータ構造を記述することもできますが、この章では、symfony の設定ファイルを扱うために、YAML について最低限知る必要のある内容だけを説明します。

スカラー

スカラーの構文は PHP と似ています。

文字列

Y '

シングルクォート (') で囲まれる文字列のなかでシングルクォートを表現するには、2つ重ねなければなりません:

'

"

文字列が1つ以上の適切なスペースで始まるもしくは終わるときは、クォートスタイル (クォートで囲む方法) が便利です。

ダブルクォートスタイルはエスケープシーケンス (\) を使って任意の文字列を表す方法も提供します。文字列に \n もしくは Unicode を埋め込むことが必要なときにこのスタイルが重宝します。

文字列に改行を入れるとき、パイプ (|) によって示されるリテラルスタイルを選ぶことができます。このスタイルは複数行にわたる文字列を表し、改行は保たれます:

|

代わりの方法として、文字列を大なり記号 (>) で示される折り畳みスタイルで表すことができます。それぞれの改行はスペースに置き換わります:

&

上記の例では、それぞれの行頭にある2つのスペースに注目してください。これらのスペースは出力結果の PHP 文字列には現れません。

数字

# # # # # #

null

ヌルの値は null もしくはチルダ (~) で表されます。

ブール値

ブール値は true と false で表されます。

日付

日付の表記は ISO-8601 標準に準拠します:

2 #

コレクション

シンプルなスカラーを記述するためだけに YAML ファイルが使われることはほとんどありません。ほとんどの場合、コレクションを記述することになります。コレクションは要素のシーケンスとマッピングで構成されます。シーケンスとマッピングは両方とも PHP 配列に変換されます。

シーケンスにおいて、ダッシュ (-) の直後にスペースを入れます:

---
- PHP:
- Perl:
- Python:

上記の YAML ファイルは次の PHP コードと同じです:

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

マッピングにおいて、それぞれのキーと値のペアを表すのにコロン (:) とスペースを使います:

---
PHP:
MySQL:
Apache: 2.2.20

上記のコードは次の PHP コードと同じです:

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

マッピングではキーは有効な YAML スカラーになります。

少なくともスペースが1つ入っていれば、コロンと値のあいだのスペースの数は問いません:

---
PHP:
MySQL:
Apache: 2.2.20

入れ子のコレクションを表すには、1つもしくは複数のスペースで字下げします:

---
"symfony 1.0":
  PHP:
  Propel:
"symfony 1.2":
  PHP:
  Propel:

上記の YAML は次の PHP コードと同じです:

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

YAML ファイルのなかで字下げするときに覚えておくことが1つあります: 字下げには1つもしくは複数のスペースを使い、タブを使ってはなりません。

次のようにシーケンスとマッピングを入れ子にできます:

---
'第1章':
  - はじめに:
  - イベントの種類:
'第2章':
  - はじめに:
  - ヘルパー:

スコープを表すのに字下げよりも明確なインジケータが使われるので、フロースタイルはコレクションを表すのに便利です。

シーケンスでは、コレクションは、角かっこ ([]) で囲まれカンマで区切られたリストとして表すことができます:

---
[PHP, Perl, Python]:

マッピングでは、コレクションは、波かっこ ({}) で囲まれ、カンマで区切られたキーもしくは値として表すことができます:

{

より見やすくするために、複数のスタイルを混ぜることができます:

---
'第1章': [はじめに, イベントの種類]
'第2章': [はじめに, ヘルパー]

"

コメント

コメントを表すには、行頭にハッシュ記号 (#) をつけます:

#

コメントは YAML パーサーによって無視され、コレクションの入れ子の現在のレベルにしたがって字下げされます。

動的な YAML ファイル

symfony では、YAML のなかで PHP コードを記述することが可能で、YAML ファイルがパースされる直前に PHP コードが評価されます:

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

字下げで散らかさないようにご注意ください。YAML ファイルに PHP コードを追加するとき、次のシンプルなティップスを思い出してください:

• <?php ?> ステートメントは行で始めるもしくは値に埋め込まなければなりません。

• <?php ?> ステートメントが単一行で終わるとき、改行 (\n) を明示的に出力する必要があります。

すべての例

次の例は、このドキュメントで説明したほとんどの YAML の構文を利用しています:

"