[转载注明：PHP开发资源网(http://www.phpres.com/)]

管理symfony 配置文件 Mastering symfony's configuration files

     现在你对symfony已经有了相当的认识， 你可以进一步深入研究它的代码以便了解它的核心设计和发现它的新的不容易引起注意的能力。 但是在你扩展symfony类以符合你的需要之前， 应该仔细看一下一些配置文件。 symfony中已经内置了许多特性， 只需要更改配置就可以激活这些特性。 也就是说， 你无需重载symfony的类就可以调整symfony的核心行为。 本章带你深入研究配置文件和由这些文件带来的强大能力。

symfony配置参数 symfony settings

myapp程序(application)的主要symfony配置都在myapp/config/settings.yml文件中。在前面章节中你已经看到许多配置参数的功能， 这里我们再看一下。

在第5章中我们已经解释过， 这个文件是与环境有关的， 也就是说每个参数可以为每个环境取一个不同的值。 记住， 通过sfConfig 类可以从PHP代码访问文件中定义的每一个参数值。 这些参数都以sf_开头。 例如， 如果你想得到cache参数的值， 你只需调用sfConfig::get(‘sf_cache’)即可。

默认的模块和行动 Default Modules and Actions
当一个程序规则没有定义模块或行动的参数时， settings.yml文件中的值就会用默认值代替: default_module: 默认模块请求参数， 是默认模块的默认值。 default_action: 默认行动请求参数， 是索引行动的默认值。
symfony为特殊情况提供了默认页。 在 $sf_symfony_data_dir/modules/default/目录下存放着默认模块， 在程序出错的情况下， symfony就执行默认模块的一个行动。 settings.yml文件则根据错误的不同， 定义了可以执行的行动:
error_404_modeule 和error_404_action: 当用户输入的URL和任何程序都不匹配时或当一个sfError404Exception产生时， 就调用这个模块。 默认值是default/error404。
login_module和login_action: 当一个未经认证的用户试图访问由security.yml中定义为secure的页面时(请参考第6章的解释)， 这个行动将被调用。 默认值是default/login。
secure_module and secure_action: 当一个用户不具备某个行动所需的信任证书时， 这个行动将被调用。 默认值是default/secure。
module_disabled_module和module_disabled_action: 当一个用户请求一个被module.yml定义为disabled的模块时， 这个行动将被调用。 默认值是default/disabled。
unavailable_module和unavailable_action: 当一个用户从一个被禁用的程序(application)中请求一个页面时， 这个行动将被调用。 默认值是default/unavailable。 要禁用一个程序(application)， 在settings.yml中关闭available参数即可。
在将一个程序(application)部署到生产环境中之前， 你需要定制这些行动， 因为默认模块的模板在页面中都包括了symfony的标识。
图19-1是页面之一的404错误页面的截屏。

你可以通过两种方法重载这些默认页:
对于settings.yml文件中定义的所有行动(index，error404， login， secure，disabled和unavailable)和所有相应的模板(indexSuccess.php， error404Success.php， loginSuccess.php， secureSuccess.php， disabledSuccess.php和unavailableSuccess.php)， 你可以在程序(application)的modules/目录中创建自己的默认模块。
对于settings.yml文件中的默认模块和行动， 你可以将参数值设为你的程序(application)的页面。
另外， 还有两个页面也包括symfony标识， 所以在实际部署之前也需要对它们重新定制。这两个页面不在默认模块中， 因为只有当symfony不能正常运行时， 才会被调用。你可以在$sf_symfony_data_dir/web/errors目录中看到这些页面:
error500.php: 当生产环境中出现内部服务器错误时， 该页面被调用。在SF_DEBUG设定为true并且出现一个错误时， symfony会显示所有的执行栈和精确的错误信息(请参看第16章的介绍)。
unavailable.php: 当用户请求一个缓存已被清除的页面时(也就是在调用symfony的clear-cache任务和该任务结束之间请求时)， 该页面被调用。 对于一个有着很大缓存的系统， 清除缓存可能需要几秒。symfony在部分清除缓存的情况下
要定制这些页面， 只需在程序(application)的web/errors目录中创建error500.php和unavailable.php即可。symfony将用这些页面代替默认页面。
NOTE 注意: 如果要将请求转向unavailable.php页面， 你应该将settings.yml中的check_lock设置为on. 该参数的默认值是off， 因为它会为每一个请求增加极少的一些负担。

选特性的激活 Optional Feature Activation

设定或取消settings.yml文件中的一些参数就可以设定或取消某些框架特性。取消不会用到的特性可以提高系统性能， 所以在部署程序(application)之前，你应该确保已经检查了表19-1中列出的参数值。

表 19-1 - 可以通过settings.yml设定的可选特性参数        描述        默认值
use_database        激活数据库管理。如果设定为off， 你将不能使用数据。        on
use_security        激活安全特性(包括安全的行动和信任证书， 请参看第6章。只有在这个特性被激活的条件下，才能使用默认的安全过滤器(sfBasicSecurityFilter。        on
use_flash        激活flash特性(请参看第6章。如果你在你的行动中从来都不用flash()， 就将这个参数设为off. 只有在这个特性被激活的条件下，才能使用flash过滤器(sfBasicFlashFilter。        on
i18n        激活接口翻译特性(请参看第6章。如果你的程序(application)是多种语言的， 将它设为on.        off
logging_enabled        允许symfony事件日志。如果你想忽略logging.yml的配置并且将symfony日志完全关闭， 就将它设为off.        on
escaping_strategy        激活输出转义特性并定义输出转义的策略(请参看第7章。如果在你的模板中不会用到$sf_data容器的话， 就将它设为off.        bc
cache        激活模板缓存(请参看第12章。如果你的模块中包括cache.yml文件， 就将它设为on. 只有在on的状态下， 才能用缓存过滤器(sfCacheFilter。        开发时为off， 实际生产环境为on
web_debug        允许使用web调试工具栏， 以便于调试(请参看第16章。如果你想在每一页中都显示工具栏， 就将它设为on. 只有在on的状态下， 才能用web调试过滤器(sfWebDebugFilter。        开发时为on， 实际生产环境为off
check_symfony_version        允许每次请求是检查symfony的版本。如果要在框架升级后能自动清楚缓存， 就将它设为on. 如果设定为off， 升级后你总是需要清除缓存。        off
check_lock        允许有清除缓存和禁用任务触发程序(application)锁定系统(请参看前面部分的内容。如果对被禁用的程序(application)的所有请求都被转向至$sf_symfony_data_dir/web/errors/unavailable.php页的话， 就将它设为on。        off
compressed        激活PHP应答压缩特性。如果你想通过PHP压缩句柄压缩出现的HTML页时， 就 将它设为on.        off
use_process_cache        激活基于PHP加速器的symfony优化特性。如果你安装了诸如APC， XCache 或eAccelerator之类的加速器时， symfony 可以利用这些加速器的能力在请求之间将对象和配置保存在内存。开发过程中或者你不想使用PHP加速器优化时， 将它设为off。 即使你没有安装任何加速器， 设为on也不会影响系统性能。 on

特性配置 Feature Configuration

设置setting.yml中的某些参数可以改变诸如表单验证， 缓存和第三方模块等的内置特性的行为。
输出转义参数 Output Escaping Settings

输出转义参数控制模板中的变量可存取的方法(请参看第7章。setting.yml中包括两个与这个特性有关的参数:
escaping_strategy 参数可取 bc， both, on， 或off等值。
escaping_method 参数可取 ESC_RAW， ESC_ENTITIES， ESC_JS， 或 ESC_JS_NO_ENTITIES。
路由参数 Routing Settings

settings.yml中有两个路由参数: * suffix 参数为生成的URL设定默认的后缀。suffix的默认值是句号.， 相应的后缀为. 如果设定为.html， 则所有生成的URL就都成了静态页面。 * no_script_name 参数可以让前端控制器的名字出现在生成的URL。除非你将前端控制器存放在不同的目录中并且修改了默认的URL重写规则， 只在项目的一个单独程序(application)中设置为on. 通常在主要程序(application)的生产环境中设置为on， 其他情况下都设置为off。
表单验证配置参数 Form Validation Settings

表单验证配置参数控制由Validation 辅助函数组产生的错误信息的输出方式(请参看第10章。些错误包括在

<

div>标记中， 它们利用validation_error_class参数(作为类的属性)和validation_error_id_prefix参数来构造id属性， 默认值是form_error和error_for_， 因此， 对于一个名为foobar的输入来说，调用form_error()而输出的属性将会是class=”form_error”, id=”error_for_foobar”。

这两个参数确定了每条错误信息的前缀字符(validation_error_prefix)和后缀字符(validation_error_suffix。你可以根据需要定制你自己的错误信息。

缓存配置参数 Cache Settings

缓存配置参数大多数在cache.yml中定义，只有cache和etag在settings.yml中定义，前者打开模板缓存机制，后者允许ETAG在服务器端操作(请参看第15章)。
日志配置参数 Logging Settings

settings.yml中包括两个日志配置参数(请参看第16章): error_reporting指明在php日志中记录哪些事件。通常在生产环境中设为341，也即记录E_PARSE，E_COMPILE_ERROR，E_ERROR，E_CORE_ERROR和E_USER_ERROR产生的事件，而在开发环境中设为4095， 即只记录E_ALL 和 E_STRICT产生的事件。 web_debug激活web debug toolbar. 仅在开发和测试环境中才需要设置这个参数。
指向资源的路径 Paths to Assets

settings.yml中还包括指向资源的路径的参数。如果你想用与symfony设定的路径不同的路径值， 你可以改变以下路径参数的设置:
rich_text_js_dir : Rich text编辑器Javascript 文件的存放路径， 默认值为 js/tiny_mce
prototype_web_dir: 原型库的路径，默认值为/sf/prototype
admin_web_dir:管理生成器所需文件的存放路径。
web_debug_web_dir:web debug toolbar所需文件的存放路径。
calendar_web_dir: javascript calendar所需文件的存放路径。
默认辅助函数配置参数 Default Helpers

配置参数standard_helpers指明每个模板都会导入的默认辅助函数(请参看第7章)， 默认值是Partial， Cache 和 Form 辅助函数。果你要在某个程序(application)的所有模板中都导入一个辅助函数组， 就将这个组的名字加入到standard_helpers中， 这样就可以避免在每个模板中都用use_helper()去声明。

激活模块配置参数 Activated Modules

enabled_modules参数指明从插件或symfony核心激活的模块。使某个插件绑定了一个模块， 如果没有预先在enabled_modules中声明， 用户也不可以请求这个模块。该参数的默认值只包括提供默认的symfony页(成功页， 未发现页等)的模块。
Character Set 字符集

程序(application)的一项通用设置是字符集， 因为框架的许多部分都会用到字符集， 如模板， 输出转义和辅助函数。配置参数charset用于定义字符集， 默认值是utf-8。
其他配置 Miscellaneous Configuration

settings.yml文件中还包括一些用于控制symfony核心行为的参数。表19-1列出了这些参数。

表19-1 myapp/config/settings.yml中的其他配置参数。
# 去掉core_compile.yml里定义的框架核心类的注释
strip_comments:         on
# 累被调用但还没载入时执行的函数
# 参数值为函数名组成的数组。由框架桥调用。
autoloading_functions:  ~
# session过气事件，单位秒
timeout:                1800
# 抛出错误前的最大跳转次数
max_forwards:           5
# 全局常量
path_info_array:        SERVER
path_info_key:          PATH_INFO
url_format:             PATH

SIDEBAR 加入你的程序(application)的配置参数

settings.yml定义了一个程序(application)的symfony参数配置。在第五章中我们说过， 如果你想加入新的参数， 最合适的地方是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文件， 用于定制项目的配置参数。这个文件也受配置级联的影响， 所以在程序(application)的app.yml定义的参数会覆盖项目级的app.yml中定义的参数。

扩展自动载入特性 Extending the Autoloading Feature

在第二章我们介绍了自动载入特性， 如果类在某些特定的目录中， 这个特性可以让你无需在你的代码中require 。也就是说， 框架会在你需要的适当时候帮你完成这些工作。

autoload.yml文件中列出了所有可以自动载入类的路径。这个配置文件第一次被处理时， symfony就会编译文件中引用的所有路径。一旦在这些目录中发现有.php文件， 那么这个文件的路径和类名就会被加进一个存放自动载入类的内部列表。这个列表放在缓存的config/config_autoload.yml.php文件。系统运行的时候， 如果需要用到一个类， symfony就会在这个列表中自动查找类的路径，并将找到的.php文件包括进去。

所有包含类和/或接口的.php文件都是自动加载的对象。

系统默认在项目的以下目录中的类都能被自动加载: * myproject/lib/ * myproject/lib/model * myproject/apps/myapp/lib/ * myproject/apps/myapp/modules/mymodule/lib

在默认的程序(application)配置目录中， 并没有autoload.yml文件。如果你想修改框架参数---比如，你希望你的文件结构中某些目录中的类也能被自动加载---你可以创建一个空的autoload.yml文件， 并重定义$sf_symfony_data_dir/config/autoload.yml或增加自己的定义。

autoload.yml文件必须以autoload关键字开头， 然后列出所有的symfony可以寻找类的位置。每个位置需要一个标签， 这可以让你重载symfony的定义。每个位置还需要提供一个名字name(以注释形式出现在config_autoload.yml.php中)和一个绝对路径path.然后还需要用recursive参数确定是否需要递归， 也就是说symfony是否需要在所有的子目录中查找.php文件，并用exclude参数排除无需查找的子目录。19-2列出了默认的位置和定义方法。

表19-2 $sf_symfony_data_dir/config/autoload.yml中定义的默认的自动载入配置。 autoload:
  # symfony core
  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
  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
  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
  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的句柄中。这可以通过在settings.yml文件中的autoloading_functions参数来实现。这个配置需要一个以可调用方法为元素的数组作为参数， 示例如下:
.settings:
  autoloading_functions:
    - [myToolkit， autoload]

当symfony遇到一个新的类， 它首先用自己的自动载入机制和autoload.yml中定义的位置， 如果没有找到类的定义， 它会用settings.yml中的其他自动加载功能继续寻找， 一直到类被找到为止。所以你可以任意添加你想要的自动加载功能，例如在第十七章中介绍过的连接到框架组件的桥。

定制文件结构 Custom File Structure

每当框架寻找一个路径时， 无论是核心类还是模板，插件，配置文件等，系统都用路径变量而不用实际路径。通过改变这些变量， 你可以遵照客户的需要完全改变symfony项目的目录结构。

CAUTION 注意 你可以定制symfony项目的目录结构，但这并不非常必要。symfony框架的一个优点就是任何一个开发者只要看到默认的目录结构， 就会根据习惯知道项目的结构。在你改变项目结构之前应该考虑这个因素。
基本的文件结构 The Basic File Structure

在程序(application)被启动时， $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/目录中，你应该用sfConfig::get(‘sf_upload_dir’)来取得路径， 而不应该使用SF_ROOT_DIR.’/web/uploads/’。

当运行系统确定了模块名($module_name)时， 模块的目录结构在运行时被定义。这是根据constants.php文件中定义的路径名自动产生的，表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/目录的路径在运行时自动生成为:

sfConfig::get('sf_app_module_dir'./.module_name.'/'.sfConfig::get('sf_app_module_validate_dir_name')Modifying the Project Web Root