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 

值类型: 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() 方法:

1
2
3
4
5
6
7
8
// 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, macvimemacs

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'
1
2
3
4
5
6
7
8
9
10
11
<!-- 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>
1
2
3
4
// app/config/config.php
$container->loadFromExtension('framework', array(
    'ide' => 'myide://open?url=file://%%f&line=%%l',
));

Note

如果 framework.idexdebug.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 分隔符:

1
2
3
4
// /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']
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!-- 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>
1
2
3
4
// 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
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
// 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标准版时,分析器在 devtest 环境下是开启的。

Note

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

collect 

值类型: boolean 默认值: true

这个选项配置的是分析器在开启时的行为方式。如果设为 true ,分析器会收集全部请求的数据(除非你进行了配置,如一个自定义的 matcher)。如果你希望仅收集必要的信息,你可以设置 collectfalse ,进而手动激活数据收集器(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。例如,基于ippath

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推荐在开发环境下使用,而falsenull 则是生产环境的首选。


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.inisession.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_divisorgc_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即可:

1
2
3
4
# app/config/config.yml
framework:
    session:
        save_path: ~
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
5
6
// 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):

1
2
3
4
5
# app/config/config.yml
framework:
    # ...
    assets:
        base_path: '/images'
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
5
6
7
// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'base_path' => '/images',
    ),
));

base_urls 

值类型: array

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

1
2
3
4
5
6
# app/config/config.yml
framework:
    # ...
    assets:
        base_urls:
            - 'http://cdn.example.com/'
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
5
6
7
// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'base_urls' => array('http://cdn.example.com/'),
    ),
));

packages 

你可以把资源(assets)打包,来为它们指定不同的基本链接:

1
2
3
4
5
6
7
# app/config/config.yml
framework:
    # ...
    assets:
        packages:
            avatars:
                base_urls: 'http://static_cdn.example.com/avatars'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<!-- 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>
1
2
3
4
5
6
7
8
9
10
11
// app/config/config.php
$container->loadFromExtension('framework', array(
    // ...
    'assets' => array(
        'packages' => array(
            'avatars' => array(
                'base_urls' => 'http://static_cdn.example.com/avatars',
            ),
        ),
    ),
));

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

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

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

version 

值类型: string

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

例如,假设你有下列资源:

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 选项:

1
2
3
4
5
# app/config/config.yml
framework:
    # ...
    assets:
        version: 'v2'
1
2
3
4
5
6
7
8
9
10
11
12
<!-- 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>
1
2
3
4
5
6
7
// 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_strategyjson_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_strategyjson_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-plugingulp-rev 的Webpack 和 Gulp。

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 # 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'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!-- 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>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 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_strategyjson_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,你可以这样配置:

1
2
3
4
5
6
# app/config/config.yml
framework:
    templating:
        form:
            resources:
                - 'WebsiteBundle:Form'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!-- 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>
1
2
3
4
5
6
7
8
9
10
// 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,psr6redis

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.appcache.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 策略时这也很有用,总地说来,使用场合是,当你需要抽象出真实的部署路径时 (例如,当离线进行缓存预热时)。

完整的默认配置 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
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 发表评论或留下问题(我们会尽量回复)