FrameworkBundle配置信息（"framework"根键）

3.4 版本

维护中的版本

难易度：困难

FrameworkBundle包括了多数的“基础”框架功能，并且可以在你的程序配置文件中的 framework 根键下进行配置。当使用XML时，你必须使用 http://symfony.com/schema/dic/symfony 的命名空间。

本文包括session、translation、forms、validation、routing等的相关设置。

Tip

http://symfony.com/schema/dic/symfony/symfony-1.0.xsd 这个XSD schema是可用的。

配置选项 ¶

secret
http_method_override
从 Symfony 3.3 起 trusted_proxies 已被删除
ide
test
default_locale
trusted_hosts
form
- enabled
csrf_protection
- enabled
esi
- enabled
fragments
- enabled
- path
profiler
- enabled
- collect
- only_exceptions
- only_master_requests
- dsn
- matcher
  
  ip
  
  path
  
  service
router
session
assets
templating
translator
- enabled
- fallbacks
- logging
- paths
property_access
- magic_call
- throw_exception_on_invalid_index
validation
annotations
serializer
php_errors
- log
- throw
cache

secret ¶

值类型: string 必填项

这是个字符串，对你的程序来说它是唯一的，一般用于给“安全相关”的操作增加entropy（熵。译注：提高安全性的密串）。它的值应该是由字母、数字和随机符号组成，推荐长度是32个字符。

在程序中，Symfony使用它来生成 CSRF tokens，用于加密用在remember me functionality（“记住我”功能）中的cookies，以及在使用 ESI (Edge Side Includes) 时创建签名URIs。

这个选项对应的是服务容器中名为 kernel.secret 的参数（parameter），你可以在程序“需要不可改变的随机串来增加更多的熵”时使用它。

同其他与security相关的参数一样，一个良好习惯就是每次（初始化程序时）都改变这个值。但是要注意，改变这个值将令所有签名URI（signed URIs）和“记住我”功能失效。这就是为什么要在此值被改变之后，应重新生成程序缓存，并且令程序所有用户log out退出登陆的原因。

http_method_override ¶

值类型: boolean 默认值: true

这个选项决定了_method请求参数（request parameter）是否被刻意用在POST请求中的HTTP method。如果开启，那么 Request::enableHttpMethodParameterOverride 方法会被自动调用。该选项对应的是服务容器中名为kernel.http_method_override的参数。

Note

更多信息请参考如何改变表单的Action和Method。

Caution

如果你使用的是 AppCache反向代理，kernel将忽略 _method 参数，它可能导致错误。

要修复这点，在创建 Request 之前先调用 enableHttpMethodParameterOverride() 方法：

// web/app.php
 
// ...
$kernel = new AppCache($kernel);
 
Request::enableHttpMethodParameterOverride(); // <-- add this line / 添加此行
$request = Request::createFromGlobals();
// ...

trusted_proxies

在Symfony 3.3中 trusted_proxies 已被删除。参考 如何配置Symfony才能让它在负载均衡和反向代理背后工作。

ide ¶

值类型: string 默认值: null

Symfony把变量库和异常信息中可见的文件路径给转换成“能在浏览器中打开”的链接。如果你愿意在自己喜欢的IDE或文本编辑器中打开这些文件，把这个选项设置为以下值: phpstorm, sublime, textmate, macvim 和 emacs。

Note

phpstorm 在MacOS上被PhpStorm原生支持，Windows则需要 PhpStormProtocol 而Linux需要 phpstorm-url-handler。

如果你使用其他编辑器，预期的配置值是一个URL模板，它包括一个 %f 占位符，这是预期的文件路径，以及 %l 占位符，它用于行号 (百分号 (%) 必须使用两次以转义，防止Symfony将其作为容器参数而解析)。

1
2
3

# app/config/config.yml
framework:
    ide: 'myide://open?url=file://%%f&line=%%l'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config ide="myide://open?url=file://%%f&line=%%l" />
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    'ide' => 'myide://open?url=file://%%f&line=%%l',
));

Note

如果 framework.ide 和 xdebug.file_link_format 都被定义了，Symfony使用 framework.ide 选项的值。

Tip

设置 xdebug.file_link_format ini选项，可以在Xdebug extension未开启的情况下工作。

Tip

当你的程序运行在container或virtual machine（虚拟机）时，你可以告诉Symfony，通过改变文件的前缀，来把文件从guest映射到host。此映射在URL模板中应当指明，使用 & 和 > 作为 guest-to-host 分隔符:

// /path/to/guest/.../file will be opened 
// as /path/to/host/.../file on the host 
// and /foo/.../file as /bar/.../file also
'myide://%f:%l&/path/to/guest/>/path/to/host/&/foo/>/bar/&...'

Symfony 3.2： Guest to host 映射从 Symfony 3.2 起被引入。

test ¶

值类型: boolean

如果这个配置选项被指定（并且不是false），那么所有“与你的测试程序相关”的服务（比如test.client）会被加载。本设定应该出现在你的test环境中（通常是 app/config/config_test.yml）。

Seealso

更多信息请参考 Testing 测试）。

default_locale ¶

值类型: string 默认值: en

如果路由参数中的_locale值没有被设置，默认的locale会被使用。可以使用 Request::getDefaultLocale 方法来取到它。

Seealso

关于默认locale的更多信息可参考设置默认的Locale。

trusted_hosts ¶

值类型: array | string 默认值: array()

大量的不同攻击，被揭示出来依靠的是“用不同的软件（web servers，reverse proxies，web frameworks等等）处理 Host 头”时的矛盾。基本上，框架在每次生成绝对URL时（例如当发送“重置密码”的邮件时），host主机可以被攻击者所操纵。

Note

阅读 HTTP Host header attacks 了解更多关于此类攻击的信息。

Symfony的 Request::getHost() 方法，在这类攻击中的某些时候是脆弱的，因为该方法取决于你的web服务器的配置。避免这类攻击的一个简单办法，是把“你的Symfony程序能够予以响应”的主机给添加到白名单中。这就是这个 trusted_hosts 选项的目的所在。如果进入的请求之主机名并不与你白名单中的相匹配，程序将不予响应，用户将收到500响应。

1
2
3

# app/config/config.yml
framework:
    trusted_hosts:  ['example.com', 'example.org']

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <trusted-host>example.com</trusted-host>
        <trusted-host>example.org</trusted-host>
        <!-- ... -->
    </framework>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    'trusted_hosts' => array('example.com', 'example.org'),
));

Hosts也可以通过正则表达式来配置（比如 .*\.?example.com$ ），这能令“响应任意子域名”变得容易。

此外，通过 Request::setTrustedHosts() 方法，你还能在前端控制器中设置trusted hosts：

1 2	// web/app.php Request::setTrustedHosts(array('.\.?example.com$', '.\.?example.org$'));

本选项的默认值是个空数组，意味着程序将不对任何给定的host予以响应。

Seealso

参考安全公告的博客原贴以了解更多。

form ¶

enabled ¶

值类型: boolean 默认值: false

是否在服务容器中启用表单。如果你没有使用表单，可以把它设为 false ，这样会提高程序性能，因为容器会加载较少的服务。

当有子选项被设置时，本选项将被自动设置为 true 。

Note

这将自动开启验证。

Seealso

更多细节请参考表单。

csrf_protection ¶

Seealso

关于表单中的CSRF防护的更多信息，参考如何实现CSRF防护。

enabled ¶

值类型: boolean 默认值: true，如果“表单支持”被开启的话，否则是false。

本选项可用于对全部表单关闭CSRF防护。但是你也可以禁用某一个表单的CSRF防护。

如果你使用了表单，但希望避免开启session（比如在一个API-only的网站中使用表单）， csrf_protection 需要设成 false 才行。

esi ¶

Seealso

阅读使用Edge Side Includes 以了解更多。

enabled ¶

值类型: boolean 默认值: false

是否在框架中开启对edge side includes的支持。

你可以把 esi 选项设为 true 来开启它：

1
2
3

# app/config/config.yml
framework:
    esi: true

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <esi />
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    'esi' => true,
));

fragments ¶

Seealso

参考 HTTP缓存系列以了解更多fragments内容。

enabled ¶

值类型: boolean 默认值: false

是否开启fragment listener。fragment监听用于渲染“独立于页面其他部分”的ESI片断。

当有子项被设置时，本选项将自动设置为 true 。

path ¶

值类型: string 默认值: '/_fragment'

fragments的路径前缀。fragment listener仅当请求“始于此路径”时，才会被执行。

profiler ¶

enabled ¶

值类型: boolean 默认值: false

分析器可以通过设置本选项为 true 来开启。当你使用Symfony标准版时，分析器在 dev 和 test 环境下是开启的。

Note

Profiler（分析器）独立于“web除错工具条”而工作，参考 WebProfilerBundle配置了解如何开启/关闭工具条。

collect ¶

值类型: boolean 默认值: true

这个选项配置的是分析器在开启时的行为方式。如果设为 true ，分析器会收集全部请求的数据（除非你进行了配置，如一个自定义的 matcher）。如果你希望仅收集必要的信息，你可以设置 collect 为 false ，进而手动激活数据收集器（data collectors）：

1	$profiler->enable();

only_exceptions ¶

值类型: boolean 默认值: false

当它被设为 true 时，分析器将仅在“处理请求”的过程中有异常抛出时被开启。

only_master_requests ¶

值类型: boolean 默认值: false

当它被设为 true 时，分析器仅对主请求（master requests）开启（子请求[subrequests]时不开启）。

dsn ¶

值类型: string 默认值: 'file:%kernel.cache_dir%/profiler'

存储“分析信息”（profiling information）的DSN（数据源名称）。

Seealso

参考切换Profiler存储了解更多关于“分析器的信息存储”之信息。

matcher ¶

Matcher选项的配置是为了动态开启profiler。例如，基于ip或path。

Seealso

参考如何使用Matchers来有条件地开启Profiler分析器了解更多相关内容。

ip ¶

值类型: string

如果设置，分析器将仅在当前IP地址匹配时开启。

path ¶

值类型: string

如果设置，分析器将仅在当前路径匹配时开启。

service ¶

值类型: string

这个设置包含的是一个自定义matcher的service id。

router ¶

resource ¶

值类型: string 必填项

这是含有“自身路由和导入路由”的主路由资源（比如一个YAML文件）之加载路径。

type ¶

值类型: string

用于提示加载器“格式”（format）的资源类型。若你以可接受的文件扩展名（.xml, .yml / .yaml, .php）来使用默认路由器的话，本选项并非必须。

http_port ¶

值类型: integer 默认值: 80

普通http请求的端口号（在匹配route scheme时有用）。

https_port ¶

值类型: integer 默认值: 443

https请求的端口号（在匹配route scheme时有用）。

strict_requirements ¶

值类型: mixed 默认值: true

决定路由生成器（generator）的行为。当要生成拥有特殊 requirements 条件）的路由时，生成器在（路由）使用的参数没有遇到到这些条件时，可以做出不同行为。

它的值可以是以下之一：

true: 当条件没有被遇到时，招聘一个异常；
false: 当条件没有被遇到时，禁止抛出异常并返回null；
null: 禁止检查条件（因此，就算条件不匹配时，也要去匹配路由）。

true推荐在开发环境下使用，而false或null 则是生产环境的首选。

session ¶

storage_id ¶

值类型: string 默认值: 'session.storage.native'

用于session storage（session存储）的service id。session.storage服务的假名（alias）将被设置为这个服务id。这个类必须实现 SessionStorageInterface 接口。

handler_id ¶

值类型: string 默认值: 'session.handler.native_file'

用于session storage（session存储）的service id。 session.handler 服务的假名将被设置为这个服务id。

你可以把它设为 null ，这样就能使用你在安装PHP时的默认handler。

Seealso

在如何使用PdoSessionHandler把Session存储到数据库中一文中可以看到相关用例。

name ¶

值类型: string 默认值: null

这个选项指定的是session cookie的名称。默认时，它使用的是 php.ini 中 session.name 指令所定义的cookie名称。

cookie_lifetime ¶

值类型: integer 默认值: null

决定session的lifetime生命周期——以秒计。默认值是 - null - 意味着来自php.ini中的session.cookie_lifetime值将被使用。将这个值设为0表示cookie在浏览器session周期中有效。

cookie_path ¶

值类型: string 默认值: /

本选项决定session cookie的路径。默认是 / 。

cookie_domain ¶

值类型: string 默认值: ''

本选项决定设置在session cookie中的domain。默认是空（blank），意味着就是“根据cookie协议来生成cookie”的服务器之主机名（host name）。

cookie_secure ¶

值类型: boolean 默认值: false

本选项决定cookie是否仅在安全连接（secure connection）条件下发送。

cookie_httponly ¶

值类型: boolean 默认值: true

本选项决定是否仅通过http protocal才可以访问cookies。这意味着cookie不能被脚本语言访问到，比如JavaScript。这项设定可以有效减少“利用XSS攻击”进行ID窃取。

gc_divisor ¶

值类型: integer 默认值: 100

见 gc_probability。

gc_probability ¶

值类型: integer 默认值: 1

本选项决定“垃圾收集器”进程（GC，garbage collector）在每次session初始化时的启动概率。概率通过 gc_probability / gc_divisor 计算出来，比如，1/100就代表每次请求时，有1%的机会GC进程将会启动。

gc_maxlifetime ¶

值类型: integer 默认值: 1440

本选项决定多少秒之后，session数据会被视为“垃圾”并有可能被清理。垃圾收集可能在发生于session启动时，这取决于 gc_divisor 和 gc_probability。

use_strict_mode ¶

值类型: boolean 默认值: false

这是指session模块是否使用严格的session id模式。如果此模式开启，模块不接受未经初始化的session IDs。如果未初始化的session ID被浏览器发出来，一个新的session ID会被送到浏览器。session采纳了严格模式之后，程序会从session fixation（session固定攻击）中受到保护。

save_path ¶

值类型: string 默认值: %kernel.cache_dir%/sessions

本选项决定传入save handler中的参数（arguments）。如果你选择了默认的文件型session handler，这个值就是session文件被创建时的路径所在。更多信息请见配置Session文件的存储目录一文。

你也可以令此选项的值使用你的php.ini中的save_path，将其设为null即可：

# app/config/config.yml
framework:
    session:
        save_path: ~

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:session save-path="null" />
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    'session' => array(
        'save_path' => null,
    ),
));

metadata_update_threshold ¶

值类型: integer 默认值: 0

这是指session元数据在两次更新期间有多少秒。它可以防止session handler在session未更新时进行写入。

Seealso

此选项的用法示例可参考 限制Session元数据写入。

assets ¶

base_path ¶

值类型: string

本选项让你定义一个用于assets资源的基本路径（basic path）：

# app/config/config.yml
framework:
    # ...
    assets:
        base_path: '/images'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:assets base_path="/images" />
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'base_path' => '/images',
    ),
));

base_urls ¶

值类型: array

本选项让你定义用于assets资源的基本链接（basic URLs）。如果提供了多个基本链接，Symfony将在每次生成一个asset路径时，从collection中选择一个：

# app/config/config.yml
framework:
    # ...
    assets:
        base_urls:
            - 'http://cdn.example.com/'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:assets base-url="http://cdn.example.com/" />
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'base_urls' => array('http://cdn.example.com/'),
    ),
));

packages ¶

你可以把资源（assets）打包，来为它们指定不同的基本链接：

# app/config/config.yml
framework:
    # ...
    assets:
        packages:
            avatars:
                base_urls: 'http://static_cdn.example.com/avatars'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:assets>
            <framework:package
                name="avatars"
                base-url="http://static_cdn.example.com/avatars" />
        </framework:assets>
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'packages' => array(
            'avatars' => array(
                'base_urls' => 'http://static_cdn.example.com/avatars',
            ),
        ),
    ),
));

现在你可以在模板中使用 avatars 包：

Twig
PHP

1	<img src="{{ asset('...', 'avatars') }}">

1	<img src="<?php echo $view['assets']->getUrl('...', 'avatars') ?>">

每个包可以配置以下选项：

base_path
base_urls
version_strategy
version
version_format
json_manifest_path

version ¶

值类型: string

本选项通过为所有渲染出（rendered）的资源路径添加一个query parameter，用来打破（bust） assets的缓存（比如 /images/logo.png?v2 ）。这仅适用于通过Twig的 asset 函数（或等价PHP）输出的资源，也适用于用Assetic输出的assets。

例如，假设你有下列资源：

Twig
PHP

1	<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />

1	<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />

默认情况下，这将输出一个路径来对应你的图片，比如 /images/logo.png 这种。现在，激活 version 选项：

# app/config/config.yml
framework:
    # ...
    assets:
        version: 'v2'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <framework:assets version="v2" />
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'version' => 'v2',
    ),
));

现在，如果你使用这个功能，相同的asset将被渲染为 /images/logo.png?v2 ，在每次部署之前，你必须手动增加 version 的值，以便query parameters能够改变。

利用 version_format 选项，你也可以控制query string的工作方式。

Note

本参数不可以与 version_strategy 或 json_manifest_path 同时设置。

Tip

就像所有设置一样，你可以冷静生个参数（parameter）作为 version 的值。这可以令每次部署时的缓存版本增加变得更容易。

verion_format ¶

值类型: string 默认值: %%s?%%s

本选项指定了一个 sprintf pattern，可以和version选项一起用于构建一个asset的路径。默认时，该pattern把asset的版本当作一个query string。例如，如果version_format被设成%%s?version=%%s，同时version被设为5，那么资源路径将为是/images/logo.png?version=5。

Note

所有在格式字符串中出现的百分号（ % ）必须使用两次以进行字符转义。若不转义，其值可能会被当成 Service Parameters 服务参数而被无意中拦截。

Tip

某些CDN并不支持query string（查询字符串）方式的“缓存击破”（cache-busting）。幸运的是， version_format 并不局限于仅仅产生“版本化”的query strings。

这个pattern接收asset的原始路径和版本，分别作为其第一和第二参数。由于asset的路径是一个参数，你不能把它改为“原样（in-place）”（如 /images/logo-v5.png ）；然而，你可以通过 version-%%2$s/%%1$s pattern来为asset路径添加前缀，这会导致一个 version-5/images/logo.png 的路径。

接下来可以用URL rewrite rules（URL重写规则）在提供asset之前，无视版本前缀。另一种方式是，你可以拷贝assets到合适的“版本”路径（version path），作为你部署进程的一个环节，然后忘掉任何URL重写。后者在你需要较老的asset版本以令其“可通过原始URL来访问”时，是有用的。

verion_strategy ¶

值类型: string 默认值: null

应用在资源上的 asset version strategy（资源版本策略）之服务id。

Note

本参数不可以与 version_strategy 或 json_manifest_path 同时设置。

json_manifest_path ¶

值类型: string 默认值: null

3.3： json_manifest_path 从 Symfony 3.3 起被引入。

这个选项指向的是“包含有asset资源名称及其对应的已编译名称的数组”的 manifest.json 文件所在的路径。常见的使用了 "manifest" 文件的 cache-busting（缓存击破）技巧，可以通过常规的前端编译，在assets文件名后面写上一个"hash” (如 main.ae433f1cb.css) 来完成。

Tip

Symfony的 Webpack Encore 支持输出加密assets。还有，它可以同其他许多编译流程混用，包括分别使用了 webpack-manifest-plugin 和 gulp-rev 的Webpack 和 Gulp。

本选项可以全局设置用于所有资源，以及为每一个asset包单独使用：

 # app/config/config.yml
framework:
     assets:
         # this manifest is applied to every asset (including packages)
         # 这个清单适用于每一个asset资源（包括package包）
         json_manifest_path: "%kernel.project_dir%/web/assets/manifest.json"
         packages:
             foo_package:
                 # this package uses its own manifest (the default file is ignored)
                 # 这个包使用了它自己的清单（默认文件被忽略了）
                 json_manifest_path: "%kernel.project_dir%/web/assets/a_different_manifest.json"
             bar_package:
                 # this package uses the global manifest (the default file is used)
                 # 这个包使用了全局的清单（默认文件被使用了）
                 base_path: '/images'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
        <!-- this manifest is applied to every asset (including packages) -->
        <framework:assets json-manifest-path="%kernel.project_dir%/web/assets/manifest.json">
            <!-- this package uses its own manifest (the default file is ignored) -->
            <framework:package
                name="foo_package"
                json-manifest-path="%kernel.project_dir%/web/assets/a_different_manifest.json" />
            <!-- this package uses the global manifest (the default file is used) -->
            <framework:package
                name="bar_package"
                base-path="/images" />
        </framework:assets>
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    'assets' => array(
        // this manifest is applied to every asset (including packages)
        'json_manifest_path' => '%kernel.project_dir%/web/assets/manifest.json',
        'packages' => array(
            'foo_package' => array(
                // this package uses its own manifest (the default file is ignored)
                'json_manifest_path' => '%kernel.project_dir%/web/assets/a_different_manifest.json',
            ),
            'bar_package' => array(
                // this package uses the global manifest (the default file is used)
                'base_path' => '/images',
            ),
        ),
    ),
));

Note

本参数不可以与 version_strategy 或 json_manifest_path 同时设置。此外，在一个全局manifest清单文件被指定时，本选项在package scope（资源范围）上不可以为空（nullified）。

Tip

如果你请求的资源在 not found in the manifest.json 文件中找不到，则原始的 - unmodified - 未修改资源路径（asset path）将被返回。

templating ¶

hinclude_default_template ¶

值类型: string 默认值: null

设置在“加载片断（fragment）”或“JavaScript被禁用”时要显示的内容。本选项既可以是一个模板名称，也可以是模板内容本身。

Seealso

参考如何用hinclude.js嵌入异步内容了解更多。

form ¶

resources ¶

值类型: string[] 默认值: ['FrameworkBundle:Form']

所有用于“表单主题”（form theming）的PHP资源列表。如果你的模板使用的是Twig，本项设置并非必填项，这时请参考表单主题文档。

假设你有自定义的全局表单主题存放在 src/WebsiteBundle/Resources/views/Form，你可以这样配置：

# app/config/config.yml
framework:
    templating:
        form:
            resources:
                - 'WebsiteBundle:Form'

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
    <framework:config>
 
        <framework:templating>
 
            <framework:form>
 
                <framework:resource>WebsiteBundle:Form</framework:resource>
 
            </framework:form>
 
        </framework:templating>
 
    </framework:config>
</container>

// app/config/config.php
$container->loadFromExtension('framework', array(
    'templating' => array(
        'form' => array(
            'resources' => array(
                'WebsiteBundle:Form'
            ),
        ),
    ),
));

Note

来自 FrameworkBundle:Form 的默认表单主题将始终被包容到form resources中。

Seealso

参考全局表单主题以了解更多。

cache ¶

值类型: string

模板缓存目录的路径。若未设置，则缓存被禁用。

Note

当使用Twig模板时，缓存始终由TwigBundle负责处理，而毋须由FrameworkBundle来开启。

engines ¶

值类型: string[] / string 必填项

使用的模板引擎。既可以是一个字符串（只有一个引擎被配置时），也可以是引擎数组。

loaders ¶

值类型: string

模板加载器（templating loaders）的一个service ids数组（或者当只配置一个loader时，是一个字符串）。模板加载器，用于从一个资源（比如一个文件系统或数据库）中找到并加载模板。模板加载器必须实现 LoaderInterface 接口。

translator ¶

enabled ¶

值类型: boolean 默认值: false

是否在服务容器中开启 translator 服务。

fallbacks ¶

值类型: string|array 默认值: array('en')

本选项用于“当前locale的translation key（翻译源的键）没有被找到”这种情形。

Seealso

更多内容请参考翻译。

logging ¶

默认值: true，如果debug模式开启的话；否则是 false。

设为true时，如果translator无法找到给定的键所对应的翻译信息，则一个日志入口（a log entry）会做成。日志被写入了translation channel——如果存在一个“经过locale回滚的翻译源”，将以debug level写入；如果根本找不到可用翻译资源的话，则是以warning level写入。

paths ¶

值类型: array 默认值: []

本选项定义了一个路径数组，翻译组件用来寻找翻译文件。

property_access ¶

magic_call ¶

值类型: boolean 默认值: false

开启本选项时，property_accessor服务在调用getValue()方法时，将使用PHP的 __call() 魔术方法。

throw_exception_on_invalid_index ¶

值类型: boolean 默认值: false

开启本选项时， property_accessor 服务会在你尝试访问数组中的某个“无效索引”（invalid index）时抛出一个异常。

validation ¶

enabled ¶

值类型: boolean 默认值: true，如果表单支持被开启的话；否则是false。

是否开启验证支持。

当有子选项被设置时，本选项将自动被设为 true 。

cache ¶

值类型: string

用于“把类的metadata（元数据）持久化到缓存中”的服务。这个服务实现的是 CacheInterface 接口。

把本选项设置为 validator.mapping.cache.doctrine.apc ，即可使用由Doctrine提供的APC缓存。

enable_annotations ¶

值类型: boolean 默认值: false

如果本选项被开启，可以使用annotations来定义验证约束（validation constraints）。

translation_domain ¶

值类型: string 默认值: validators

用于翻译“验证约束中的错误信息”时的translation domain。

strict_email ¶

值类型: Boolean 默认值: false

如果本选项被开启，Email约束验证器将使用egulias/email-validator。否则，验证器会使用一个简单的正则表达式来验证邮箱地址。

mapping ¶

paths ¶

值类型: array 默认值: []

本选项允许定义一个“文件路径或目录”的数组，程序组件会在这里面寻找附加的验证文件（validation files）。

annotations ¶

cache ¶

值类型: string 默认值: 'file'

本选项取值可以是下列之一：

file: 使用文件系统（filesystem）来缓存annotations。
none: 禁止缓存annotations。
a service id（服务id）: 一个引用了 Doctrine Cache 实现的服务id。

file_cache_dir ¶

值类型: string 默认值: '%kernel.cache_dir%/annotations'

在 annotations.cache 设置为 'file' 时，annotations的缓存文件所在的目录。

debug ¶

值类型: boolean 默认值: %kernel.debug%

是否开启缓存的debug mode。如果开启，缓存将在原始文件发生改变（不管是代码还是annotations）时自动更新。出于性能考虑，推荐在生产环境下关闭debug mode，若你使用默认值则会自动关闭。

serializer ¶

enabled ¶

值类型: boolean 默认值: false

是否在服务容器中开启 serializer 服务。

cache ¶

值类型: string

把类的metadata（元数据）持久化到缓存中的服务。这个服务必须实现 Doctrine\Common\Cache\Cache 接口。

Seealso

更多信息请参考开启元数据缓存。

enable_annotations ¶

值类型: boolean 默认值: false

如果本选项被开启，可以使用annotation来定义序列化群组（serialization groups）。

Seealso

更多信息请参考使用序列化群组的Annotations。

name_converter ¶

值类型: string

2.8 name_converter 选项从 Symfony 2.8 开始被引入。

想要使用的命名转换器（name converter）。CamelCaseToSnakeCaseNameConverter 命名转换器可以通过使用 serializer.name_converter.camel_case_to_snake_case 值来开启。

Seealso

更多信息请参考在序列化和反序列化时转换属性名称。

circular_reference_handler ¶

值类型: string

用作默认的serializer的circular reference handler（循环引用处理器）的服务id。本服务实现的是PHP魔术方法 __invoke($object)。

Seealso

更多信息请参考应对循环引用。

php_errors ¶

log ¶

3.2： log 选项从 Symfony 3.2 起被引入。

值类型: boolean 默认值: false

使用框架程序的logger而不是PHP内置的logger来记录PHP错误信息。

throw ¶

3.2： throw 选项从 Symfony 3.2 起被引入。

值类型: boolean 默认值: %kernel.debug%

把PHP错误以 \ErrorException 实例来抛出。debug.error_handler.throw_at 参数控制阈值（threshold）。

cache ¶

app ¶

值类型: string 默认值: cache.adapter.filesystem

被 cache.app 服务所使用的缓存适配器（cache adapter）。FrameworkBundle自带多个adapter: apcu, doctrine, system, filesystem,psr6 和 redis。

Tip

一开始可能难于理解，为了避免疑惑，牢记所有pools（缓存池）进行的是相同的操作，却是在不同的介质之上被分别适配。从内部讲，一个池，封装的是一个adapter的定义。

system ¶

值类型: string 默认值: cache.adapter.system

被 cache.system 服务所使用的缓存适配器（cache adapter）。

directory ¶

值类型: string 默认值: %kernel.cache_dir%/pools

从 cache.adapter.filesystem adapter (包括 cache.app) 进行继承的服务所使用的缓存目录之路径。

default_doctrine_provider ¶

值类型: string

用作你默认的 Doctrine provider 的服务名称。provider可以作为 cache.doctrine 服务而被使用。

default_psr6_provider ¶

值类型: string

用作你默认的 PSR-6 providerr 的服务名称。它可作为 cache.psr6 服务而被使用。

default_redis_provider ¶

值类型: string 默认值: redis://localhost

从 cache.adapter.filesystem adapter (including cache.app) 进行继承的服务所使用的缓存目录之路径。

pools ¶

值类型: array

框架扩展（framework extension）所创建的 cache pools 缓存池列表。

Seealso

关于pools工作的更多信息，参考缓存池。

name ¶

值类型: prototype

你希望创建的池名称。

Note

你的池名称必须不能是 cache.app 或 cache.system。

adapter ¶

值类型: string 默认值: cache.app

要使用的adaptor名称。你也可以使用你自己的实现（implementation）。

Note

你的服务必须实现 CacheItemPoolInterface 接口。

public ¶

值类型: string 默认值: null

你的服务是否为public。

default_lifetime ¶

值类型: string

你的缓存元素（cache items）的默认时间，以秒计。

provider ¶

值类型: string

当指定的adaptor需要时，用作provider的服务之名称。

clearer ¶

值类型: string

用于清除 PSR-6 缓存的缓存清理器（cache clearer。

Seealso

更多信息请参考 Psr6CacheClearer。

prefix_seed ¶

3.2： prefix_seed 选项从 Symfony 3.2 起被引入。

值类型: string 默认值: null

如果定义此值，它会成为“为cache item的键”所生成的“命名空间”的一部分。一个常用的实践是，使用程序级的独立名称 (如 symfony.com)，因为这可以在把多个程序部署到“共享了相同缓存后端的同一路径（位于不同服务器）”时，避免命名冲突。

在使用 blue/green deployment 策略时这也很有用，总地说来，使用场合是，当你需要抽象出真实的部署路径时 (例如，当离线进行缓存预热时)。

完整的默认配置 ¶

YAML

framework:
    secret:               ~
    http_method_override: true
    trusted_proxies:      []
    ide:                  ~
    test:                 ~
    default_locale:       en

    csrf_protection:
        enabled:              false
 
    # form configuration / 表单配置
    form:
        enabled:              false
        csrf_protection:
            enabled:          true
            field_name:       ~
 
    # esi configuration / esi配置
    esi:
        enabled:              false
 
    # fragments configuration / fragments配置
    fragments:
        enabled:              false
        path:                 /_fragment
 
    # profiler configuration  / 分析器配置
    profiler:
        enabled:              false
        collect:              true
        only_exceptions:      false
        only_master_requests: false
        dsn:                  file:%kernel.cache_dir%/profiler
        matcher:
            ip:                   ~
 
            # use the urldecoded format  / 使用经urldecode解码的格式
            path:                 ~ # Example: ^/path to resource/
            service:              ~
 
    # router configuration  / 路由配置
    router:
        resource:             ~ # Required
        type:                 ~
        http_port:            80
        https_port:           443
 
        # * set to true to throw an exception when a parameter does not
        #   match the requirements
        # * 设为true的话，当路由参数无法匹配条件时，会抛出异常
        # * set to false to disable exceptions when a parameter does not
        #   match the requirements (and return null instead)
        # * 设为false的话，若路由参数无法匹配条件，则会关闭异常（返回null来替代）
        # * set to null to disable parameter checks against requirements
        # * 设为null的话，将关闭参数之于需求的检查
        #
        # 'true' is the preferred configuration in development mode, while
        # 'false' or 'null' might be preferred in production
        # 'true'为开发环境下的首选配置，而'false'或'null'在生产环境下可能是首选
        strict_requirements:  true
 
    # session configuration / session配置
    session:
        storage_id:           session.storage.native
        handler_id:           session.handler.native_file
        name:                 ~
        cookie_lifetime:      ~
        cookie_path:          ~
        cookie_domain:        ~
        cookie_secure:        ~
        cookie_httponly:      ~
        gc_divisor:           ~
        gc_probability:       ~
        gc_maxlifetime:       ~
        save_path:            "%kernel.cache_dir%/sessions"
 
    # serializer configuration / serializer配置
    serializer:
       enabled:                   false
       cache:                      ~
       name_converter:             ~
       circular_reference_handler: ~
 
    # assets configuration / assets配置
    assets:
        base_path:          ~
        base_urls:          []
        version:            ~
        version_format:     "%%s?%%s"
        packages:

            # Prototype / 原型
            name:
                base_path:            ~
                base_urls:            []
                version:              ~
                version_format:       "%%s?%%s"
 
    # templating configuration / 模板配置
    templating:
        hinclude_default_template:  ~
        form:
            resources:

                # Default: / 默认
                - FrameworkBundle:Form
        cache:                ~
        engines:              # Required
 
            # Example:
            - twig
        loaders:              []
 
    # translator configuration / translator配置
    translator:
        enabled:              false
        fallbacks:            [en]
        logging:              "%kernel.debug%"
        paths:                []
 
    # validation configuration / validation验证配置
    validation:
        enabled:              false
        cache:                ~
        enable_annotations:   false
        translation_domain:   validators
        mapping:
            paths:            []
 
    # annotation configuration / annotation配置
    annotations:
        cache:                file
        file_cache_dir:       "%kernel.cache_dir%/annotations"
        debug:                "%kernel.debug%"
 
    # PHP errors handling configuration
    php_errors:
        log:                  false
        throw:                "%kernel.debug%"
 
    # cache configuration / 缓存配置
    cache:
        app: cache.app
        system: cache.system
        directory: "%kernel.cache_dir%/pools"
        default_doctrine_provider: ~
        default_psr6_provider: ~
        default_redis_provider: "redis://localhost"
        pools:
            # Prototype / 原型
            name:
                adapter: cache.app
                public: false
                default_lifetime: ~
                provider: ~
                clearer: ~

本文，包括例程代码在内，采用的是 Creative Commons BY-SA 3.0 创作共用授权。

登录symfonychina 发表评论或留下问题（我们会尽量回复）

文章目录

FrameworkBundle配置信息（"framework"根键）

配置选项 ¶

secret ¶

http_method_override ¶

trusted_proxies

ide ¶

test ¶

default_locale ¶

trusted_hosts ¶

form ¶

enabled ¶

csrf_protection ¶

enabled ¶

esi ¶

enabled ¶

fragments ¶

enabled ¶

path ¶

profiler ¶

enabled ¶

collect ¶

only_exceptions ¶

only_master_requests ¶

dsn ¶

matcher ¶

ip ¶

path ¶

service ¶

router ¶

resource ¶

type ¶

http_port ¶

https_port ¶

strict_requirements ¶

session ¶

storage_id ¶

handler_id ¶

name ¶

cookie_lifetime ¶

cookie_path ¶

cookie_domain ¶

cookie_secure ¶

cookie_httponly ¶

gc_divisor ¶

gc_probability ¶

gc_maxlifetime ¶

use_strict_mode ¶

save_path ¶

metadata_update_threshold ¶

assets ¶

base_path ¶

base_urls ¶

packages ¶

version ¶

verion_format ¶

verion_strategy ¶

json_manifest_path ¶

templating ¶

hinclude_default_template ¶

form ¶

resources ¶

cache ¶

engines ¶

loaders ¶

translator ¶

enabled ¶

fallbacks ¶

logging ¶

paths ¶

property_access ¶

magic_call ¶

throw_exception_on_invalid_index ¶

validation ¶

enabled ¶

cache ¶

enable_annotations ¶

translation_domain ¶

strict_email ¶

mapping ¶