symfony book 日本語ドキュメント

第5章 - symfonyを設定する

シンプルで使いやすくするために、symfonyは少数の規約を定義します。これらの規約は修正を行わずに標準のアプリケーションの共通要件を満たします。しかしながら、シンプルで強力な設定の一式を利用することで、symfonyとアプリケーションを連携させる方法をほとんどカスタマイズできます。これらのファイルによって、固有のパラメーターをアプリケーションに追加することもできます。

この章では設定システムがどのように機能するのかを説明します:

設定システム

目的にかかわらず、多くのWebアプリケーションは共通の機能の一式を共有しています。たとえば、セクションは一部のユーザーに制限される、もしくはページはレイアウトによってデコレート(装飾)される、もしくはバリデーションが失敗したあとでフォームがユーザーの入力で満たされるなどです。symfonyはこれらの機能をエミュレートする構造を定義するので、開発者はコンフィギュレーション設定を変更することでこれらの構造をさらに調整できます。多くの変更は1行のコードを必要としないので、たくさんのコードが背後に存在するとしても、この戦略によって多くの開発時間が節約されます。これらの情報は単独で容易に識別できる位置で維持されるので、はるかに効率的でもあります。

しかしながら、このアプローチには重大な欠点が2つあります:

これらの不都合な点を考慮にいれると、symfonyでは設定ファイルが得意なことに対してのみ設定ファイルを使うことにします。実際のところ、symfonyの設定システムに望む多くのことはつぎのとおりです:

YAMLの構文とsymfonyの規約

symfonyは設定に対して、より伝統的なINIもしくはXMLフォーマットの代わりに、デフォルトでYAMLフォーマットを利用します。YAMLはインデント(字下げ)を通して構造を示すので速く書けます。その利点と基本ルールはすでに1章で説明しました。しかしながら、YAMLファイルを書いているときにいくつかの規約を覚えておく必要があります。このセクションではもっとも有名な規約をいくつか紹介します。このトピックを完全に卒業するには、YAMLのWebサイトを訪問してください。(http://www.yaml.org/)

まず第一に、タブは使いません; 代わりに半角のスペース(ブランク)を使います。YAMLパーサーはタブを含むファイルを理解できないので、リスト5-1で示すようにスペースで行をインデントします(2つのスペースはsymfonyの規約です)。

リスト5-1 YAMLファイルはタブを禁止する

# タブは使わない
all:
-> mail:
-> -> webmaster:  webmaster@example.com

# 代わりに半角のスペースを使う
all:
  mail:
    webmaster: webmaster@example.com

パラメーターがスペースで始まるもしくは終わる文字列である場合、シングルクォート(')で値をとり囲みます。リスト5-2で示されるように、文字列のパラメーターが特別な文字を含むのであれば、その値もシングルクォートでとり囲んでください。

リスト5-2 - 非標準的な文字列はシングルクォートで閉じる

error1: This field is compulsory
error2: '  This field is compulsory  '
error3: 'Don''t leave this field blank'   # シングルクォートは二重でなければならない

特別な文字列のヘッダー(>(大なり記号)と|(縦線・パイプライン))と追加のインデントを用いることで、複数行の長い文字列と複数行の文字列も定義できます。リスト5-3はこの規約を示しています。

リスト5-3 - 複数行の長い文字列を定義する

# >(大なり記号)で導入される、折り返しスタイル
# それぞれの改行はスペースで折り返される
# YAMLがより読みやすくなる
accomplishment: >
  Mark set a major league
  home run record in 1998.

# |(縦線・パイプライン)によって導入される、リテラルスタイル
# すべての改行はカウントされる
# インデントは結果の文字列に表示されない
stats: |
  65 Home Runs
  0.278 Batting Average

値を配列として定義するには、リスト5-4で示されるように、要素を角かっこ([、])で閉じるかダッシュ(-)を用いた拡張構文を使います。

リスト5-4 - YAMLの配列構文

# 配列のための省略構文
players: [ Mark McGwire, Sammy Sosa, Ken Griffey ]

# 配列のための拡張構文
players:
  - Mark McGwire
  - Sammy Sosa
  - Ken Griffey

値を連想配列もしくはハッシュとして定義するには、波かっこ({、})で要素をとり囲み、key: valueの組のようにキーと値の間に空白文字を挿入します。リスト5-5で示されるように、すべての新しいキーに対して、インデントとキャリッジ・リターン(CR)を追加することで拡張構文も利用できます。

リスト5-5 - YAMLの連想配列構文

# 正しくない構文、スペースがコロンのあとで見つからない
mail: {webmaster:webmaster@example.com,contact:contact@example.com}

# 連想配列のための正しい省略構文
mail: { webmaster: webmaster@example.com, contact: contact@example.com }

# 連想配列のための拡張構文
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com

ブール値を追加するには、正の値に対してはon、1、もしくはtrue、負の値に対してoff、0もしくはfalseのいずれかを使います。リスト5-6では可能なブール値が示されています。

リスト5-6 - ブール値のYAML構文

true_values:   [ on, 1, true ]
false_values:  [ off, 0, false ]

リスト5-7で示されるように、YAMLファイルを読みやすくするための(ハッシュ記号の#で始まる)コメント追加や、値へのスペースの追加をためらう必要はありません。

リスト5-7 - YAMLのコメント構文と値の位置合わせ

# これはコメント行
mail:
  webmaster: webmaster@example.com
  contact:   contact@example.com
  admin:     admin@example.com   # 追加のスペースのおかげで値をわかりやすく配置できる

symfonyの設定ファイルにおいて、ハッシュ記号で始まる行(コメントとしてYAMLパーサーによって無視される)を見ることがありますが、通常の設定行のように見えます。これはsymfonyの規約です: デフォルトの設定、symfonyのコアに設置されたほかのYAMLファイルから継承されたものは、アプリケーションの設定のなかでコメント行として繰り返されます。このようなパラメーターの値を変更したい場合、リスト5-8で示されるように、行の最初をアンコメントする必要があります。

リスト5-8 - デフォルトの設定はコメントとして示される

# キャッシュはデフォルトでoff
settings:
# cache: off

# この設定を変更したい場合、最初の行をアンコメントする
settings:
  cache: on

時々symfonyはパラメーターの定義をカテゴリに分類します。任意のカテゴリのすべての設定はカテゴリのヘッダーの下でインデントされて表示されます。key: valueの一組の長いリストをカテゴリに分類してこれらを構造化することで設定の読みやすさが改善されます。カテゴリのヘッダーはドット(.)で始まります。リスト5-9ではカテゴリの例が示されています。

リスト5-9 - カテゴリのヘッダーはキーのように見えるが、ドットで始まる

all:
  .general:
    tax:        19.6

  mail:
    webmaster:  webmaster@example.com

この例では、mailがキーでgeneralはカテゴリヘッダーのみです。リスト5-10で示されるように、そのカテゴリがあたかも存在しなかったようにすべてが機能します。taxパラメーターは実際にはallキーの直接の子供です。しかしながらカテゴリーを利用することでsymfonyがallキーの真下に存在する配列を扱うための助けになります。

リスト5-10 - カテゴリヘッダーは読みやすくする目的のためだけに存在し、実際には無視される

all:
  tax:          19.6

  mail:
    webmaster:  webmaster@example.com

SIDEBAR YAMLがお好きでなければ

YAMLはPHPコードで使われる設定を定義するための単なるインターフェイスなので、YAMLで定義された設定はPHPに変換されることになります。ブラウザーでアプリケーションを見た後に、キャッシュされた設定を確認してください(たとえば、cache/frontend/dev/config/)。PHPファイルがYAML設定に対応していることがわかります。この章の後のほうで、もっと設定のキャッシュを学びます。

YAMLファイルを使いたくないのであればよいお知らせがあります。PHPもしくは別のフォーマット(XML、INI、など)を通して設定ファイルを手動で設定できます。この本全体を通して、YAMLを使わずに設定を定義する別の方法に出会い、symfonyのコンフィギュレーションハンドラーを置き換える方法も学ぶことになります(19章)。これらを賢く使えば、これらのトリックによって設定ファイルを回避するもしくは独自の設定フォーマットを定義できます。

助けてください、YAMLファイルを修正したらアプリケーションが動かなくなりました！

YAMLのファイルは解析されてPHPのハッシュと配列に変換されます。ビュー、コントローラー、もしくはモデルのふるまいを修正するために値はアプリケーションのさまざまな場所で使われます。多くの場合、YAMLのファイルに問題があるとき、値を実際に使う必要があるまで検出されません。その上、通常は投じられたエラーもしくは例外がYAMLの設定ファイルに関連しているのかどうかは明らかではありません。

設定を変更したあとでアプリケーションが突然機能を停止する場合、YAMLを記述するさいに共通の不注意な間違いをしなかったことを確認します:

設定ファイルの概要

設定は項目によってファイルに分割されます。ファイルはパラメーターの定義、もしくは設定を含みます。これらのパラメーターはいくつかのレベル(プロジェクト、アプリケーションとモジュール)でオーバーライドされます; パラメーターのなかには特定のレベル限定のものもあります。つぎの章でこれらのメイントピックに関連する設定ファイルを扱い、19章では高度な設定方法を扱います。

プロジェクトのコンフィギュレーション

デフォルトではプロジェクトの設定ファイルはわずかに存在します。myproject/config/ディレクトリのなかで見つかるファイルはつぎのとおりです:

これらのファイルはおもに外部のコンポーネントもしくはコマンドラインによって使われる、もしくはsymfonyによって読み込まれるYAMLの解析プログラムよりも先に処理される必要があります。これらのなかにYAMLフォーマットを使わないものが存在するのはそういうわけです。

アプリケーションのコンフィギュレーション

設定のメイン部分はアプリケーションの設定です。アプリケーションの設定はメインの設定のためにフロントコントローラー(web/ディレクトリ)のなかで定義されます。YAMLファイルはアプリケーションのconfig/ディレクトリ、i18n/ディレクトリ、フレームワークディレクトリに設置されます。i18n/ディレクトリは国際化のために、フレームワークファイルは見えないが役に立つ追加のアプリケーション設定のためにあります。

フロントコントローラーのコンフィギュレーション

本当に最初のアプリケーションのコンフィギュレーションは実際にはフロントコントローラー内で見つかります; これはリクエストによって実行される最初のスクリプトです。リスト5-11のデフォルトのweb/index.phpをご覧ください。

リスト5-11 - 運用環境用のデフォルトのフロントコントローラー

[php]
<?php

require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');

$configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'prod', false);
sfContext::createInstance($configuration)->dispatch();

アプリケーションの名前(frontend)と環境(prod)を定義したあとで、アプリケーションの設定はコンテキストとディスパッチングのまえに呼び出されます。ですのでアプリケーションの設定クラスのなかで利用できる便利なメソッドはわずかです:

これらの値の1つを変更したい場合、おそらく追加のフロントコントローラーが必要です。つぎの章でフロントコントローラーに関する詳細な情報と新しいフロントコントローラーを作成する方法をお伝えます。

メインアプリケーションのコンフィギュレーション

メインアプリケーションの設定はmyproject/apps/frontend/config/ディレクトリに設置されたファイルに保存されます:

国際化のコンフィギュレーション

国際化されたアプリケーションはさまざまな言語のページを表示できます。このためには特別な設定が必要です。国際化のための設定を行う場所は2ヶ所あります:

国際化機能の有効はsettings.ymlファイルで設定されることに留意してください。これらに関する詳細な情報は13章で見つかります。

アプリケーションの追加コンフィギュレーション

設定ファイルの2番目の一式はsymfonyのインストレーションディレクトリ($sf_symfony_lib_dir/config/config/)に存在し、アプリケーションの設定ディレクトリには表示されません。そこで定義された設定はほとんど修正する必要のないもしくはすべてのプロジェクトに対してグローバルであるデフォルトです。しかしながら、修正する必要がある場合、同じ名前を持つ空のファイルをmyproject/apps/frontend/configディレクトリに作り、変更したい設定をオーバーライドしてください。アプリケーションで定義された設定はフレームワークで定義された設定よりつねに優先されます。以下のものはsymfonyがインストールされたconfig/ディレクトリに存在する設定ファイルです:

モジュールのコンフィギュレーション

デフォルトでは、モジュールは特別な設定を持ちません。しかしながら、必要ならば、任意のモジュールのためにいくつかのアプリケーションレベルの設定をオーバーライドできます。たとえば、1つのモジュールのすべてのアクションのために特定のJavaScriptファイルをインクルードするためにこれを行うことでしょう。カプセル化を保持するために指定されたモジュールに制限された新しいパラメーターを追加することを選択することもできます。

ご明察のとおり、モジュール設定ファイルはmyproject/aaps/frontend/modules/mymodules/config/ディレクトリに設置しなければなりません。これらのファイルはつぎのとおりです:

モジュールのたいていの設定ファイルは、すべてのビュー、もしくは1つのモジュールのすべてのアクション、もしくはそれらの一部に対して、パラメーターを追加する機能を提供します。

SIDEBAR ファイルが多すぎるでしょうか？

アプリケーション内部に存在する設定ファイルの数に圧倒されているかもしれません。しかしながらつぎのことを念頭に置いて下さるようお願いします:

たいていの場合、デフォルトの規約が多くの共通の要件を満たすので、設定を変更する必要はありません。それぞれの設定ファイルは特定の機能に関係し、つぎの章でこれらの使いかたを一つずつ説明します。単独のファイルをとり組むとき、それが何を行い、どのように編成されているのかわかります。プロフェッショナルなWeb開発のために、しばしデフォルトの設定は完全には適用されません。設定ファイルによってsymfonyのメカニズムをコードなしで簡単に修正できます。同じ量のコントロールを実現するために必要なPHPのコード量を想像してください。すべての設定が1つのファイルに設置されたとしたら、ファイルに完全な可読性がなくなるだけでなく、いくつかのレベルで設定を再定義できなくなります(この章の後のほうにある"設定カスケード"をご覧ください)。

設定システムはsymfonyのすばらしい強みの1つです。これによって、元来対象としたWebアプリケーションだけでなく、ほかのほとんどすべてのアプリケーションに対してもsymfonyを利用できるからです。

環境

アプリケーションの開発過程で、おそらく平行していくつかの設定の一式を保有することが必要になります。たとえば、開発期間にテストのデータベースのための接続設定と、運用環境で利用できる実際のデータのための接続設定が必要になるでしょう。同時に設定する方法の需要に応えるために、symfonyは異なる環境(environment)を提供します。

環境とは何か？

アプリケーションはさまざまな環境(environment)のもとで動くことができます。異なる環境は同じPHPコード(フロントコントローラーは別)を共有しますが、、完全に異なる設定を持つことができます。それぞれのアプリケーションに対して、symfonyは3つの異なるデフォルト環境を提供します: 運用(prod)、テスト(test)、と開発(dev)です。欲しい数だけカスタム環境を追加することも自由にできます。

ですので、基本的には、環境(environment)と設定(コンフィギュレーション)(configuration)は同義語です。たとえば、test環境では警告とエラーが記録されるのに対して、prod環境ではエラーのみが記録します。キャッシュのアクセラレータはdev環境ではよく無効にされますが、testとprod環境では有効にされます。devとtest環境ではテストデータが必要になることがあります。テストデータは運用環境で使われるものとは別にデータベースに保存されます。ですので2つの環境のあいだでデータベースの設定は異なります。すべての環境は同じマシン上に同居できますが、運用サーバーは一般的にprod環境のみを含みます。

dev環境において、メンテナンスはパフォーマンスよりも重要なので、ロギングとデバッグの設定はすべて有効です。一方で、prod環境はデフォルトでパフォーマンスを最適化した設定を持つので、運用環境の設定では多くの機能をオフです。よい経験則はとり組んでいる機能に満足するまで開発環境でとり組み、運用環境に切り替えてからはスピードをチェックします。

test環境はつぎの点でdevとprod環境とは異なります。機能テストとバッチスクリプトを組むためにコマンドラインを通してのみこの環境と関わることになります。結果として、test環境は運用環境と近いですが、Webブラウザーでアクセスできません。Cookieの使用とほかのHTTP固有のコンポーネントをシミュレートします。

ブラウザーで閲覧しているアプリケーションの環境を変更するには、フロントコントローラーを変更するだけです。これまでは開発環境だけを見てきました。例で使われたURLは開発用のフロントコントローラーを呼び出していたからです:

http://localhost/frontend_dev.php/mymodule/index

しかしながら、運用環境でアプリケーションが応対する様子を見たいのであれば、運用環境用のフロントコントローラーを呼び出します:

http://localhost/index.php/mymodule/index

Webサーバーがmod_rewriteを有効にしている場合、web/.htaccessに書かれている、symfonyのカスタム書き換えルールを利用できます。これらのルールは運用環境用のフロントコントローラーをデフォルトの実行スクリプトとして定義し、つぎのようなURLを許可します:

http://localhost/mymodule/index

SIDEBAR 環境とサーバー

環境とサーバーの概念を混同しないでください。symfonyにおいて、異なる環境は異なる設定でフロントコントローラー(リクエストを実行するスクリプト)に対応します。異なるサーバーはURLの異なるドメイン名に対応します。

http://localhost/frontend_dev.php/mymodule/index
       _________ _____________
        サーバー  　環境

通常、開発者は開発サーバーのなかのアプリケーションにとり組みます。開発サーバーではインターネットから切り離され、すべてのサーバーとPHPの設定を自由に変更できます。アプリケーションを運用環境にリリースする時期が来たとき、アプリケーションのファイルを運用サーバーに転送して、エンドユーザーがアクセスできるようにします。

このことは多くの環境がそれぞれのサーバー上で利用できることを意味します。たとえば、開発サーバー上でも運用環境で運用できます。しかしながら、たいていの場合、サーバーの設定を公開することとセキュリティのリスクを避けるために、運用環境のみ運用サーバーにアクセスできます。運用システム上の開発用ではないコントローラーを誤って流出させることを避けるために、symfonyは基本的なIPチェックをこれらのコントローラーに追加します。このことによってlocalhostからのみアクセスできるようになります。削除できるこれらにアクセスできるようにしたい場合、悪意のあるユーザーはデフォルトのfrontend_dev.phpを推測して多くのデバッグ情報にアクセスできるので、これを誰でもアクセスできるようにすることのリスクを考えてください。

新しい環境を追加するには、新しいディレクトリを作るもしくはsymfonyのCLIを使う必要はありません。単に新しいフロントコントローラーを作り、環境の名前の定義を変更するだけです。この環境はすべての環境に共通の設定に加えてデフォルトのすべての設定を継承します。つぎの章でこれを行う方法を示します。

設定カスケード

同じ設定を異なった場所で、一回以上定義できます。たとえば、すべてのアプリケーションに対して、text/xml mime-typeが必要なrssモジュールのページを除いて、mime-typeのページをtext/htmlに設定することを考えます。symfonyは最初の設定をfrontend/config/view.ymlに書いて、2番目にfrontend/modules/rss/config/view.yml`に書く機能を提供します。設定システムはモジュールレベルで定義された設定はアプリケーションレベルで定義された設定をオーバーライドしなければならないことを知っています。

実際、symfonyにはいくつかの設定レベルが存在します:

カスタマイズできるすべてのプロパティのうち、多くは環境に依存します。結果として、すべての環境のための末尾の部分に加えて、多くのYAMLの設定ファイルは環境によって分割されます。よくあるsymfonyの設定はリスト5-12のようになります。

リスト5-12 - symfonyの設定ファイルの構造

# 運用環境の設定
prod:
  ...

# 開発環境の設定
dev:
  ...

# テスト環境の設定
test:
  ...

# カスタム環境の設定
myenv:
  ...

# すべての環境のための設定
all:
  ...

加えて、このフレームワーク自身は、プロジェクトのツリー構造ではなく、symfonyインストレーションの$sf_symfony_lib_dir/config/config/ディレクトリに設置されたファイルでデフォルト値を定義します。リスト5-13で示されるようにデフォルトの設定はこれらのファイルで設定されます。これらの設定はすべてのアプリケーションによって継承されます。

リスト5-13 - デフォルト設定($sf_symfony_lib_dir/config/config/settings.yml)

 # デフォルト設定:
 default:
   default_module:         default
   default_action:         index
   ...

リスト5-14で示されるように、これらのデフォルトの定義はプロジェクト、アプリケーション、モジュールの設定ファイルのなかでコメントとして繰り返されるので、いくつかのパラメーターはデフォルトで定義されこれらが修正可能であることはご存じのとおりです。

リスト5-14 - 報のために繰り返される、デフォルト設定(frontend/config/settings.yml)

#all:
#  default_module:         default
#  default_action:         index
#...

このことはプロパティは何度も定義することが可能で、実際の値は定義のカスケードから由来します。名前つきの環境のパラメーター定義はすべての環境のための同じパラメーター定義より優先され、すべての環境のための定義はデフォルトの定義より優先されます。モジュールレベルでのパラメーター定義はアプリケーションレベルでの同じパラメーター定義よりも優先されます。アプリケーションレベルでの定義はプロジェクトレベルでの定義より優先されます。これはつぎの優先順位のリストにまとめることができます:

  1. モジュール
  2. アプリケーション
  3. プロジェクト
  4. 特別な環境
  5. すべての環境
  6. デフォルト

コンフィギュレーションキャッシュ

実行時のYAMLの解析と設定カスケードの処理はそれぞれのリクエストに対する深刻なオーバーヘッドを意味します。symfonyはリクエストを迅速にするために設計された組み込みのコンフィギュレーションキャッシュのメカニズムを持ちます。

設定ファイルは、フォーマットが何であれ、ハンドラー(handler)と呼ばれる、いくつかの特別なクラスによって処理され、これらのファイルは速く処理されるPHPコードに変換されます。開発環境において、インタラクティビティを推進するために、ハンドラーはリクエストごとの変更に対して設定をチェックします。これらは最近修正されたファイルを解析するのでYAMLファイルのなかの変更を即座に確認できます。しかしながら、運用環境においては、最初のリクエストの間に処理が一回行われ、その後のリクエストのために処理すみのPHPコードはキャッシュに保存されます。運用環境においてすべてのリクエストは十分に最適化されたPHPコードを実行するので、パフォーマンスは保証されます。

たとえば、app.ymlファイルがつぎの内容を含むとします:

all:                   # すべての環境のための設定
  mail:
    webmaster:         webmaster@example.com

それから、プロジェクトのcache/フォルダーに設置された、config_app.yml.phpファイルはつぎの内容を含みます:

[php]
<?php

sfConfig::add(array(
  'app_mail_webmaster' => 'webmaster@example.com',
));

結果として、多くの場合、YAMLのファイルはsymfonyによって解析されず、代わりにコンフィギュレーションキャッシュに依存します。しかしながら、開発環境において、symfonyは体系的にYAMLファイルの修正の日付とキャッシュされたファイルを比較し、以前のリクエスト以降に変更されたファイルだけを再処理します。

このことは、運用環境でもリクエストごとに設定ファイルがコンパイルされる多くのPHPフレームワークよりも優れた強みを示しています。Javaと異なり、PHPはリクエスト間の実行コンテキストを共有しません。ほかのPHPフレームワークに関しては、XMLの設定ファイルの柔軟性を維持すると、リクエストごとにすべての設定を処理するために余分な負荷(パフォーマンスヒット)が多く必要になります。しかしながらsymfonyにはこのことがあてはまりません。キャッシュシステムのおかげで、設定によって引き起こされるオーバーヘッドはとても低いものになっています。

このメカニズムには考慮するべきことがあります。製品環境で設定を変更した場合、修正を考慮したすべての設定ファイルの再解析を強制する必要があります。そのためには、キャッシュをクリアする必要があります。キャッシュをクリアするにはcache/ディレクトリの内容を削除するか、symfonyのcache:clearタスクを呼び出します:

> php symfony cache:clear

コードから設定にアクセスする

すべてのファイルは最終的にはPHPに変換され、それらが含む多くの設定は干渉なしでフレームワークによって自動的に使われます。しかしながら、時々設定ファイルで定義されたいくつかの設定をコード(アクション、テンプレート、カスタムクラスなど)からアクセスする必要があります。settings.yml、app.yml、module.ymlとi18n.ymlのなかで定義された設定はsfConfigという名前の特別なクラスを通して利用できます。

sfConfigクラス

sfConfigクラスを通してアプリケーションのコードの範囲から設定にアクセスできます。このクラスはシンプルなゲッタークラスのメソッドを持つ、設定パラメーターのためのレジストリで、コードのすべての部分からアクセスできます:

[php]
// 設定を読みとる
$parameter = sfConfig::get('param_name', $default_value);

PHPコードの範囲から設定を定義、オーバーライドすることもできます:

[php]
// 設定を定義する
sfConfig::set('param_name', $value);

パラメーター名は、以下の順番で、アンダースコア(_)によって分割されたいくつかの要素を連結したものです:

PHPコードは実行される環境のために定義された値だけにアクセスするので、環境は含まれません。

たとえば、リスト5-15で示されるapp.ymlファイルのなかで定義される値にアクセスする必要がある場合、リスト5-16で示されているようなコードが必要です。

リスト5-15 - app.ymlの設定のサンプル

all:
  .general:
    tax:          19.6
  default_user:
    name:         John Doe
  mail:
    webmaster:    webmaster@example.com
    contact:      contact@example.com
dev:
  mail:
    webmaster:    dummy@example.com
    contact:      dummy@example.com

リスト5-16 - PHPのコードでdev環境のコンフィギュレーション設定にアクセスする

[php]
echo sfConfig::get('app_tax');   // カテゴリのヘッダーが無視されることは覚えておく
 => '19.6'
echo sfConfig::get('app_default_user_name');
 => 'John Doe'
echo sfConfig::get('app_mail_webmaster');
 => 'dummy@example.com'
echo sfConfig::get('app_mail_contact');
 => 'dummy@example.com'

すべての値を変更できるので、symfonyのコンフィギュレーション設定はPHP定数のすべての利点を持ちますが、不利な点はともないません。

このため、アプリケーションのためにsymfonyの設定を行うことができる、settings.ymlファイルはsfConfig::set()呼び出しのリストと同等です。リスト5-17はリスト5-18で示されるようなコードとして解釈されます。

リスト5-17 - settings.ymlの抜粋

all:
  .settings:
    available:              on
    path_info_array:        SERVER
    path_info_key:          PATH_INFO
    url_format:             PATH

リスト5-18 - settings.ymlを解析するときにsymfonyが行うこと

[php]
sfConfig::add(array(
  'sf_available' => true,
  'sf_path_info_array' => 'SERVER',
  'sf_path_info_key' => 'PATH_INFO',
  'sf_url_format' => 'PATH',
));

settings.ymlファイルのなかで見つかる設定の意味に関しては19章を参照してください。

アプリケーションのカスタム設定とapp.yml

アプリケーションの機能に関連する多くの設定はmyproject/apps/frontend/config/ディレクトリに設置されたapp.ymlに保存されます。このファイルは環境に依存しており、デフォルトでは空です。すべての設定は簡単に変更できます。コードからこれらの設定にアクセスするためにsfConfigクラスを使います。リスト5-19は例を示しています。

リスト5-19 - 特定のサイトに対して受理されたクレジットカードのオペレータを定義するapp.ymlのサンプル

all:
  creditcards:
    fake:             off
    visa:             on
    americanexpress:  on

dev:
  creditcards:
    fake:             on

fakeのクレジットカードが現在の環境で受理されるか知るには、つぎの値を取得します:

[php]
sfConfig::get('app_creditcards_fake');

NOTE allキーの真下でPHPの配列が必要なときカテゴリヘッダーを使うことが必要です。そうでなければ上記で示されたようにsymfonyは値を個別に利用できるようにします。

all:
  .array:
    creditcards:
      fake:             off
      visa:             on
      americanexpress:  on

[php]
print_r(sfConfig::get('app_creditcards'));

Array(
  [fake] => false
  [visa] => true
  [americanexpress] => true
)

TIP 1つのスクリプト内部で、定数もしくは設定を定義をしたくなるたびに、app.ymlファイルに設置するほうがよいのかどうかを考えてください。このファイルはすべてのアプリケーションの設定を保存するためにとても便利な場所です。

app.ymlの構文を処理するのが難しくなったカスタムパラメーターが必要なとき、独自の構文を定義することが必要になるかもしれません。その場合、設定を新しいファイルに保存することができます。この設定は新しいコンフィギュレーションハンドラーによって解釈されます。コンフィギュレーションハンドラーに関する詳しい情報に関しては19章を参照してください。

設定ファイルからより多くの情報を得るためのティップス

独自のYAMLファイルを書くまえに学ぶべきトリックがいくつかあります。これらによって設定の重複を回避し、独自のYAMLフォーマットを扱うことができます。

定数をYAML設定ファイルのなかで利用する

いくつかのコンフィギュレーション設定はほかの設定の値に依存します。同じ値を2度設定することを避けるために、symfonyはYAMLファイル形式で定数をサポートします。パーセント記号(%)で囲まれた大文字の設定名(sfConfig::get()でアクセス可能)を見てみると、コンフィギュレーションハンドラーはこれらの設定を現在の値に置き換えます。例に関しては5-20のリストをご覧ください。

リス5-20 - YAMLファイル形式で定数を使う、autoload.ymlからの例

autoload:
  symfony:
    name:           symfony
    path:           %SF_SYMFONY_LIB_DIR%
    recursive:      on
    exclude:        [vendor]

pathパラメーターはsfConfig::get('sf_symfony_lib_dir')によって返された値をとります。多の設定ファイルに依存する1つの設定ファイルが欲しい場合、あなたが依存するファイルがすでに解析されたことを確認する必要があります(解析された設定ファイルの順番を理解するにはsymfonyのソースを調べてください)。app.ymlは解析される最後のファイルの1つなので、そのファイルで別のものに依存することがあります。

スクリプトを設定に組み込む

設定が外部パラメーター(たとえばデータベース、またはほかの設定ファイル)に依存することがあります。このような特別の場合に対処するために、symfonyの設定ファイルはYAMLパーサーに渡されるまえにPHPファイルとして解析されます。このことは、リスト5-21のように、PHPコードをYAMLファイル内部に設置できることを意味します。

リスト5-21 - PHPのコードをYAMLファイルに含めることができる

all:
  translation:
    format:  <?php echo (sfConfig::get('sf_i18n') == true ? 'xliff' : 'none')."\n" ?>

しかしながら設定はリクエストのかなり初期の間に解析されるので、助けをしてくれるsymfonyの組み込みメソッドもしくは関数が存在しないことにご注意ください。

また、デフォルトでecho言語構造はCR(キャリッジ・リターン)を追加しないので、YAMLフォーマットを有効に保つために"\n"もしくはecholnヘルパーを追加する必要があります。

all:
  translation:
    format:  <?php echoln(sfConfig::get('sf_i18n') == true ? 'xliff' : 'none') ?>

CAUTION 運用環境において、設定はキャッシュされるので、設定ファイルはキャッシュがクリアされたあとで一回だけ解析されます(そして実行されます)。

独自のYAMLファイルを読み込む

YAMLファイルを直接読み込みたいときは、いつでもsfYamlクラスが使えます。このクラスはYAMLファイルをPHPの連想配列に変換できるYAMLパーサーです。リスト5-22はサンプルのYAMLファイルを表し、リスト5-23は解析方法を示しています。

リスト5-22 - test.ymlファイルのサンプル

house:
  family:
    name:     Doe
    parents:  [John, Jane]
    children: [Paul, Mark, Simone]
  address:
    number:   34
    street:   Main Street
    city:     Nowheretown
    zipcode:  12345

リスト5-23 - YAMLファイルを連想配列に変換するsfYamlクラスを使う

[php]
$test = sfYaml::load('/path/to/test.yml');
print_r($test);

Array(
  [house] => Array(
    [family] => Array(
      [name] => Doe
      [parents] => Array(
        [0] => John
        [1] => Jane
      )
      [children] => Array(
        [0] => Paul
        [1] => Mark
        [2] => Simone
      )
    )
    [address] => Array(
      [number] => 34
      [street] => Main Street
      [city] => Nowheretown
      [zipcode] => 12345
    )
  )
)

まとめ

symfonyは設定システム(configuration system)をシンプルで読みやすくするためにYAMLフォーマットを利用します。複数の環境(environment)を扱い定義のカスケードを通してパラメーターを設定する機能によって開発者は多彩なことができます。設定のなかにはsfConfigオブジェクトを通してコードの範囲内からアクセスできるものが存在します。とりわけアプリケーションの設定はapp.ymlファイルに保存されます。

もちろん、symfonyはたくさんの設定ファイルを持ちますが、このアプローチによってsymfonyはより適合性のあるものになります。アプリケーションが高度なレベルのカスタマイズを必要としないのであれば、これらの設定ファイルに悩む必要がないことを覚えておいてください。