YAML フォーマット

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

YAML はデータを記述するためのシンプルな軽量マークアップ言語です。文字列、ブール値、浮動小数点数、整数のような単純なデータ型をあらわすための構文は PHP と似ています。PHP と異なる構文は配列 (シーケンス) とハッシュ (マッピング) です。

複雑なネストのデータ構造も YAML であらわすことができますが、この章では、symfony の設定ファイルを扱うために、YAML について知っておかなければならない最小限の知識を説明します。

スカラー

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

文字列

文字列はシングルクォートかダブルクォートで囲みます。

'シングルクォートで囲まれた文字'

'シングルクォートで囲まれた文字列のなかでのシングルクォート '' '

文字列が1つ以上の適切なスペースではじまるもしくは終わる場合には、クォートスタイル (クォートで囲む方法) が適しています。

"ダブルクォートで囲まれた文字列\n"

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

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

ほかにも、大なり記号 (>) で示される折り畳みスタイルを選ぶことができます。それぞれの改行はスペースに置き換わります。

>
  これはとても長いセンテンスで
  YAML において数行にわたりますが、
  改行コードは追加されず
  文字列としてレンダリングされます。

数字

# 整数
12

# 8進数
014

# 16進数
0xC

# 浮動小数点数
13.4

# 指数
1.2e+34

# 無限大
.inf

null

ヌル (ナル) の値は null もしくはチルダ (~) であらわします。

ブール値

ブール値は true と false であらわします。

日付

日付のフォーマットは ISO-8601 標準に準拠します。

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

# 単純な日付
2002-12-14

コレクション

単純なスカラーをあらわすためだけに YAML ファイルを使うことはめったにありません。ほとんどの場合、コレクションをあらわすことになります。コレクションはシーケンスとマッピングのどちらかの要素になります。シーケンスとマッピングは両方とも PHP 配列に変換されます。

シーケンスでは、ダッシュ (-) の直後にスペースを入れます。

- PHP
- Perl
- Python

上記の YAML コードは次の PHP コードと同等です。

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

マッピングでは、キーと値のペアをあらわすのにコロン (:) とスペースを使います。

PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

上記の YAML コードは次の PHP コードと同等です。

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

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

PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

ネストのコレクションをあらわすには、1つもしくは複数のスペースでインデントを入れます。

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

上記の 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]

マッピングスタイルでは、コレクションは、波かっこ ({}) で囲まれ、カンマで区切られたキーもしくは値としてあらわされます。

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

見やすくするために、複数のスタイルを組み合わせることができます。

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

"symfony 1.0": { PHP: 5.0, Propel: 1.2 }
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

コメント

文字列の行頭をハッシュ記号 (#) にすればコメントになります。

# 行コメント
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # 行末のコメント
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

動的な YAML ファイル

symfony のプロジェクトでは、YAML ファイルのなかで PHP コードを書くことが可能です。PHP コードが評価されるタイミングは YAML ファイルがパースされる直前です。

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 構文を利用しています。

"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