第5章 - symfonyを設定する

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

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

symfonyの設定はYAMLで書かれたファイルに保存されますが、つねに別のファイルフォーマットを選ぶこともできます。
設定ファイル(configuration file)はプロジェクトレベル、アプリケーションレベル、モジュールレベルでそれぞれプロジェクトのディレクトリ構造のなかに存在します。
複数のコンフィギュレーション設定の一式(セット)を定義できます。設定の一式は環境(environment)と呼ばれます。
設定ファイルで定義された値はアプリケーションのPHPコードから利用できます。
加えて、symfonyはYAMLファイルのなかでPHPコードを使うことや設定システムをはるかに柔軟なものにするしくみを公認しています。

設定システム

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

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

開発者は複雑なXMLファイルを絶え間なく書かなければならない事態に陥ります。
PHPアーキテクチャにおいて、すべてのリクエストを処理する時間がはるかに長くなります。

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

パワフルである: 設定ファイルで管理できるほとんどすべての状況は設定ファイルを利用して管理する。
シンプルである: 変更をほとんど行わずにすむので、通常のアプリケーションにおいて多くの設定を行う状況に遭遇しない。
簡単である: 開発者が読みやすく、作成と修正を簡単に行うことができる設定ファイルである。
カスタマイズ可能である: デフォルトの言語はYAMLであるが、INI、XML、開発者が望む任意のフォーマットも利用できる。
速い: 設定ファイルはアプリケーションではなく設定システムによって処理される。設定システムは設定ファイルをPHPサーバーで速く処理されるコードの塊(チャンク)にコンパイルする(まとめる)。

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 ]

YAMLファイルを読みやすくするには、リスト5-7で示されるように、(ハッシュ記号の#で始まる)コメントを追加し値にスペースを付け足すことを躊躇しないでください。

リスト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/myapp/dev/config/)。PHPファイルがYAMLの設定に対応していることがわかります。この章の後のほうで、設定のキャッシュに関して詳しく学びます。

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

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

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

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

キーとその値の間のスペースを入れ忘れていないか:
```
key1:value1      # :のあとでスペースが見つからない
```

連続したキーが同じ方法でインデントされていない:

all:
  key1:  value1
   key2: value2  # インデントのレベルがほかの連続したメンバーと同じではない
  key3:  value3

文字列の区切り文字なしで、キーもしくは値にYAMLの予約文字が存在する:

message: tell him: go way    # :(コロン)、[、](角かっこ)、{と}(中かっこ)はYAMLの予約文字
message: 'tell him: go way'  # 正しい構文

コメント行を修正している:

# key: value     # 見出しの#が原因で無視される

同じレベルで同じキーを持つ値を2回設定している:

key1: value1
key2: value2
key1: value3     # key1 は2回定義され、値は最後に定義されたものになる

設定はつねに文字列であるにもかかわらず、変換するまで、設定が特別な型をとると考える:
```
income: 12,345   # 変換するまで、これはまだ文字列
```

設定ファイルの概要

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

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

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

config.php: これはリクエストまたはコマンドで実行される一番最初のファイルです。symfonyのファイルへのパスを含み、異なる設置ディレクトリを利用するために変更できます。いくつかのdefineステートメントをこのファイルの最後に追加する場合、定数はすべてのプロジェクトのアプリケーションからアクセスできます。このファイルの高度な使いかたは19章を参照してください。
databases.yml: このファイルはデータベースへのアクセスと接続の設定を定義する(ホスト名、ログイン名、パスワード、データベース名など)。8章でより詳しく説明します。このファイルをアプリケーションレベルでオーバーライドできます。
properties.ini: このファイルは、プロジェクト名と異なるサーバーのための接続設定を含む、コマンドラインツールによって利用されるいくつかのパラメーターを保有します。このファイルを利用する機能の概要に関しては16章を参照してください。
rsync_exclude.txt: このファイルはサーバー間の同期から除外されるディレクトリを指定します。設定方法は16章で検討します。
schema.ymlとpropel.ini:これらはPropel(symfonyのORMレイヤー)によって使われるデータアクセス用の設定ファイルです。これらのファイルはPropelのライブラリとsymfonyのクラスとプロジェクトのデータを連携させるために使われます。schema.ymlはプロジェクトのリレーショナルデータモデルの記述を含みます。propel.iniは自動的に生成されるので、修正する必要はおそらくありません。もしPropelを利用しないのであれば、これらのファイルは必要ありません。8章でこれらの使いかたに関する詳細な説明を行います。

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

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

主要な部分のコンフィギュレーションはアプリケーションのコンフィギュレーションです。これはフロントコントローラー(web/ディレクトリ内)で定義されます。主要な定数はYAMLファイルでアプリケーションのconfig/ディレクトリ内に、国際化ファイルはi18n/ディレクトリに、見えないが役に立つアプリケーションの追加設定はsymfonyのファイルに設置されます。

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

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

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

[php]
<?php

define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);

require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

sfContext::getInstance()->getController()->dispatch();

アプリケーション(myapp)と環境(prod)の名前の定義をした後に、一般的な設定ファイルはディスパッチ(発送)するまえに呼び出されます。いくつかの便利な定数はここで定義されます:

SF_ROOT_DIR: プロジェクトのrootディレクトリ(通常はファイル構造を変更しないかぎり、デフォルト値のまま)
SF_APP: プロジェクトのアプリケーション名。ファイルのパスを算出するために必要です。
SF_ENVIRONMENT: 環境名(prod、dev、もしくは独自に定義したほかのプロジェクト固有の環境)は使われる予定のコンフィギュレーション設定を決定します。環境(environment)はこの章の後のほうで説明します。
SF_DEBUG: デバッグモードの有効(詳細な内容は16章を参照)

これらの値の1つを変更したい場合、おそらく追加のフロントコントローラーが必要です。つぎの章ではフロントコントローラーについてより詳しい説明と新しいものを作成する方法をお教えします。

SIDEBAR rootディレクトリはどこでも設定できます

Webのroot(symfonyプロジェクトのweb/ディレクトリ)の元に設置されたファイルとスクリプトのみが外部から利用できます。フロントコントローラーのスクリプト、画像、スタイルシートとJavaScriptファイルは公開されます。ほかのすべてのファイルはサーバーのwebディレクトリのrootの外側に存在しなければなりません。このことはこれらのファイルは任意の場所に設定できることを意味します。

プロジェクトの非公開ファイルはSF_ROOT_DIRパスからフロントコントローラーによってアクセスされます。古典的には、rootディレクトリはweb/ディレクトリの1つの上のレベルに設置されます。しかしながら、symfonyでは完全に異なる構造を選択できます。主要なディレクトリ構造が2つのディレクトリで構成され、1つのディレクトリは公開で、もう1つは非公開である状況を想像してください:
symfony/    # 公開領域
  apps/
  batch/
  cache/
  ...
www/        # 非公開領域
  images/
  css/
  js/
  index.php
この場合、rootディレクトリはsymfony/ディレクトリです。アプリケーションを動かすためにindex.phpフロントコントローラー内でSF_ROOT_DIRをつぎのように定義する必要があります:
define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony');

固有のディレクトリ構造でsymfonyを動かす方法に関する詳細な情報は19章で説明します。

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

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

app.yml: このファイルはアプリケーション固有の設定です; すなわち、アプリケーションに固有なビジネスロジックもしくはアプリケーションロジックを定義するグローバル変数で、データベースに保存する必要のないものです。税率、運賃、Eメールアドレスはこのファイルによく保存されます。デフォルトではこのファイルは空です。
config.php: このファイルはアプリケーションを起動させます。すなわち、これはアプリケーションを開始できるようにとても基本的なすべての初期化を行います。このファイル内でディレクトリ構造をカスタマイズするもしくはアプリケーション固有の定数を追加できます(詳細は19章を参照)。これはプロジェクトのconfig.phpをインクルードすることで起動します。
factories.yml: symfonyは、ビュー、リクエスト、リスポンス、セッション、などを扱う独自のクラスを定義します。代わりに独自のクラスを使いたい場合、ここでこれらを指定できます。17章で詳細な情報を提供します。
filters.yml: フィルターはすべてのリクエストに対して実行されるコードの一部です。このファイルでは処理されるフィルターを定義し、それぞれのモジュールに対してオーバーライドできます。6章でこれらの詳細について検討します。
logging.yml: このファイルはログに記録される詳細内容のレベルを定義します。これはアプリケーションの管理とデバッグの助けになります。この設定の使いかたは16章で説明します。
routing.yml: ルーティングルールがこのファイルに保存されます。ルーティングルールはわかりづらくてブックマークしにくいURLを"スマート"(smart)で明快なものに変換します。新しいアプリケーションに対して、デフォルトのルールがいくつか存在します。9章でリンクとルーティングに関するすべての説明を行います。
settings.yml: symfonyのアプリケーションの主要な設定はこのファイルで定義されます。このファイルでアプリケーションが国際化機能、デフォルトの言語、リクエストの有効期限とキャッシュにオンにするかなどを指定します。このファイル内で1行変更すれば、アプリケーションをシャットダウンできるのでメンテナンスを実行するもしくはコンポーネントの1つをアップグレードすることが可能です。共通の設定と使いかたは19章で説明します。
view.yml: デフォルトのビューの構造(レイアウトの名前、タイトル、とメタタグ; デフォルトのスタイルシートとJavaScriptファイルで、デフォルトのcontent-type、などが含まれる)がこのファイルで設定されます。このファイルはメタタグとタイトルのタグのデフォルト値も定義します。7章でこのファイルの詳細を説明します。これらの設定はそれぞれのモジュールのためにオーバーライドできます。

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

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

アプリケーションのconfig/ディレクトリのi18n.yml: このファイルは翻訳の一般的な設定を定義します。たとえば翻訳のためのデフォルトのculture、ファイル、データベース、フォーマットから翻訳文がもたらされるかどうかです。
アプリケーションのi18nディレクトリの翻訳ファイル: これらは基本的に辞書(dictionary)です。ユーザーが言語を切り替えたときにページが翻訳されたテキストを表示するようにアプリケーションのテンプレートのなかで使われるそれぞれのフレーズに対する翻訳を渡します。

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

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

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

autoload.yml: このファイルはオートロード機能の設定を含みます。カスタムクラスが指定されたディレクトリに設置されている場合、この機能のおかげでこれらのクラスをコード内でrequireを行わずにすみます。詳細は19章で説明します。
constants.php: このファイルはアプリケーションのデフォルトのファイル構造を含みます。このファイルの設定をオーバーライドするには、19章で説明されているように、アプリケーションのconfig.phpを使います。
core_compile.ymlとbootstrap_compile.yml: これらは、(bootstrap_compile.ymlで)アプリケーションを起動させ、(core_compile.ymlで)リクエストを処理するために含まれるクラスのリストです。これらのクラスは実際には(コメントなしの)最適化された1つのPHPファイルに連結されます。このPHPファイルはファイルのアクセスオペレーションを最小にすることで実行速度を加速します(置き換えられた1つのファイルはそれぞれのリクエストに対して40倍以上速くロードされます)。これはとりわけPHPアクセレータを使わない場合に便利です。最適化のテクニックは18章で説明します。
config_handlers.yml: このファイルのなかでそれぞれの設定ファイルを処理するハンドラーを追加もしくは修正できます。19章に詳細な説明があります。
php.yml: このファイルはphp.iniファイルのディレクティブが適切に定義されていることをチェックし必要な場合にこれらのディレクティブをオーバーライドできるようにします。詳細は19章を確認してください。

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

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

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

generator.yml: (scaffoldingとadministrationを利用して)データベースのテーブルに対応して生成されたモジュールに対して、このファイルはインターフェイスが列とフィールドを表示する方法と、ユーザーに提示されるインタラクション(フィルター、ソート、ボタン、など)を定義します。14章でより詳細な内容を説明します。
module.yml: このファイルはモジュールに固有なカスタムパラメーターとアクションの設定を含みます。6章で詳細を説明します。
security.yml: このファイルはアクションに対するアクセス制限を設定します。ここで登録ユーザーもしくは特別なパーミッションを持つ登録ユーザーの一部のみがページを閲覧できるように指定することができます。6章に詳細な説明があります。
view.yml: このファイルはモジュールのアクションの1つもしくはすべてのビューのための設定を含みます。このファイルはアプリケーションのview.ymlをオーバーライドします。7章で説明します。
データのバリデーションファイル: config/ディレクトリの代わりにvalidate/ディレクトリに設置されていますが、フォームに入力されたデータをコントロールするために使われる、YAMLデータのバリデーションファイルは、モジュールの設定ファイルでもあります。これらの使いかたは10章で学ぶことになります。

モジュールのたいていの設定ファイルは、すべてのビュー、もしくは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環境とは異なります。機能テストとバッチスクリプトを組むためにコマンドラインを通してのみこの環境と関わることになります。結果として、テスト環境は運用環境と近いですが、Webブラウザーでアクセスできません。Cookieの使用とほかのHTTP固有のコンポーネントをシミュレートします。

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

http://localhost/myapp_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/myapp_dev.php/mymodule/index
       _________ _____________
        サーバー  　環境
通常、開発者は開発サーバーのなかのアプリケーションにとり組みます。開発サーバーではインターネットから切り離され、すべてのサーバーとPHPの設定を自由に変更できます。アプリケーションを運用環境にリリースする時期が来たとき、アプリケーションのファイルを運用サーバーに転送して、エンドユーザーがアクセスできるようにします。

このことはそれぞれのサーバー上で多くの環境が利用可能であることを意味します。たとえば、開発サーバーで運用環境を運用することさえ可能です。しかしながら、サーバーの設定の公開とセキュリティのリスクを避けるために、たいていの場合、運用環境は運用サーバーのみでアクセスできるようにすべきです。

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

設定カスケード

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

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

粒度のレベル:
- フレームワーク内に設置されたデフォルトの設定
- プロジェクト全体のためのグローバル設定(myproject/config/)
- プロジェクトのアプリケーションのためのローカルの設定(myproject/apps/myapp/config/)
- モジュールに制限されたローカルの設定(myproject/apps/myapp/modules/mymodule/config/)
環境レベル:
- ある環境に固有
- すべての環境用

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

実行時の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のclear-cacheタスクを呼び出します:

> symfony clear-cache

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

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

sfConfigクラス

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

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

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

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

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

設定ファイル名に関連するプレフィックス(sf_はsettings.yml、app_はapp.yml、mod_はmodule.yml、sf_i18n_はi18n.yml、sf_logging_はlogging.yml)
親キーは小文字(定義されている場合)
キーの名前は小文字

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

アプリケーションの機能に関連する多くの設定はapp.ymlに保存されます。このファイルはmyproject/apps/myapp/config/ディレクトリのなかに設置されます。このファイルは環境に依存しており、デフォルトでは空です。すべての設定は簡単に変更できます。PHPコードからこれらの設定にアクセスするには、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')によって返された値をとります。別の設定ファイルに依存する設定ファイルが欲しい場合、依存されるファイルがすでに解析されたことを確認する必要があります(解析された設定ファイルの順番を理解するには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はより適合性のあるものになります。アプリケーションが高度なレベルのカスタマイズを必要としないのであれば、これらの設定ファイルに悩む必要がないことを覚えておいてください。