Development

Documentation/zh_CN/book/1.0/05-Configuring-Symfony (diff)

You must first sign up to be able to contribute.

Changes between Version 3 and Version 4 of Documentation/zh_CN/book/1.0/05-Configuring-Symfony

Show
Ignore:
Author:
Le.Jiang (IP: 222.67.111.231)
Timestamp:
03/26/07 17:19:28 (10 years ago)
Comment:

finished 99% of this chapter

Legend:

Unmodified
Added
Removed
Modified
  • Documentation/zh_CN/book/1.0/05-Configuring-Symfony

    v3 v4  
    368368实际上,symfony的配置信息分成好几级: 
    369369 
    370   * Granularity levels
    371     * The default configuration located in the framework 
    372     * The global configuration for the whole project (in `myproject/config/`
    373     * The local configuration for an application of the project (in `myproject/apps/myapp/config/`
    374     * The local configuration restricted to a module (in `myproject/apps/myapp/modules/mymodule/config/`
    375   * Environment levels
    376     * Specific to one environment 
    377     * For all environments 
    378  
    379 Of all the properties that can be customized, many are environment-dependent. Consequently, many YAML configuration files are divided by environment, plus a tail section for all environments. The result is that typical symfony configuration looks like 例 5-12. 
    380  
    381 例 5-12 - The Structure of Symfony Configuration Files 
    382  
    383     # Production environment settings 
     370  * 粒度级别
     371    * 框架里的默认配置 
     372    * 整个项目的全局配置 (在 `myproject/config/` 里
     373    * 项目中应用程序的配置 (在 `myproject/apps/myapp/config/` 里
     374    * 模块的配置 (在 `myproject/apps/myapp/modules/mymodule/config/` 里
     375  * 环境级别
     376    * 针对某一个环境 
     377    * 所有环境 
     378 
     379所有可以自定的属性里,有一些是与环境有关的。因此,很多YAML配置文件是按照环境分成了好几段,最后一段针对所有环境。因此一个典型的symfony配置文件类似于例 5-12。 
     380 
     381例 5-12 - symfony配置文件的结构 
     382 
     383    # 生产环境设置 
    384384    prod: 
    385385      ... 
    386386 
    387     # Development environment settings 
     387    # 开发环境设置 
    388388    dev: 
    389389      ... 
    390390 
    391     # Test environment settings 
     391    # 测试环境设置 
    392392    test: 
    393393      ... 
    394394 
    395     # Custom environment settings 
     395    # 自定义环境设置 
    396396    myenv: 
    397397      ... 
    398398 
    399     # Settings for all environments 
     399    # 所有环境的设置 
    400400    all: 
    401401      ... 
    402402 
    403 In addition, the framework itself defines default values in files that are not located in the project tree structure, but in the $sf_symfony_data_dir/config/ directory of your symfony installation. The default configuration is set in these files as shown in 例 5-13. These settings are inherited by all applications. 
    404  
    405 例 5-13 - The Default Configuration, in `$sf_symfony_data_dir/config/settings.yml` 
     403另外,symfony框架本身定义的默认值并不在项目的目录里,它们在你的symfony的$sf_syfmony_data_dir/config/目录里。默认的配置信息在例5-13里的文件里设置。所有的应用程序都会继承到这些设定。 
     404 
     405例 5-13 - 默认配置信息, 在 `$sf_symfony_data_dir/config/settings.yml`里 
    406406 
    407407     # Default settings: 
    411411       ... 
    412412 
    413 These default definitions are repeated in the project, application, and module configuration files as comments, as shown in 例 5-14, so that you know that some parameters are defined by default and that they can be modified. 
    414  
    415 例 5-14 - The Default Configuration, Repeated for Information, in `myapp/config/settings.yml` 
     413这些配置会在项目,应用程序,模块的配置信息里面以注释的形式反复出现,如例5-14所示,这样你就可以知道这些默认值并且可以修改它们。 
     414 
     415例 5-14 - 默认配置信息, 在 `myapp/config/settings.yml` 中出现以供参考 
    416416 
    417417    #all: 
    420420     ... 
    421421 
    422 This means that a property can be defined several times, and the actual value results from a definition cascade. A parameter definition in a named environment has precedence over the same parameter definition for all environments, which has precedence over a definition in the default configuration. A parameter definition at the module level has precedence over the same parameter definition at the application level, which has precedence over a definition at the project level. This can be wrapped up in the following priority list
    423  
    424   1. Module 
    425   2. Application 
    426   3. Project 
    427   4. Specific environment 
    428   5. All environments 
    429   6. Default 
     422这意味着一个属性可以多次定义,最后的取值取决于层叠的结构。任何特定一个环境里定义的参数优先于所有环境里定义的参数,所有环境里的参数优先于默认配置。模块配置里的参数优先于应用程序级里定义的同样参数,应用程序里的参数优先于项目级。这可以通过下面的优先级列表来表示
     423 
     424  1. 模块 
     425  2. 应用程序 
     426  3. 项目 
     427  4. 特定的环境 
     428  5. 所有环境 
     429  6. 默认 
    430430 
    431431配置缓存 The Configuration Cache 
    432432----------------------- 
    433433 
    434 Parsing YAML and dealing with the configuration cascade at runtime represent a significant overhead for each request. Symfony has a built-in configuration cache mechanism designed to speed up requests. 
    435  
    436 The configuration files, whatever their format, are processed by some special classes, called handlers, that transform them into fast-processing PHP code. In the development environment, the handlers check the configuration for changes at each request, to promote interactivity. They parse the recently modified files so that you can see a change in a YAML file immediately. But in the production environment, the processing occurs once during the first request, and then the processed PHP code is stored in the cache for subsequent requests. The performance is guaranteed, since every request in production will just execute some well-optimized PHP code. 
    437  
    438 For instance, if the `app.yml` file contains this
    439  
    440     all:                   # Setting for all environments 
     434执行时解析YAML还有处理配置文件的层叠结构会增加每次请求的负担。symfony内建了配置文件缓存机制来提高请求速度。 
     435 
     436不管什么格式的配置文件都需要一些特别的类来处理,又叫处理者,这些配置文件被转换成快速的PHP代码。开发环境里,处理着每次请求都会去检查配置文件的变化,这样提高交互性。它们解析改变的文件使你能马上看到YAML改编的效果。但是在生产环境,这样的处理只在第一次请求时进行,处理得到的PHP代码被保存下来给后面的请求使用。这样能提高性能,因为生产环境里的每次请求只需要执行一些优化过的PHP代码。 
     437 
     438例如,如果`app.yml`文件内容如下
     439 
     440    all:                   # 所有环境的设置 
    441441      mail: 
    442442        webmaster:         webmaster@example.com 
    443443 
    444 then the file `config_app.yml.php`, located in the `cache/` folder of your project, will contain this
     444那么`cache/`目录下的`config_app.yml.php`文件,将包括下面的内容
    445445 
    446446    [php] 
    451451    )); 
    452452 
    453 As a consequence, most of the time, the YAML files aren't even parsed by the framework, which relies on the configuration cache instead. However, in the development environment, symfony will systematically compare the dates of modification of the YAML files and the cached files, and reprocess only the ones that have changed since the previous request. 
    454  
    455 This presents a major advantage over many PHP frameworks, where configuration files are compiled at every request, even in production. Unlike Java, PHP doesn't share an execution context between requests. For other PHP frameworks, keeping the flexibility of XML configuration files requires a major performance hit to process all the configuration at every request. This is not the case in symfony. Thanks to the cache system, the overhead caused by configuration is very low. 
    456  
    457 There is an important consequence of this mechanism. If you change the configuration in the production environment, you need to force the reparsing of all the configuration files for your modification to be taken into account. For that, you just need to clear the cache, either by deleting the content of the cache/ directory or, more easily, by calling the clear-cache symfony task
     453这样,大多数时候,symfony不需要去解析YAML文件,只需要执行cache里的配置信息就可以了。不过在开发环境,symfony会自动比较YAML文件还有配置缓存的修改时间,只重新处理上次请求后修改过的配置文件。 
     454 
     455这是symfony与其他很多PHP框架相比的很大的有点,这些PHP框架里每次请求时都会去处理配置文件,即使是生产环境。与Java不同,PHP不会在请求之间共享执行状态。 其他依赖XML配置文件的框架在每次请求时处理XML性能损失很大。symfony不存在这个问题,配置文件带来的速度影响很小。 
     456 
     457这样的机制带来一个重要的问题,如果你改变了生产环境的配置信息,你需要强制重新解析所有你修改过的配置文件,这样改变才能生效。你只需要清除缓存就可以了,可以直接清空cache/目录的内容,或是执行clear-cache这个symfony任务
    458458 
    459459    > symfony clear-cache 
    462462------------------------------------- 
    463463 
    464 All the configuration files are eventually transformed into PHP, and many of the settings they contain are automatically used by the framework, without further intervention. However, you sometimes need to access some of the settings defined in the configuration files from your code (in actions, templates, custom classes, and so on). The settings defined in settings.yml, app.yml, module.yml, logging.yml, and i18n.yml are available through a special class called sfConfig. 
    465  
    466 ### The sfConfig Class 
    467  
    468 You can access settings from within the application code through the `sfConfig` class. It is a registry for configuration parameters, with a simple getter class method, accessible from every part of the code: 
    469  
    470     [php] 
    471     // Retrieve a setting 
     464所有的配置文件最终都被转换成PHP代码,框架会自动使用很多设置。不过,有时你需要在你的代码中(动作,模版,自定义类等)访问配置文件里定义的设置。settings.yml、apps.yml、module.yml、logging.yml还有i18n.yml里的配置信息可以通过一个特殊的sfConfig类来访问。 
     465 
     466### sfConfig类 The sfConfig Class 
     467 
     468你可以在程序代码里通过`sfConfig`类访问配置信息。它是一个配置信息的登记处,它有一些简单的存取方法,这些存取方法可以在程序的任何地方使用。 
     469 
     470    [php] 
     471    // 取得一个设定 
    472472    parameter = sfConfig::get('param_name', $default_value); 
    473473 
    474 Note that you can also define, or override, a setting from within PHP code
    475  
    476     [php] 
    477     // Define a setting 
     474注意你也可以在PHP代码里定义或者覆盖一个设置
     475 
     476    [php] 
     477    // 定义一个设定 
    478478    sfConfig::set('param_name', $value); 
    479479 
    480 The parameter name is the concatenation of several elements, separated by underscores, in this order
    481  
    482   * A prefix related to the configuration file name (`sf_` for `settings.yml`, `app_` for `app.yml`, `mod_` for `module.yml`, `sf_i18n_` for `i18n.yml`, and `sf_logging_` for `logging.yml`) 
    483   * The parent keys (if defined), in lowercase 
    484   * The name of the key, in lowercase 
    485  
    486 The environment is not included, since your PHP code will have access only to the values defined for the environment in which it's executed. 
    487  
    488 For instance, if you need to access the values defined in the app.yml file shown in 例 5-15, you will need the code shown in 例 5-16. 
    489  
    490 例 5-15 - Sample `app.yml` Configuration 
     480参数的名字由几部分组成,中间用下划线分割,顺序如下
     481 
     482  * 与配置文件名有关的前缀 (`sf_` 代表 `settings.yml`, `app_` 代表 `app.yml`, `mod_` 代表 `module.yml`, `sf_i18n_` 代表 `i18n.yml`, `sf_logging_` 代表 `logging.yml`) 
     483  * 父键名 (如果有), 小写形式 
     484  * 键名, 小写形式 
     485 
     486参数名字不包括环境名称,因为PHP代码只能访问到执行时所在的环境里定义的参数。 
     487 
     488例如,如果你需要访问app.yml里定义的值,见例5-15,你需要例5-16中的代码。 
     489 
     490例 5-15 - `app.yml` 配置文件样本 
    491491 
    492492    all: 
    504504        contact:      dummy@example.com 
    505505 
    506 例 5-16 - Accessing Configuration Settings in PHP in the `dev` Environment 
     506例 5-16 - 在`dev`环境从PHP代码里访问配置信息 
    507507 
    508508    [php] 
    509509    echo sfConfig::get('app_version'); 
    510510     => '1.5' 
    511     echo sfConfig::get('app_tax');   // Remember that category headers are ignored 
     511    echo sfConfig::get('app_tax');   // 请注意分类的头会被忽略掉 
    512512     => '19.6' 
    513513    echo sfConfig::get('app_default_user_name); 
    518518     => 'dummy@example.com' 
    519519 
    520 So symfony configuration settings have all the advantages of PHP constants, but without the disadvantages, since the value can be changed. 
    521  
    522 On that account, the `settings.yml` file, where you can set the framework settings for an application, is the equivalent to a list of `sfConfig::set()` calls. 例 5-17 is interpreted as shown in 例 5-18. 
    523  
    524 例 5-17 - Extract of `settings.yml` 
     520所以symfony的配置信息有所有PHP常量的优点,但是没有PHP常量的缺点,因为symfony配置的值可以改变。 
     521 
     522所以, 用来给应用程序设定框架设置的`settings.yml`文件,相当于一系列的`sfConfig::set()`调用。例 5-17 会被解释为 例 5-18。 
     523 
     524例 5-17 - 不完整的`settings.yml` 
    525525 
    526526    all: 
    531531        url_format:             PATH 
    532532 
    533 例 5-18 - What Symfony Does When Parsing `settings.yml` 
     533例 5-18 - symfony处理`settings.yml`文件的结果 
    534534 
    535535    [php] 
    541541    )); 
    542542 
    543 Refer to Chapter 19 for the meanings of the settings found in the `settings.yml` file. 
     543`settings.yml`文件里面设置的含义请参考第19章。 
    544544 
    545545### 自定义应用程序配置与app.yml Custom Application Settings and app.yml 
    546546 
    547 Most of the settings related to the features of an application should be stored in the `app.yml` file, located in the `myproject/apps/myapp/config/` directory. This file is environment-dependent and empty by default. Put in every setting that you want to be easily changed, and use the `sfConfig` class to access these settings from your code. 例 5-19 shows an example. 
    548  
    549 例 5-19 - Sample `app.yml` to Define Credit Card Operators Accepted for a Given Site 
     547大部分与程序功能有关的设置存放在`app.yml`文件里,这个文件在`myproject/apps/myapp/config/`目录。`app.yml`与环境有关,默认是空的。把所有你需要很容易修改的设置放在这个文件里,在代码里用`sfConfig`类访问它们。如例5-19。 
     548 
     549例 5-19 - 这个`app.yml`给指定的网站定义接受的信用卡类型 
    550550 
    551551    all: 
    559559        fake:             on 
    560560 
    561 To know if the `fake` credit cards are accepted in the current environment, get the value of
     561想要知道前环境是否接受`fake`信用卡,需要这么写代码
    562562 
    563563    [php] 
    565565 
    566566>**TIP** 
    567 >Each time you are tempted to define a constant or a setting in one of your scripts, think about if it would be better located in the app.yml file. This is a very convenient place to store all application settings. 
    568  
    569 When your need for custom parameters becomes hard to handle with the `app.yml` syntax, you may need to define a syntax of your own. In that case, you can store the configuration in a new file, interpreted by a new configuration handler. Refer to Chapter 19 for more information about configuration handlers. 
     567>当你要定义一个常量或者一个设置的时候,考虑一下把它放在app.yml里面会不会更好。在这里存放应用程序配置很方便。 
     568 
     569如果你的自定义参数用`app.yml`的语法难以处理,你可以考虑自己定义一套语法。这样你可以把配置信息存在一个新的文件里,用新的处理者解析配置文件。配置文件处理者的资料详见第19章。 
    570570 
    571571更好的使用配置文件的技巧 Tips for Getting More from Configuration Files 
    572572---------------------------------------------- 
    573573 
    574 There are a few last tricks to learn before writing your own YAML files. They will allow you to avoid configuration duplication and to deal with your own YAML formats. 
     574在开始写你自己的YAML文件之前,有一些最后的技巧需要掌握。这些技巧可以避免配置信息的重复还有处理你自己的YAML格式。 
    575575 
    576576### 在YAML文件里使用常量 Using Constants in YAML Configuration Files 
    577577 
    578 Some configuration settings rely on the value of other settings. To avoid setting the same value twice, symfony supports constants in YAML files. On encountering a setting name (one that can be accessed by `sfConfig::get()`) in capital letters enclosed in `%` signs, the configuration handlers replace them with their current value. See 例 5-20 for an example. 
    579  
    580 例 5-20 - Using Constants in YAML Files, Example from `autoload.yml` 
     578一些配置设定的值取决于其他的设定。为了避免重复设置同样的值,symfony支持在YAML文件里使用常量。如果遇到`%`包起来的大写形式的设定名(可以通过`sfConfig::get()`取得值),配置文件处理者会用这个设定的当前值来替换这个常量。见例5-20。 
     579 
     580例 5-20 - 在YAML文件里使用常量,以`autoload.yml`为例 
    581581 
    582582    autoload: 
    587587        exclude:        [vendor] 
    588588 
    589 The path parameter will take the value returned by sfConfig::get('sf_symfony_lib_dir'). If you want one configuration file to rely on another, you need to make sure that the file you rely on is already parsed (look in the symfony source to find out the order in which the configuration files are parsed). `app.yml` is one of the last files parsed, so you may rely on others in it. 
     589path参数的值会是执行sfConfig::get('sf_symfony_lib_dir')的结果。如果一个配置文件依赖于另一个配置文件,被依赖的配置文件必须先被解析(请查看symfony的源代码来了解配置文件载入的顺序)。`app.yml`是最后被解析的文件之一,所以你可以在这个文件里使用其它文件里定义的设定。 
    590590 
    591591### 在配置文件里使用脚本 Using Scriptable Configuration 
    592592 
    593 It may happen that your configuration relies on external parameters (such as a database or another configuration file). To deal with these particular cases, the symfony configuration files are parsed as PHP files before being passed to the YAML parser. It means that you can put PHP code in YAML files, as in 例 5-21. 
    594  
    595 例 5-21 - YAML Files Can Contain PHP 
     593有可能你的配置信息与外部参数有关(例如数据库或者其他配置文件)。为了解决这种问题,symfony在把配置文件传给YAML处理者之前先用PHP来解析配置文件。这意味着你可以在YAML文件里使用PHP代码,如例5-21。 
     594 
     595例 5-21 - YAML文件可以包含PHP 
    596596 
    597597    all: 
    599599        format:  <?php echo sfConfig::get('sf_i18n') == true ? 'xliff' : 'none' ?> 
    600600 
    601 But be aware that the configuration is parsed very early in the life of a request, so you will not have any symfony built-in methods or functions to help you. 
     601但是请注意配置文件在请求的周期的很早的时候就被处理了,所以你不能使用symfony内建的方法或者函数。 
    602602 
    603603>**CAUTION** 
    604 >In the production environment, the configuration is cached, so the configuration files are parsed (and executed) only once after the cache is cleared. 
     604>在生产环境,配置文件会被缓存,所以配置文件只会在清除缓存后被处理(并执行)一次。 
    605605 
    606606### 浏览你的YAML文件 Browsing Your Own YAML File 
    607607 
    608 Whenever you want to read a YAML file directly, you can use the `sfYaml` class. It is a YAML parser that can turn a YAML file into a PHP associative array. 例 5-22 presents a sample YAML file, and 例 5-23 shows you how to parse it. 
    609  
    610 例 5-22 - Sample `test.yml` File 
     608如果你想直接读取YAML文件,你可以使用`sfYaml`类。它是一个可以把YAML文件转化成PHP数组的YAML解析器。例5-22是一个YAML文件的例子,例5-23是前面YAML文件的解析结果。 
     609 
     610例 5-22 - `test.yml`  
    611611 
    612612    house: 
    621621        zipcode:  12345 
    622622 
    623 例 5-23 - Using the `sfYaml` Class to Turn a YAML File into an Associative Array 
     623例 5-23 - 使用`sfYaml`类把YAML转换成一个数组 
    624624 
    625625    [php] 
    653653------- 
    654654 
    655 The symfony configuration system uses the YAML language to be simple and readable. The ability to deal with multiple environments and to set parameters through a definition cascade offers versatility to the developer. Some of the configuration can be accessed from within the code via the `sfConfig` object, especially the application settings stored in the `app.yml` file. 
    656  
    657 Yes, symfony does have a lot of configuration files, but this approach makes it more adaptable. Remember that you don't need to bother with them unless your application requires a high level of customization. 
     655symfony配置系统使用的YAML语言简单并且可读性强。多种环境与层叠结构的参数定义为开发者提供了多种选择。一些配置文件可以从代码里通过`sfConfig`类访问,特别是`app.yml`里的应用程序配置。 
     656 
     657的确,symfony有很多配置文件,不过这使symfony适用性更强。注意除非你的应用程序需要高级别的定制你根本不需要去修改它们。 
    658658}}}