symfony book 日本語ドキュメント

第19章 - symfonyの設定ファイルをマスターする

現在あなたはsymfonyをとてもよく理解しています。すでにコアの設計を理解し、新しい隠し機能を見つけるためにコードを徹底的に調べる準備ができています。しかし、独自の要件に適用するためにsymfonyのクラスを拡張するまえに、設定ファイルをもっとよく見ることが必要です。すでに多くの機能はsymfonyに組み込まれ、設定を少し変更すれば有効になります。このことはクラスをオーバーライドしなくてもsymfonyコアのふるまいを調整できることを意味します。この章では設定ファイルとこれらの強力な機能を詳しく説明します。

symfonyの設定

myapp/config/settings.ymlファイルはおもにmyappアプリケーション用のsymfonyの設定を含みます。前の章でこのファイルから多くの設定の機能をすでに見てきましたが、再度これらを見ることにします。

5章で説明したように、このファイルは環境に依存します。すなわちそれぞれの設定が環境ごとに異なる値をとります。このファイルで定義されたそれぞれのパラメーターはsfConfigクラスを通してPHPクラスの内部からアクセスできることを覚えておいてください。パラメーター名は設定名にプレフィックスのsf_をつけたものです。たとえば、cacheパラメーターの値を取得したい場合、必要なことはsfConfig::get('sf_cache')を呼び出すだけです。

デフォルトのモジュールとアクション

ルーティングルールがmoduleパラメーターもしくはactionパラメーターを定義していない場合、代わりにsettings.ymlファイルからの値が使われます;

symfonyは特殊な状況に対してデフォルトページを用意します。ルーティングエラーの場合、symfonyはdefaultモジュールのアクションを実行します。このアクションは$sf_symfony_data_dir_modules/default/ディレクトリに保存されています。settings.ymlファイルはエラーごとに実行するアクションを定義します:

アプリケーションを運用サーバーにデプロイするまえにこれらのアクションはカスタマイズすべきです。defaultモジュールのテンプレートではページにsymfonyのロゴが含まれるからです。これらのページの1つのスクリーンショット、404エラーのページは図19-1をご覧ください。

図19-1 - デフォルトの404エラーページ

デフォルトの404エラーページ

以下の2つの方法でデフォルトのページをオーバーライドできます:

ほかの2つのページはsymfonyの見た目を有しており、運用サーバーにデプロイするまえにこれらのページをカスタマイズすることも必要です。これらのページはdefaultモジュールには存在しません。これはsymfonyが適切に動作しないときに呼び出されるからです。代わりに、これらのデフォルトページは$sf_symfony_data_dir/web/errors/ディレクトリのなかで見つかります:

これらのページをカスタマイズするには、アプリケーションのweb/errors/ディレクトリのなかでerror500.phpページとunavailable.phpページを作ります。symfonyは固有のページの代わりにこれらを使うようになります。

NOTE 必要なときにリクエストをunavailable.phpページにリダイレクトするには、アプリケーションのsettings.ymlのなかでcheck_lock設定をonにする必要があります。デフォルトではこの設定は無効です。この設定によってすべてのリクエストに対してわずかですがオーバーヘッドが追加されるからです。

オプション機能の有効

settings.ymlファイルのパラメーターのなかには有効もしくは無効にできるsymfonyのオプション機能をコントロールするものがあります。使わない機能を無効にすることでパフォーマンスが少し押し上げられるので、アプリケーションをデプロイするまえにテーブル19-1に示されている設定の一覧を見直してください。

テーブル 19-1 - settings.ymlファイルを通したオプション機能の一式

パラメーター | 説明 | デフォルト値 ----------------------- | ----- | -------------- use_database | データベースマネージャを有効にする。データベースを使わない場合はoffに切り替える。 | on use_security | セキュリティ機能を有効にする(secureアクションとクレデンシャル; 6章を参照)。デフォルトのセキュリティフィルター(sfBasicSecurityFilter)はonの場合のみ有効です。 | on use_flash | flashパラメーター機能を有効にする(6章を参照)。アクション内でset_flash()メソッドを決して使わない場合はoffに設定する。flashフィルター(sfFlashFilter)はonになっているときのみ有効。 | on i18n | インターフェイスの翻訳機能を有効にする(13章を参照)。他言語アプリケーションのためにonに設定する。 | off logging_enabled | symfonyのイベントのロギング機能を有効にする。logging.yml設定を無視してsymfonyのロギング機能を完全にoffに切り替えたいときはoffに設定する。 | on escaping_strategy | 出力エスケーピング機能の方針を有効にして定義する(7章を参照)。テンプレート内で$sf_dataコンテナを使わない場合にoffに設定する。|bc cache | テンプレートキャッシュを有効にする(12章を参照)。モジュールの1つがcache.ymlファイルを含む場合にonに設定する。キャッシュフィルター(sfCacheFilter)がonになっている場合にのみ有効 | 開発環境ではoff、運用環境ではon web_debug | 簡単なデバッグのためにWebデバッグツールバーを有効にする(16章を参照)。ツールバーをすべてのページに表示するためにonに設定する。Webデバッグフィルター(sfWebDebugFilter)がonのときのみ有効。|onは開発環境、offは運用環境 check_symfony_version | すべてのリクエストに対してsymfonyのバージョンチェックを有効にする。symfonyをアップグレードした後に自動的にキャッシュをクリアするためにonに設定する。アップグレードした後につねにキャッシュをクリアする場合はoffのままにしておく。|off check_lock | clear-cacheタスクとdisableタスクで起動するアプリケーションのロックシステムを有効にする(前のセクションを参照)。無効されたアプリケーションへのリクエストを$sf_symfony_data_dir/web/errors/unavailable.phpページにリダイレクトするにはこのパラメーターをonに設定する。 | off compressed | PHPのレスポンス圧縮機能を有効にする。PHP圧縮ハンドラー経由で出力するHTMLを圧縮するにはonにする。 | off use_process_cache | PHPアクセレータに基づいてsymfonyの最適化を有効にする。PHPアクセレータ(たとえば、APC、XCache、eAcceleratorなど)がインストールされたとき、symfonyはリクエスト間でオブジェクトと設定をメモリに保存する機能を利用する。開発環境、もしくはPHPアクセレータ最適化が必要ではない時にoffに設定する。アクセレータがインストールされていなくても、onのままにしておいてもパフォーマンスに害をなさないことを留意する | on

機能のコンフィギュレーション

symfonyは組み込み機能、たとえば、バリデーション、キャッシュ、サードパーティのモジュールなどのふるまいを変更するにはいくつかのsettings.ymlファイルのパラメーターを使います。

出力エスケーピングの設定

出力エスケーピングの設定は変数がテンプレートにアクセスする方法をコントロールします(7章を参照)。settings.ymlファイルはこの機能のために2つの設定を含みます:

ルーティングの設定

ルーティングの2つの設定(9章を参照)はsettings.ymlファイルに保存されます:

フォームバリデーションの設定

フォームバリデーションの設定はValidationヘルパーによるエラーメッセージが表示される方法をコントロールします(10章を参照)。これらのエラーは<div>に含まれ、id属性を形成するためにこれらのエラーはvalidation_error_class設定とvalidation_error_id_prefix設定をclass属性として使います。デフォルト値はform_errorとerror_for_なので、foobarという名前の入力に対してform_error()ヘルパーへの呼び出しによる属性出力はclass="form_error" id="error_for_foobar"になります。

2つの設定はそれぞれのエラーメッセージ: validation_error_prefixとvalidation_error_suffixの前後に来る文字を決定します。一度にすべてのエラーメッセージをカスタマイズするためにこれらの設定を変更できます。

キャッシュの設定

キャッシュ設定の大部分はcache.ymlファイルのなかで定義されますが。settings.ymlファイルのなかの以下の2つの設定は異なります。cacheはテンプレートキャッシュメカニズムを有効にし、etagはサーバーサイド上のEtagハンドリングを有効にします(15章を参照)。

ロギングの設定

2つのロギングの設定(16章を参照)はsettings.ymlファイルに保存されます:

アセットへのパス

settings.ymlファイルはアセットへのパスも保存します。symfonyに搭載されたアセット以外の別のバージョンのアセットを使いたい場合、これらのパス設定を変更できます:

デフォルトのヘルパー

デフォルトのヘルパーは、すべてのテンプレートに対してロードされ、standard_helpers設定で宣言されます(7章を参照)。デフォルトでは、これらはPartial、Cache、Formヘルパーグループです。アプリケーションのすべてのテンプレート内部でヘルパーグループを利用する場合、ヘルパーグループの名前をstandard_helpers設定に追加すればそれぞれのテンプレート上でuse_helper()ヘルパーを用いてヘルパーグループを宣言する煩わしい手続きを行わずにすみます。

有効なモジュール

プラグインもしくはsymfonyコアから有効にされるモジュールはenabled_modulesパラメーターで宣言されます。プラグインがモジュールを搭載する場合、enabled_modulesパラメーターで宣言されないかぎりユーザーはこのモジュールをリクエストできません。defaultモジュールはsymfonyのデフォルトページ(congratulations、page not foundページなど)を提供し、デフォルトで唯一有効なモジュールです。

文字集合

レスポンスの文字集合はアプリケーション全体の設定です。フレームワークの多くのコンポーネントで使われるからです(テンプレート、出力エスケーパ、ヘルパーなど)。定義されるcharset設定のデフォルト値はutf-8(推奨)です。

そのほかの設定

settings.ymlファイルはコアのふるまいのためにsymfonyが内部で利用するいくつかのパラメーターを含みます。リスト19-1は設定ファイルに現れるパラメーターの一覧です。

リスト19-1 - そのほかのコンフィギュレーション設定(myapp/config/settings.yml)

# symfonyのコアクラスのコメントをcore_compile.ymlファイルで定義されたものとして除去する
strip_comments:         on
# クラスがリクエストされまだロードされていないときに呼び出される関数は
# 呼び出し可能な配列を必要とする。フレームワークブリッジによって使われる
autoloading_functions:  ~
# 秒単位の、セッションのタイムアウト
timeout:                1800
# 例外の起動前のアクションの前のフォワードの最大回数
max_forwards:           5
# グローバル定数
path_info_array:        SERVER
path_info_key:          PATH_INFO
url_format:             PATH

SIDEBAR アプリケーションの設定を追加する

settings.ymlファイルはアプリケーションに対してsymfonyの設定を定義します。5章で説明したように新しいパラメーターを追加したい場合、最適の場所はmyapp/config/app.ymlファイルです。このファイルは環境にも依存しており、このファイルが定義する設定の値は設定名にプレフィックスのapp_を付け加えることでsfConfigクラスを通して利用できます。

all:
  creditcards:
    fake:             off    # app_creditcards_fake
    visa:             on     # app_creditcards_visa
    americanexpress:  on     # app_creditcards_americanexpress

プロジェクトの設定ディレクトリのなかでapp.ymlファイルを書くこともできますが、これはカスタムプロジェクト設定を定義する方法を提供します。設定カスケードはこのファイルにも適用するので、アプリケーションのapp.ymlファイルで定義された設定はプロジェクトレベルで定義された設定をオーバーライドします。

オートロード機能を拡張する

オートロード機能は2章で手短に説明しましたが、これによってコードが特定のディレクトリに設置していればクラスをrequireせずにすみます。このことは、必要なときだけ、適切な時点に必要なクラスだけをロードする作業をsymfonyに任せられることを意味します。

autoload.ymlファイルはオートロードされたクラスが保存されるパスの一覧を示します。この設定ファイルが最初に処理されたとき、symfonyはこのファイルに参照されたすべてのディレクトリを解析します。.phpの拡張子を持つファイルがこれらのディレクトリの1つのなかで見つかるたびに、このファイル内で見つかるファイルパスとクラス名がオートロードクラスの内部リストに追加されます。このリストはキャッシュ、config/config_autoload.ymlファイルに保存されます。それから、実行時に、クラスが使われたとき、symfonyはクラスのパスをこのリストのなかで探し.phpファイルを自動的にインクルードします。

オートロード機能はクラスかつ/またはインターフェイスを含むすべての.phpファイルに対して機能します。

デフォルトでは、つぎのプロジェクトディレクトリに保存されたクラスはオートロード機能からの恩恵を受けます:

autolaod.ymlファイルはアプリケーションのデフォルトの設定ディレクトリのなかには存在しません。symfonyの設定を修正したい場合、たとえばファイル構造のどこかに保存されたクラスをオートロードするには、空のautoload.ymlファイルを作り、$sf_symfony_data_dir/config/autoload.ymlファイルもしくは独自ファイルの設定をオーバーライドします。

autoload.ymlファイルはautoload:キーで始まり、symfonyがクラスを探す場所のリストを記載しなければなりません。それぞれの場所はラベルを必要とします: これによってsymfonyのエントリーをオーバーライドできます。それぞれの位置に対して、name(config_autload.yml.phpでコメントとして表示される)と絶対パス(path)を記入してください。それから、検索が再帰的(recursive)であるように定義すると、symfonyはすべてのサブディレクトリで.phpファイルを探します。また望むサブディレクトリを除外(exclude)します。リスト19-2はデフォルトで使われる場所とファイルの構文を示しています。

リスト19-2 - オートロードのデフォルト設定($sf_symfony_data_dir/config/autoload.ymlファイル)

autoload:

  # symfonyコア
  symfony:
    name:           symfony
    path:           %SF_SYMFONY_LIB_DIR%
    recursive:      on
    exclude:        [vendor]

  propel:
    name:           propel
    path:           %SF_SYMFONY_LIB_DIR%/vendor/propel
    recursive:      on

  creole:
    name:           creole
    path:           %SF_SYMFONY_LIB_DIR%/vendor/creole
    recursive:      on

  propel_addon:
    name:           propel addon
    files:
      Propel:       %SF_SYMFONY_LIB_DIR%/addon/propel/sfPropelAutoload.php

  # プラグイン
  plugins_lib:
    name:           plugins lib
    path:           %SF_PLUGINS_DIR%/*/lib
    recursive:      on

  plugins_module_lib:
    name:           plugins module lib
    path:           %SF_PLUGINS_DIR%/*/modules/*/lib
    prefix:         2
    recursive:      on

  # プロジェクト
  project:
    name:           project
    path:           %SF_LIB_DIR%
    recursive:      on
    exclude:        [model, symfony]

  project_model:
    name:           project model
    path:           %SF_MODEL_LIB_DIR%
    recursive:      on

  # アプリケーション
  application:
    name:           application
    path:           %SF_APP_LIB_DIR%
    recursive:      on

  modules:
    name:           module
    path:           %SF_APP_DIR%/modules/*/lib
    prefix:         1
    recursive:      on

ルールのパスにワイルドカードを含めることは可能で、constants.phpファイルからファイルパスのパラメーターが使えます(つぎのセクションを参照)。設定ファイルのなかでこれらのパラメーターを使う場合、これらのパラメーターは大文字で始めと終わりを%で挟まなければなりません。

独自のautoload.ymlファイルを編集すれば新しい位置がsymfonyのオートロード機能に追加されますが、このメカニズムを拡張してsymfonyのハンドラーに独自のオートロードハンドラーを追加したいことがあります。これはsettings.ymlファイルのなかのautoloading_functionパラメーターを通して実現できます。つぎのように、このパラメーターは値として呼び出し可能なクラスの配列を必要とします:

.settings:
  autoloading_functions:
    - [myToolkit, autoload]

symfonyは新しいクラスに遭遇するとき、最初に独自のオートロードシステムが試されます(そしてautoload.ymlで定義された位置が使われます)。クラスの定義が見つからない場合、クラスが見つかるまで、settings.ymlファイルからほかのオートロード機能を試します。望む数だけオートロードメカニズムを追加できます。たとえば、ほかのフレームワークコンポーネントへのブリッジを提供するためなどです(17章を参照)。

カスタムファイル構造

symfonyフレームワークは何か(コアクラスからテンプレート、プラグイン、設定、など)を探すためにパスを使うたびに、実際のパスの代わりにパス変数を使います。これらの変数を変更することで、symfonyプロジェクトのディレクトリ構造を完全に変更して、顧客のファイル構造の要件に適合させることができます。

CAUTION symfonyプロジェクトのディレクトリ構造をカスタマイズするのは可能ですが、かならずしもよいアイディアではありません。symfonyのようなフレームワークの強みの一つは。規約が尊重されることでWeb開発者が慣習を尊重して開発されたプロジェクトを見て安心できることです。独自のディレクトリ構造を利用することを決定するまえにかならずこの問題を考えてください。

基本的なファイル構造

パス変数は、アプリケーションが起動するときに含まれる、$sf_symfony_data_dir/config/constants.phpファイルのなかで定義されます。これらの変数はsfConfigオブジェクトに保存されるのでオーバーライドするのは簡単です。リスト19-3はこれらが参照するパス変数とディレクトリのリストを示しています。

リスト19-3 - デフォルトのファイル構造の変数($sf_symfony_data_dir/config/constants.php)

sf_root_dir           # myproject/
                      #   apps/
sf_app_dir            #     myapp/
sf_app_config_dir     #       config/
sf_app_i18n_dir       #       i18n/
sf_app_lib_dir        #       lib/
sf_app_module_dir     #       modules/
sf_app_template_dir   #       templates/
sf_bin_dir            #   batch/
                      #   cache/
sf_base_cache_dir     #     myapp/
sf_cache_dir          #       prod/
sf_template_cache_dir #         templates/
sf_i18n_cache_dir     #         i18n/
sf_config_cache_dir   #         config/
sf_test_cache_dir     #         test/
sf_module_cache_dir   #         modules/
sf_config_dir         #   config/
sf_data_dir           #   data/
sf_doc_dir            #   doc/
sf_lib_dir            #   lib/
sf_model_lib_dir      #     model/
sf_log_dir            #   log/
sf_test_dir           #   test/
sf_plugins_dir        #   plugins/
sf_web_dir            #   web/
sf_upload_dir         #     uploads/

重要なディレクトリへのすべてのパスは_dirで終わるパラメーターによって決定されます。あとで必要なときにパスを変更できるように、本当の(相対もしくは絶対)ファイルパスの代わりにパス変数をつねに使用してください。たとえば、ファイルをアプリケーションのuploads/ディレクトリに移動させたいとき、パスとしてSF_ROOT_DIR.'/web/uploads/'の代わりにsfConfig::get('sf_upload_dir')を使います。

ルーティングシステムがモジュールの名前($module_name)を定義するとき、モジュールのディレクトリ構造は実行時に定義されます。リスト19-4で示されるように、constants.phpファイルのなかで定義されたパス名にしたがって、ディレクトリは自動的に作成されます。

リスト19-4 - モジュールのファイル構造のデフォルトの変数

sf_app_module_dir                 # modules/
module_name                       #  mymodule/
sf_app_module_action_dir_name     #    actions/
sf_app_module_template_dir_name   #    templates/
sf_app_module_lib_dir_name        #    lib/
sf_app_module_view_dir_name       #    views/
sf_app_module_validate_dir_name   #    validate/
sf_app_module_config_dir_name     #    config/
sf_app_module_i18n_dir_name       #    i18n/

ですので、たとえば、現在のモジュールのvalidate/ディレクトリへのパスは実行時に作成されます:

[php]
sfConfig::get('sf_app_module_dir').'/'.$module_name.'/'.sfConfig::get('sf_app_module_validate_dir_name')

ファイル構造をカスタマイズする

アプリケーションを開発するさいに、顧客がすでにディレクトリ構造を定義しており、symfonyのロジックに適合させるために構造を変更する意志のない場合、おそらくデフォルトのプロジェクトファイル構造を修正する必要があります。sfConfigオブジェクトでsf_XXX_dir変数とsf_XXX_dir_name変数をオーバーライドすることで、デフォルトとはまったく異なるディレクトリ構造でsymfonyを動かすことができます。これを行う最適の場所はアプリケーションのconfig.phpファイルです。

CAUTION sfConfigオブジェクトでsf_XXX_dir変数とsf_XXX_dir_name変数をオーバーライドするには、プロジェクトではなくアプリケーションのconfig.phpを使います。プロジェクトのconfig/config.phpファイルは、sfConfigクラスがまだ存在せずconfig/constants.phpファイルがロードされていない、リクエスト期間の初期の段階でロードされます。

たとえば、すべてのアプリケーションにテンプレートのレイアウト用に1つの共通ディレクトリを共有させたい場合、sf_template_dir設定をオーバーライドするには以下の行をmyapp/config/config.phpファイルに追加します:

[php]
sfConfig::set('sf_app_template_dir', sfConfig::get('sf_root_dir').DIRECTORY_SEPARATOR.'templates');

アプリケーションのconfig.phpファイルは空ではないので、このファイルでファイル構造の定義を格納する必要がある場合、ファイルの終わりの部分でこの作業を行うように注意してください。

Web公開のrootディレクトリの修正

constants.phpファイルに組み込まれたすべてのパスはプロジェクトのrootディレクトリに依存します。このディレクトリパスはフロントコントローラー(SF_ROOT_DIR)によって定義されます。通常のrootディレクトリはweb/ディレクトリの上のレベルですが、異なる構造を利用できます。メインのディレクトリ構造が2つのディレクトリから構成される場合を考えてみます。リスト19-5で示されるように、1つのディレクトリは公開領域で、もう1つのディレクトリは非公開領域に存在します。プロジェクトを共用ホスティングサービス上でホストするときにこのコンフィギュレーションを選ぶことはよくあります。

リスト19-5 - 共用サーバーのためのカスタムディレクトリ構造の例

symfony/    # 非公開領域
  apps/
  batch/
  cache/
  ...
www/        # 公開領域
  images/
  css/
  js/
  index.php

この場合、rootディレクトリはsymfony/ディレクトリです。ですので、アプリケーションを動かすにはindex.phpフロントコントローラーはSF_ROOT_DIRをつぎのように定義する必要があるだけです:

[php]
define('SF_ROOT_DIR', dirname(__FILE__).'/../symfony');

加えて、公開領域は通常のweb/ディレクトリの代わりにwww/ディレクトリで、つぎのように、アプリケーションのconfig.phpファイルのなかで2つのファイルパスをオーバーライドしなければなりません:

[php]
sfConfig::add(array(
  'sf_web_dir'      => SF_ROOT_DIR.'/../www',
  'sf_upload_dir'   => SF_ROOT_DIR.'/../www/'.sfConfig::get('sf_upload_dir_name'),
));

symfonyのライブラリにリンクする

リスト19-6で見ることができるように、symfonyのファイルへのパスはプロジェクトのconfig.phpファイルで定義されます。

リスト19-6 - symfonyライブラリへのパス(myproject/config/config.php)

[php]
<?php

// symfonyのディレクトリ
$sf_symfony_lib_dir  = '/path/to/symfony/lib';
$sf_symfony_data_dir = '/path/to/symfony/data';

symfony init-projectタスクをコマンドラインから呼び出すとき、これらのパスは初期化されプロジェクトを作成するために使われるsymfonyの設置ディレクトリを参照します。これらはコマンドラインとMVCアーキテクチャの両方から利用されます。

このことはフレームワークファイルへのパスを変更することでsymfonyの別の設置ディレクトリに切り替えることが可能であることを意味します。

これらのパスは絶対パスですが、dirname(__FILE__)を利用することで、プロジェクト構造内部のファイルを参照しプロジェクトを設置するために選ばれたディレクトリの独立性を保つことができます。たとえば、つぎのコードのように、多くのプロジェクトがsymfonyのlib/ディレクトリをプロジェクトのlib/symfony/ディレクトリのシンボリックリンクとして設定し、data/ディレクトリに対しても同じような設定を行います:

myproject/
  lib/
    symfony/ => /path/to/symfony/lib
  data/
    symfony/ => /path/to/symfony/data

この場合、プロジェクトのconfig.phpファイルはつぎのようにsymfonyのディレクトリを定義する必要があるだけです:

[php]
$sf_symfony_lib_dir  = dirname(__FILE__).'/../lib/symfony';
$sf_symfony_data_dir = dirname(__FILE__).'/../data/symfony';

プロジェクトのlib/vendor/ディレクトリ内でsymfonyのファイルをsvn:externalsプロパティとして格納すること選んだ場合にも同じ原則があてはまります:

myproject/
  lib/
    vendor/
      svn:externals symfony http://svn.symfony-project.com/branches/1.0

この場合、config.phpファイルはつぎのようになります:

[php]
$sf_symfony_lib_dir  = dirname(__FILE__).'/../lib/vendor/symfony/lib';
$sf_symfony_data_dir = dirname(__FILE__).'/../lib/vendor/symfony/data';

TIP アプリケーションを稼働させているサーバーが異なる場合symfonyのライブラリへのパスが異なることがあります。これを有効にする1つの方法は(rsync_exclude.txtに追加することで)プロジェクトのconfig.phpファイルを同期化の対象から除外することです。ほかの方法はconfig.phpファイルの開発バージョンと運用バージョンで同じパスを保つことですが、シンボリックリンクを指し示すこれらのパスがサーバーによって変わる可能性があります。

コンフィギュレーションハンドラーを理解する

それぞれの設定ファイルはハンドラーを持ちます。コンフィギュレーションハンドラー(configuration handler)の仕事は設定カスケードを管理することと、実行時に設定ファイルを最適化して実行可能なPHPコードに変換することです。

デフォルトのコンフィギュレーションハンドラー

デフォルトのハンドラー設定は$sf_symfony_data_dir/config/config_handlers.ymlファイルに保存されます。このファイルはファイルパスにしたがってハンドラーを設定ファイルにリンクします。リスト19-7はこのファイルの内容を抜粋したものです。

リスト19-7 - $sf_symfony_data_dir/config/config_handlers.ymlファイルの抜粋

config/settings.yml:
  class:    sfDefineEnvironmentConfigHandler
  param:
    prefix: sf_

config/app.yml:
  class:    sfDefineEnvironmentConfigHandler
  param:
    prefix: app_

config/filters.yml:
  class:    sfFilterConfigHandler

modules/*/config/module.yml:
  class:    sfDefineEnvironmentConfigHandler
  param:
    prefix: mod_
    module: yes

それぞれの設定ファイルに対して(config_handlers.ymlファイルはワイルドカードを持つファイルパスでそれぞれのファイルを識別する)、ハンドラークラスはclassキーの下で指定されます。

sfDefineEnvironmentConfigHandlerクラスによって処理される設定ファイルの設定はsfConfigクラス経由でコードのなかで直接利用できるようになり、paramキーはプレフィックスの値を含みます。

設定ファイルを処理するために使われるハンドラーの追加もしくは修正ができます。たとえば、YAMLファイルの代わりにINIファイルもしくはXMLファイルを使うためです。

NOTE config_handlers.ymlファイル用のコンフィギュレーションハンドラーはsfRootConfigHandlerクラスで、あきらかに変更できません。

設定の解析方法を修正する必要がある場合、アプリケーションのcofig/フォルダー内に空のconfig_handlers.ymlファイルを作り、classキーの行を書いたクラスでオーバーライドします。

独自ハンドラーを追加する

設定ファイルを処理するハンドラーを利用することで2つの大きな利点がもたらされます:

独自のコンフィギュレーションハンドラーを書きたい場合、$sf_symfony_lib_dir/config/ディレクトリのなかでsymfonyによって使われる構造の例にしたがってください。

アプリケーションがmyMapAPIクラスを含む場合を考えてみましょう。myMapAPIクラスは地図を配信するサードパーティのサービスのためのインターフェイスを提供します。リスト19-8で示されるように、このクラスはURLとユーザー名で初期化することが必要です。

リスト19-8 - myMapAPIクラスの初期化の例

[php]
$mapApi = new myMapAPI();
$mapApi->setUrl($url);
$mapApi->setUser($user);

アプリケーションのconfig/ディレクトリ内に設置された、map.ymlという名前のカスタム設定ファイルでこれら2つのパラメーターを保存するとよいでしょう。この設定ファイルはつぎのような内容を含むことがあります:

api:
  url:  map.api.example.com
  user: foobar

これらの設定をリスト19-8と同等なコードに変換するために、コンフィギュレーションハンドラーを作成しなければなりません。それぞれのコンフィギュレーションハンドラーはsfConfigHandlerクラスを拡張しexecute()メソッドを提供しなければなりません。execute()メソッドはパラメーターとして設定ファイルへのファイルパスの配列が必要で、キャッシュファイルに書き込まれるデータを返さなければなりません。YAMLファイル用のハンドラーはsfYamlConfigHandlerクラスを拡張します。このクラスはYAMLパーサーのために追加のファシリティを提供します。map.ymlファイルに対する典型的なコンフィギュレーションハンドラーはリスト19-9で示されるように書けます。

リスト19-9 - カスタムコンフィギュレーションハンドラー(myapp/lib/myMapConfigHandler.class.php)

[php]
<?php

class myMapConfigHandler extends sfYamlConfigHandler
{
  public function execute($configFiles)
  {
    $this->initialize();

    // yamlを解析する
    $config = $this->parseYamls($configFiles);

    $data  = "<?php\n";
    $data .= "\$mapApi = new myMapAPI();\n";

    if (isset($config['api']['url'])
    {
      $data .= sprintf("\$mapApi->setUrl('%s');\n", $config['api']['url']);
    }

    if (isset($config['api']['user'])
    {
      $data .= sprintf("\$mapApi->setUser('%s');\n", $config['api']['user']);
    }

    return $data;
  }
}

symfonyがexecute()メソッドに渡す$configFiles配列はconfig/フォルダーのなかで見つかるすべてのmap.ymlファイルへのパスを格納します。parseYamls()メソッドは設定カスケードを扱います。

この新しいハンドラーをmap.ymlファイルと関連づけるには、つぎのような内容を持つconfig_handlers.yml設定ファイルを作成しなければなりません:

config/map.yml:
  class: myMapConfigHandler

NOTE クラス(class)はオートロードする(上記の例)かファイルパスがparamキーの元のfileパラメーターで指定されたファイルのなかで定義しなければなりません。

アプリケーション内部でmap.ymlファイルに基づきmyMapConfigHandlerハンドラーによって生成されたコードが必要な場合、つぎの行を呼び出してください:

[php]
include(sfConfigCache::getInstance()->checkConfig(sfConfig::get('sf_app_config_dir_name').'/map.yml'));

checkConfig()メソッドを呼び出すとき、map.yml.phpファイルがキャッシュにまだ存在しないもしくはmap.ymlファイルがキャッシュよりも新しい場合、symfonyは設定ディレクトリのなかの既存のmap.ymlファイルを探しconfig_handlers.ymlファイルで指定されたハンドラーを利用してこれらのファイルを処理します。

TIP YAMLの設定ファイル内部で環境を扱いたい場合、ハンドラーはsfYamlConfigHandlerクラスの代わりにsfDefineEnvironmentConfigHandlerクラスを拡張できます。設定を読みとるためにparseYaml()メソッドを呼び出した後に、mergeEnvironment()メソッドを呼び出します。$config = $this->mergeEnvironment($this->parseYamls ($configFiles));を呼び出すことですべての内容を1行で実現できます。

-

SIDEBAR 既存のコンフィギュレーションハンドラーを利用する

ユーザーがsfConfigクラス経由でコードから値を読みとることができるようにする必要があるだけなら、sfDefineEnvironmentConfigHandlerコンフィギュレーションハンドラークラスを利用できます。たとえば、urlとuserパラメーターをそれぞれsfConfig::get('map_url')とsfConfig::get('map_user')として利用できるようにするには、ハンドラーをつぎのように定義します:

config/map.yml:
  class: sfDefineEnvironmentConfigHandler
  param:
    prefix: map_

ほかのハンドラーによってすでに使われているプレフィックスを選ばないように気をつけてください。 既存のプレフィックスはsf_、app、とmod_です。

PHPの設定をコントロールする

アジャイル開発のルールとベストプラクティスと互換性のあるPHPの環境を保つために、symfonyはphp.ini設定ファイルのいくつかの設定を確認してオーバーライドします。これがphp.ymlファイルの目的です。リスト19-10はデフォルトのphp.ymlファイルを示します。

リスト19-10 - symfonyのためのPHPのデフォルト設定($sf_symfony_data_dir/config/php.yml)

set:
  magic_quotes_runtime:        off
  log_errors:                  on
  arg_separator.output:        |
    &amp;

check:
  zend.ze1_compatibility_mode: off

warn:
  magic_quotes_gpc:            off
  register_globals:            off
  session.auto_start:          off

このファイルの主な目的はPHPの設定がアプリケーションと互換性があることを確認するためです。運用サーバーと同様に可能なかぎり、開発サーバーの設定を確認するためにも非常に便利です。プロジェクトの最初に運用サーバーの設定を検査し、PHPの設定をプロジェクトのphp.ymlファイルに報告するのはそういうわけです。これによってプロジェクトを運用のプラットフォームにデプロイしてもいかなる互換性の問題に遭遇しないという信頼感を持って開発とテストを行うことができます。

setヘッダーのもとで定義された変数は修正されます(サーバーのphp.iniファイルでどのように定義されていても)。warnカテゴリのもとで定義された変数はすぐに修正できませんが、これが適切に設定されていなくてもsymfonyは動きます。これらの設定をオンにすることはわるい習慣として見なされているので、この場合symfonyは警告を記録します。checkカテゴリのもとで定義された変数は同じようにすぐに修正できませんが、symfonyを動かすためにこれらの変数は特定の値を持たなければなりません。ですので、この場合、php.iniファイルが正しくなければ、例外が起こります。

symfonyのプロジェクトでエラーを追跡できるようにデフォルトのphp.ymlファイルはlog_errorsディレクティブをonに設定します。セキュリティの欠陥を防ぐためにregister_globalsディレクティブをoffに設定することも推奨します。

これらの設定をsymfonyに適用したくない、もしくはmagic_quotes_gpcディレクティブとregister_globalsディレクティブをonにして警告なしでプロジェクトを動かしたい場合、 アプリケーションのconfig/ディレクトリ内でphp.ymlファイルを作り、変更したいディレクティブの値をオーバーライドしてください。

プロジェクトがPHPの追加の拡張機能を必要な場合、extensionsカテゴリのもとで指定できます。つぎのように、このカテゴリは拡張機能の名前の配列を必要とします:

extensions: [gd, mysql, mbstring]

まとめ

設定ファイル(configuration file)はsymfonyフレームワークの動作方法を大いに変更します。symfonyはコア機能とファイルの読み込みでさえも設定に依存するので、標準の専用ホストよりも多くの環境に適用できます。このすばらしい設定の柔軟性はsymfonyの主要な強さの1つです。設定ファイルのなかで学ぶべきたくさんの規約を見た初心者を怖がらせることがあるにせよ、このことによってsymfony製のアプリケーションは膨大な数のプラットフォーム、環境に対して、互換性があります。ひとたびsymfonyの設定を習得したら、あなたのアプリケーションを動かすことを拒むサーバーは存在しないでしょう。