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

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

symfonyの設定

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

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

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

Symfony provides default pages for special situations. In the case of a routing error, symfony executes an action of the default module, which is stored in the sfConfig::get('sf_symfony_lib_dir')/controller/default/ directory. The settings.yml file defines which action is executed depending on the error:

• error_404_moduleとerror_404_action: ユーザによって入力されたURLがどのrouteにもマッチしないもしくはsfError404Exceptionが起動するときに呼び出されるアクションです。デフォルト値はdefault/error404です。
• login_moduleとlogin_action: security.ymlファイルの中でsecureと定義されたページに認証されていないユーザがアクセスしようとするときに呼び出されるアクション(詳細は6章を参照)。デフォルト値はdefault/loginです。
• secure_moduleとsecure_action: ユーザがアクションから求められるクレデンシャルを持たないときに呼び出されるアクションです。デフォルト値はdefault/secureです。
• module_disabled_moduleとmodule_disabled_action: ユーザがmodule.ymlファイルの中で無効と宣言されたモジュールをリクエストしたときに呼び出されるアクション。デフォルト値はdefault/disabledです。

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

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

以下の2つの方法でデフォルトのページを上書きできます:

• アプリケーションのmodules/ディレクトリ内で独自のデフォルトモジュールを作成し、settings.ymlファイルで定義されたすべてのアクション(index、error404、login、secure、disabled)と関連したテンプレート(indexSuccess.php、error404Success.php、loginSuccess.php、 secureSuccess.php、disabledSuccess.php)を上書きします。
• アプリケーションのページを使うためにsettings.ymlファイルのデフォルトのモジュールとアクションの設定を変更できます。

Two other pages bear a symfony look and feel, and they also need to be customized before deployment to production. These pages are not in the default module, because they are called when symfony cannot run properly. Instead, you will find these default pages in the sfConfig::get('sf_symfony_lib_dir')/exception/data/ directory:

• error.html.php: 本番環境で内部のサーバエラーが起きるときに呼び出されるページ。他の環境(debugがtrueに設定されている)においてエラーが起きるとき、symfonyはすべての実行スタックと明快なエラーメッセージを表示します(詳細は16章を参照)。
• unavailable.php: アプリケーションが(disableタスクで)無効にされている間にユーザがページをリクエストしたときに呼び出されるページ。このページはキャッシュがクリアされている間も呼び出されます(すなわち、php symfony cache:clearタスクの呼び出しとこのタスクの終了時の間)。とても大きなキャッシュを持つシステム上では、キャッシュのクリア処理は数秒かかる可能性があります。symfonyは部分的にクリアしたキャッシュでリクエストを実行できないので、処理が終わる前に受理されたリクエストはこのページにリダイレクトされます。

これらのページをカスタマイズするためには、プロジェクトもしくはアプリケーションのconfig/ディレクトリの中でerror/error.html.phpページとunavailable.phpページを作ります。symfonyは固有のページの代わりにこれらのテンプレートを使用するようになります。

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

オプション機能の有効

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

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

Parameter	Description	Default Value
use_database	Enables the database manager. Set it to off if you don't use a database.	on
i18n	Enables interface translation (see Chapter 13). Set it to on for multilingual applications.	off
logging_enabled	Enables logging of symfony events. Set it to off when you want to turn symfony logging off completely.	on
escaping_strategy	Enables the output escaping feature (see Chapter 7). Set it to on if you want data passed to your templates to be escaped.	off
cache	Enables template caching (see Chapter 12). Set it to on if one of your modules includes cache.yml file. The cache filter (sfCacheFilter) is enabled only if it is on.	off in development, on in production
web_debug	Enables the web debug toolbar for easy debugging (see Chapter 16). Set it to on to display the toolbar on every page.	on in development, off in production
check_symfony_version	Enables the check of the symfony version for every request. Set it to on for automatic cache clearing after a framework upgrade. Leave it set to off if you always clear the cache after an upgrade.	off
check_lock	Enables the application lock system, triggered by the cache:clear and project:disable tasks (see the previous section). Set it to on to have all requests to disabled applications redirected to the sfConfig::get('sf_symfony_lib_dir')/exception/data/unavailable.php page.	off
compressed	Enables PHP response compression. Set it to on to compress the outgoing HTML via the PHP compression handler.	off

機能の構成

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

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

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

• escaping_strategy設定はonもしくはoffの値を取ることができます。
• escaping_method設定はESC_RAW、ESC_SPECIALCHARS、 ESC_ENTITIES、ESC_JS、もしくはESC_JS_NO_ENTITIESの値に設定できます。

ルーティングの設定

ルーティングの設定(9章を参照)はfactories.ymlファイルの中のroutingキーの下で定義されます。リスト19-1はルーティングのデフォルト構成を示しています。

リスト19-1 - frontend/config/factories.ymlファイルの中の、ルーティング構成の設定

routing:
  class: sfPatternRouting
  param:
    load_configuration: true
    suffix:             .
    default_module:     default
    default_action:     index
    variable_prefixes:  [':']
    segment_separators: ['/', '.']
    variable_regex:     '[\w\d_]+'
    debug:              %SF_DEBUG%
    logging:            %SF_LOGGING_ENABLED%
    cache:
      class: sfFileCache
      param:
        automatic_cleaning_factor: 0
        cache_dir:                 %SF_CONFIG_CACHE_DIR%/routing
        lifetime:                  31556926
        prefix:                    %SF_APP_DIR%

• suffixパラメータは生成されたURLのためにデフォルトの接尾辞を設定します。デフォルトの値はピリオド(.)で、どの接尾辞にも一致しません。例えば、すべての生成されたURLが静的なページに見えるように.htmlに設定します。
• ルーティングルールがmoduleパラメータもしくはactionパラメータを定義しないとき、代わりにfactories.ymlファイルからの値が使用されます:
  • default_module: デフォルトのmoduleリクエストパラメータ。デフォルトはdefaultモジュール。
  • default_action: デフォルトのactionリクエストパラメータ。デフォルトはindexアクション。
• デフォルトでは、routeのパターンはコロンの(:)の接頭辞によって名前付きのワイルドカードを識別します。よりPHPにフレンドリな構文でルールを書きたいのであれば、ドル記号($)をvariable_prefixes配列に追加できます。この方法では、'/article/:year/:month/:day/:title'の代わりに'/article/$year/$month/$day/$title'のようなパターンを書けます。
• パターンのルーティングは区切り文字の間の名前付きのワイルドカードを見分けます。デフォルトの区切り文字はスラッシュとドットですが、望むのであればsegment_separatorsパラメータにより多くの区切り文字を追加できます。例えば、ダッシュ(-)を追加したい場合、'/article/:year-:month-:day/:title'のようなパターンを書けます。
• 本番モードにおいて、外部URLと内部URIの間の変換を加速するために、パターンのルーティングは独自のキャッシュを使用します。デフォルトでは、このキャッシュはファイルシステムを利用しますが、クラスと設定をcacheパラメータで宣言すれば任意のキャッシュクラスを使用できます。利用可能なキャッシュストレージクラスのリストに関しては15章を参照して下さい。本番環境でルーティングキャッシュを無効にするためには、debugパラメータをonに設定します。

sfPatternRoutingクラス専用の設定があります。アプリケーションのルーティング、独自もしくはsymfonyのルーティングファクトリ(sfNoRoutingとsfPathInfoRouting)の1つのどちらかに対して別のクラスを利用できます。これらの2つのどちらかを用いることで、すべての外部URLは'module/action?key1=param1'のようになります。カスタマイズする必要はありませんが、速いです。違いは最初のものはPHPのGETを使用し、2番目はPATH_INFOを使用します。主にバックエンドのインタフェースにこれらを使用します。

ルーティングに関連する追加パラメータが1つありますが、これは settings.ymlファイルに保存されます:

• no_script_name設定は生成されたURLの中でフロントコントローラを有効にします。フロントコントローラを様々なディレクトリに保存してデフォルトのURL書き換えルールを変更しない限り、no_script_name設定はプロジェクト内の単独のアプリケーションに対してのみonです。通常この設定は本番環境のメインアプリケーションに対してonでその他に対してoffです。

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

The features described in this section are deprecated since symfony 1.1 and only work if you enable the sfCompat10 plugin.

フォームバリデーションの設定は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章を参照)。factories.ymlファイルの中で2つのすべてのキャッシュシステム(ビューキャッシュ、ルーティングキャッシュと、国際化キャッシュ)に対してどのストレージを使用するのかを指定することもできます。リスト19-2はビューのキャッシュファクトリのデフォルト構成を示しています。

リスト19-2 - frontend/config/factories.ymlファイルの中の、ビューのキャッシュ構成の設定

view_cache:
  class: sfFileCache
  param:
    automatic_cleaning_factor: 0
    cache_dir:                 %SF_TEMPLATE_CACHE_DIR%
    lifetime:                  86400
    prefix:                    %SF_APP_DIR%/template

classの値はsfFileCache、sfAPCCache、sfEAcceleratorCache、sfXCacheCache、sfMemcacheCache、と sfSQLiteCacheのどれかになります。sfCacheを継承しキャッシュのキーの読み取りと削除をする、設定用の同じ一般的なメソッドを提供するのであれば、独自クラスも可能です。ファクトリのパラメータは選んだクラスに依存しますが、定数が存在します:

• lifetimeはキャッシュが削除されるまでの秒数を定義します
• prefixはすべてのキャッシュキーに追加される接頭辞です(環境によって異なるキャッシュを利用するために接頭辞の環境を使用する)。2つのアプリケーションの間でキャッシュを共有させたい場合は同じ接頭辞を使います。

それぞれの特定のファクトリに関しては、キャッシュストレージの位置を定義しなければなりません。

• sfFileCacheに関しては、cache_dirパラメータはキャッシュディレクトリへの絶対パスを探します
• sfAPCCache、sfEAcceleratorCache、とsfXCacheCacheは位置パラメータを取りません。これらがAPC、EAcceleratorもしくはXCacheキャッシュシステムとコミュニケーションするためにPHPのネイティブ関数を使用するからです
• sfMemcacheCacheに関しては、Memcachedサーバのホスト名をhostパラメータに、もしくはホストの配列をserversパラメータに入力します
• sfSQLiteCacheに関しては、SQLiteデータベースファイルへの絶対パスは databaseパラメータに入力されます。

追加パラメータに関しては、それぞれのキャッシュクラスのAPIドキュメントを確認して下さい。

ビューはキャッシュを使用できる唯一のコンポーネントではありません。routingファクトリとI18Nファクトリの両方は、ビューキャッシュと同じように、キャッシュファクトリを設定できるcacheパラメータを提供します。例えば、リスト19-1はデフォルトで加速戦術用にファイルキャッシュを使用するルーティングを示していますが、望むものは何でも変更できます。

ロギングの設定

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

• error_reportingはPHPログに記録されるイベントを指定します。デフォルトでは、本番環境に対してはE_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERRORに(ロギングされるイベントはE_PARSE、E_COMPILE_ERROR、E_ERROR、E_CORE_ERROR、と E_USER_ERROR)、開発環境ではE_ALL | E_STRICTに設定されます。
• web_debug設定はウェブデバッグツールバーを有効にします。開発とテスト環境のみではonに設定します。

アセットへのパス

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

• rich_text_js_dirに保存されるリッチなテキストエディタのJavaScriptファイル(デフォルトはjs/tiny_mce)
• prototype_web_dirに保存されるPrototypeライブラリ(デフォルトは/sf/prototype)
• admin_web_dirに保存されadministrationジェネレータが必要なファイル
• web_debug_web_dirに保存されウェブデバッグツールバーが必要なファイル
• calendar_web_dirに保存されJavaScriptのカレンダーが必要なファイル

デフォルトのヘルパ

デフォルトのヘルパは、すべてのテンプレートに対してロードされ、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-3は設定ファイルに現れるパラメータの一覧です。

リスト19-3 - frontend/config/settings.ymlファイルの中の、その他の構成設定

# symfonyのコアクラスのコメントをcore_compile.ymlファイルで定義されたものとして除去する
strip_comments:         on
# 例外の起動前のアクションの前のフォワードの最大回数
max_forwards:           5

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

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

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ファイルに対して機能します。

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

• myproject/lib/
• myproject/lib/model
• myproject/apps/frontend/lib/
• myproject/apps/frontend/modules/mymodule/lib

There is no autoload.yml file in the default application configuration directory. If you want to modify the framework settings--for instance, to autoload classes stored somewhere else in your file structure--create an empty autoload.yml file and override the settings of sfConfig::get('sf_symfony_lib_dir')/config/config/autoload.yml or add your own.

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

Listing 19-4 - Default Autoloading Configuration, in sfConfig::get('sf_symfony_lib_dir')/config/config/autoload.yml

autoload:
  # プラグイン
  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_LIB_DIR%/model
    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

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

独自のautoload.ymlファイルを編集すれば 新しい位置がsymfonyのオートローディング機能に追加されますが、このメカニズムを拡張してsymfonyのハンドラに独自のオートローディングハンドラを追加したいことがあります。symfonyはクラスのオートローディングを管理するために標準の spl_autoload_register()関数を使用するので、アプリケーションの設定クラスに多くのコールバックを登録できます:

class frontendConfiguration extends sfApplicationConfiguration
{
  public function initialize()
  {
    parent::initialize(); // symfonyのオートローディングを最初にロードする

    // 独自のオートローディングコールバックをここに挿入する
    spl_autoload_register(array('myToolkit', 'autoload'));
  }
}

PHPのオートローディングシステムは新しいクラスに遭遇するとき、最初にsymfonyのオートローディングメソッドが試されます(そしてautoload.ymlファイルの中で定義された位置が使用されます)。クラスの定義が見つからない場合、クラスが見つかるまでspl_autoload_register()で登録されたすべてのcallableが呼び出されます。例えば、他のフレームワークコンポーネントへのブリッジを提供するために(17章参照)、望む数だけオートローディングメカニズムを追加できます。

カスタムのファイル構造

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

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

基本的なファイル構造

パス変数はsfProjectConfigurationとsfApplicationConfigurationクラスの中で定義されsfConfigオブジェクトに保存されます。リスト19-5はパス変数とこれらが参照するディレクトリの一覧を示しています。

リスト19-5 - sfProjectConfigurationとsfApplicationConfigurationの中で定義された、デフォルトのファイル構造の変数

sf_root_dir           # myproject/
sf_apps_dir           #   apps/
sf_app_dir            #     frontend/
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_cache_dir          #   cache/
sf_app_base_cache_dir #     frontend/
sf_app_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_log_dir            #   log/
sf_test_dir           #   test/
sf_plugins_dir        #   plugins/
sf_web_dir            #   web/
sf_upload_dir         #     uploads/

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

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

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

For instance, if you want all applications to share a common directory for the template layouts, add this line to the setup() method of the ProjectConfiguration class to override the sf_app_template_dir settings:

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

sfConfig::set()を呼び出すことでプロジェクトのディレクトリ構造を変更できる場合でも、すべての関連パスの変更が考慮されるのでプロジェクトとアプリケーションの設定クラスによって定義された専用メソッドを使う方がベターです。例えば、setCacheDir()メソッドは次の定数: sf_cache_dir、sf_app_base_cache_dir、sf_app_cache_dir、sf_template_cache_dir、sf_i18n_cache_dir、sf_config_cache_dir、sf_test_cache_dir、とsf_module_cache_dirを変更します。

プロジェクトのウェブrootの修正

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

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

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

この場合、rootディレクトリはsymfony/ディレクトリです。ですのでアプリケーションを動かすためにはindex.phpフロントコントローラがconfig/ProjectConfiguration.class.phpファイルをインクルードすることがだけが必要です:

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

加えて、次のように、公開領域を通常のweb/からwww/に変更するにはsetWebDir()メソッドを使います:

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
    // ...

    $this->setWebDir($this->getRootDir().'/../www');
  }
}

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

リスト19-8で見られるように、symfonyへのパスは、config/ディレクトリ内に設置された、ProjectConfigurationクラスの中で定義されます。

リスト19-8 - myproject/config/ProjectConfiguration.class.phpの中の、symfonyのファイルへのパス

<?php

require_once '/path/to/symfony/lib/autoload/sfCoreAutoload.class.php';
sfCoreAutoload::register();

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
  }
}

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

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

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

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

この場合、次のようにProjectConfigurationクラスはsymfonyのlibディレクトリを必要とするだけです:

<?php

require_once dirname(__FILE__).'/../lib/vendor/symfony/lib/autoload/sfCoreAutoload.class.php';
sfCoreAutoload::register();

class ProjectConfiguration extends sfProjectConfiguration
{
  public function setup()
  {
  }
}

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

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

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

設定ハンドラを理解する

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

デフォルトの設定ハンドラ

The default handler configuration is stored in sfConfig::get('sf_symfony_lib_dir')/config/config/config_handlers.yml. This file links the handlers to the configuration files according to a file path. Listing 19-9 shows an extract of this file.

Listing 19-9 - Extract of sfConfig::get('sf_symfony_lib_dir')/config/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ファイルを使うためです。

config_handlers.ymlファイル用の設定ハンドラはsfRootConfigHandlerクラスで、明らかに変更できません。

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

独自ハンドラを追加する

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

• 設定ファイルはPHPの実行コードに変換され、このコードはキャッシュに保存されます。このことは、本番環境において設定は1回だけ解析されるのでパフォーマンスが最適化されていることを意味します。
• 設定ファイルは異なるレベル(プロジェクトとアプリケーション)で定義することが可能で、最後のパラメータの値はカスケードから由来します。プロジェクトレベルでパラメータを定義し、アプリケーション単位でこれらを上書きできます。

If you feel like writing your own configuration handler, follow the example of the structure used by the framework in the sfConfig::get('sf_symfony_lib_dir')/config/ directory.

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

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

$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-11で示されるように書けます。

リスト19-11 - frontend/lib/myMapConfigHandler.class.phpの中の、カスタムの設定ハンドラ

<?php

class myMapConfigHandler extends sfYamlConfigHandler
{
  public function execute($configFiles)
  {
    // Parse the 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

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

他の多くのsymfony設定ファイルに関しては、PHPコードに設定ハンドラを直接追加することもできます:

sfContext::getInstance()->getConfigCache()->registerConfigHandler('config/map.yml', 'myMapConfigHandler', array());

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

include(sfContext::getInstance()->getConfigCache()->checkConfig('config/map.yml'));

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

YAMLの設定ファイル内部で環境を扱いたい場合、ハンドラはsfYamlConfigHandlerクラスの代わりにsfDefineEnvironmentConfigHandlerクラスを拡張できます。設定を読み取るためには、parseYaml()メソッドの代わりにgetConfiguration()メソッド: $config = $this->getConfiguration($configFiles)を呼び出します。

-

既存の設定ハンドラを利用する

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

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

他のハンドラによって既に使用されている接頭辞を選ばないように気を付けて下さい。 既存の接頭辞はsf_、app、とmod_です。

要約

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