settings.yml 設定ファイル

symfony のコンフィギュレーションの大半は YAML もしくはプレーンな PHP で書かれた設定ファイルを通じて変更できます。この章では settings.yml ファイルを説明します。

アプリケーションの settings.yml ファイルは apps/APP_NAME/config/ ディレクトリに配置されています。

設定ファイルの原則の章で述べたように、settings.yml ファイルでは、環境が認識され、コンフィギュレーションカスケードのメカニズムがはたらいています。

それぞれの環境には2つのサブセクション (.actions と .settings) が設けられています。共通ページにおいてレンダリングされるデフォルトのアクション以外、すべてのコンフィギュレーションディレクティブは .settings サブセクションにとりそろえられています。

設定

• .actions

  • error_404
  • login
  • secure
  • module_disabled

• .settings

  • cache
  • charset
  • check_lock
  • compressed
  • csrf_secret
  • default_culture
  • default_timezone
  • enabled_modules
  • error_reporting
  • escaping_strategy
  • escaping_method
  • etag
  • i18n
  • lazy_cache_key
  • file_link_format
  • logging_enabled
  • no_script_name
  • standard_helpers
  • use_database
  • web_debug
  • web_debug_web_dir

.actions サブセクション

デフォルトコンフィギュレーション:

default:
  .actions:
    error_404_module:       default
    error_404_action:       error404
 
    login_module:           default
    login_action:           login
 
    secure_module:          default
    secure_action:          secure
 
    module_disabled_module: default
    module_disabled_action: disabled

.actions サブセクションは共通ページがレンダリングされる際に実行されるアクションを定義します。それぞれの定義には2つの要素が用意されており、1つはモジュール (サフィックスは _module) で、もう1つはアクション (サフィックスは _action) です。

error_404

error_404 アクションは404ページがレンダリングされる際に実行されます。

login

login アクションは認証されていないユーザーが認証を必要とするページにアクセスしようとすると実行されます。

secure

secure アクションはアクセスしてきたユーザーが必須のクレデンシャルをもっていない場合に実行されます。

module_disabled

module_disabled アクションはユーザーが無効なモジュールをリクエストした際に実行されます。

.settings サブセクション

.settings サブセクションではフレームワークの設定を調整します。下記の段落では、利用可能なすべての設定項目を説明します。設定項目はおおまかな重要度順で並べられています。

.settings セクションで定義されているすべての設定項目の名前は設定の名前にプレフィックスの sf_ をつけたものであり、sfConfig オブジェクトを通じて任意の場所で利用できます。たとえば charset 設定の値を得るには、コードを次のように書きます。

sfConfig::get('sf_charset');

escaping_strategy

デフォルト: true

escaping_strategy 設定は出力エスケーパサブフレームワークを有効にするかどうかを決めます。この設定はブール値をとります。この設定が有効な場合、escaping_method 設定で定義されているヘルパー関数が呼び出され、テンプレートのなかで利用可能なすべての変数は自動的にエスケープされます (下記の説明をご参照ください)。

escaping_method 設定がデフォルトのヘルパーであることにご注意ください。ケースバイケースでこの設定をオーバーライドすれば、たとえば JavaScript スクリプトタグのなかで変数を出力するなどの状況に対処できます。

出力エスケーパサブフレームワークはエスケープの際に charset 設定を使います。

設定の値はデフォルトの true のままにしておくことをぜひおすすめします。

escaping_method

デフォルト: ESC_SPECIALCHARS

escaping_method 設定はテンプレートのなかでエスケープに使われるデフォルトの関数を定義します (上記の escaping_strategy 設定をご参照ください)。

組み込み関数の1つを選ぶ、もしくは自前の関数を作ることができます (ESC_RAW、ESC_ENTITIES、ESC_JS、 ESC_JS_NO_ENTITIES と ESC_SPECIALCHARS)。

ほとんどの場合、デフォルトで事足ります。英語もしくはヨーロッパの言語だけを扱う場合には ESC_ENTITIES ヘルパーを選ぶこともできます。

csrf_secret

デフォルト: ランダムに生成される秘密の文字列

csrf_secret 設定はアプリケーションにおいて一意性のある秘密の文字列です。この設定に false がセットされていないかぎり、フォームフレームワークで定義されているすべてのフォームで CSRF 対策機能が有効になります。この設定は link_to() ヘルパーにも使われ、リンクをフォームに変換することが必要な場合に役立ちます (たとえば HTTP DELETE メソッドをシミュレートしたい場合)。

デフォルトをあなたが選んだ一意性のある秘密の文字列に変更しておくことをぜひおすすめします。

charset

デフォルト: utf-8

charset 設定はフレームワークのあらゆる場所で使われる文字集合を指定します。この設定の利用範囲はレスポンスの Content-Type ヘッダーから出力エスケーピングまでおよびます。

ほとんどの場合、デフォルトで事足ります。

enabled_modules

デフォルト: [default]

enabled_modules 設定はこのアプリケーションで有効にするモジュールの名前の配列です。デフォルトでは、プラグインもしくは symfony コアで定義されているモジュールは有効ではなく、これらにアクセスできるようにするには、この配列につけ加えなければなりません。

モジュールの追加方法はシンプルで、リストに名前を加えるだけです (モジュールの順序は問いません)。

enabled_modules: [default, sfGuardAuth]

settings.yml ファイルの .actions サブセクションであらかじめ定義されているすべてのデフォルトアクションは symfony フレームワークの default モジュールに収められています。これらすべてをカスタマイズし、この設定から default モジュールを除外しておくことをおすすめします。

default_timezone

デフォルト: なし

default_timezone 設定は PHP が使うデフォルトのタイムゾーンを定義します。この設定は PHP が認識する任意のタイムゾーンをとります。

cache

デフォルト: false

cache 設定はテンプレートのキャッシュを有効もしくは無効にします。

etag

デフォルト: dev と test 環境を除いて、デフォルトでは true

etag 設定は HTTP の ETag ヘッダーの自動生成を有効もしくは無効にします。レスポンスのコンテンツにおいて、symfony によって生成される ETag ヘッダーは単純な md5 のハッシュです。

i18n

デフォルト: false

i18n 設定は国際対応サブフレームワークを有効もしくは無効にします。この設定はブール値をとります。国際対応したアプリケーションを開発するのであれば、この設定に true をセットします。

default_culture

デフォルト: en

default_culture 設定は国際対応サブフレームワークで使われるデフォルトのカルチャを定義します。この設定は任意の有効なカルチャの文字列をとります。

standard_helpers

デフォルト: [Partial, Cache]

standard_helpers 設定はすべてのテンプレートのなかでロードされるヘルパーグループの配列です (ヘルパーグループの名前にはサフィックスの Helper をつけません)。

no_script_name

デフォルト: 新しいアプリケーションの prod 環境では true、それ以外の環境では false

no_script_name 設定は生成される URL にフロントコントローラスクリプトの名前をつけ足すかどうかを決めます。generate:app タスクによって作られた新しいアプリケーションの prod 環境において、この設定には true がセットされています。

すべてのフロントコントローラが同じディレクトリ (web/) に配置されている場合、この設定に true をセットできるのはあきらかに1つのアプリケーションと環境にかぎられます。no_script_name 設定に true がセットされているアプリケーションが複数必要であれば、該当するフロントコントローラを Web 公開ディレクトリに移動させます。

lazy_cache_key

デフォルト: 新しいプロジェクトでは true、アップグレードしたプロジェクトでは false

lazy_cache_key 設定が有効な場合、キャッシュキーの生成はアクションもしくはパーシャルがキャッシュ可能になるまで延期されます。テンプレートパーシャルの使いかたしだいではパフォーマンスを大きく改善できます。

file_link_format

デフォルト: なし

デバッグメッセージにおいて、sf_file_link_format 設定もしくは PHP の xdebug.file_link_format ディレクティブに値がセットされている場合、ファイルパスはクリック可能なリンクに変換されます。たとえば、ファイルが TextMate で開かれるようにしたいのであれば、次の値をセットします。

txmt://open?url=file://%f&line=%l

%f プレースホルダはファイルの絶対パスに置き換わり、%l プレースホルダは行番号に置き換わります。

logging_enabled

デフォルト: prod 以外のすべての環境では true

logging_enabled 設定はロギングサブフレームワークを有効にします。この設定に false がセットされていれば、ロギングメカニズムが回避され、パフォーマンスが少し改善されます。

web_debug

デフォルト: dev 以外のすべての環境では false

web_debug 設定はデバッグツールバーを有効にします。レスポンスの Content-Type ヘッダーに HTML がセットされている場合、デバッグツールバーがページに投入されます。

error_reporting

デフォルト:

• prod: E_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERROR
• dev: E_ALL | E_STRICT
• test: (E_ALL | E_STRICT) ^ E_NOTICE
• デフォルト: E_PARSE | E_COMPILE_ERROR | E_ERROR | E_CORE_ERROR | E_USER_ERROR

error_reporting 設定は PHP のエラーレポートのレベルをコントロールします (ログに書き込まれ、ブラウザに表示されます)。

デフォルトのコンフィギュレーションがもっとも理にかなったものであり、変更すべきではありません。

compressed

デフォルト: false

compressed 設定は PHP ネイティブなレスポンス圧縮を有効にします。この設定に true がセットされている場合、ob_gzhandler() 関数が ob_start() 関数のコールバックに使われます。

この設定に false をセットしておいたままにしておいて、Web サーバーに備わっている圧縮メカニズムを利用することをおすすめします。

use_database

デフォルト: true

use_database 設定はアプリケーションでデータベースを使うかどうかを決めます。

check_lock

デフォルト: false

check_lock 設定は cache:clear や project:disable タスクなどによって実行されるアプリケーションのロックシステムを有効もしくは無効にします。

この設定に true がセットされている場合、無効なアプリケーションへのリクエストはすべて自動的に symfony コアの lib/exception/data/ ディレクトリに配置されている unavailable.php ページにリダイレクトされます。

web_debug_web_dir

デフォルト: /sf/sf_web_debug

web_debug_web_dir 設定には Web サイトにおけるデバッグツールバーのアセット (画像、スタイルシートそして JavaScript ファイル) へのパスがセットされます。