FrameworkBundle配置信息("framework"根键)

2.8 版本
维护中的版本

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 

值类型: array

配置“应该被信任为代理”的IP地址。更多细节请参考如何配置Symfony才能让它在负载均衡和反向代理背后工作

1
2
3
# app/config/config.yml
framework:
    trusted_proxies:  [192.0.0.1, 10.0.0.0/8]
1
2
3
4
5
6
7
8
9
10
<!-- 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-proxies="192.0.0.1, 10.0.0.0/8" />
</container>
1
2
3
4
// app/config/config.php
$container->loadFromExtension('framework', array(
    'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'),
));

ide 

值类型: string 默认值: null

如果你使用的IDE是TextMate或Mac Vim这种,那么Symfony可以把“一个异常中的所有文件路径”给转成一个link(链接),它可以在你的IDE中打开那个文件。

Symfony中包含了“预置链接”(preconfigured URLs),可以用在那些流行的编辑器中,你可以使用下面的键(key)来配置它们:

  • textmate
  • macvim
  • emacs
  • sublime

你也可以指定一个自定义链接的字符串。如果你要这么做,所有百分号( % )必须使用两次以便转义。例如,如果你在Mac OS上使用PHPStorm,你得像下面这样处理:

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

Tip

如果你在Windows PC上使用编辑器,可以安装 PhpStormProtocol 来使用本功能。

当然,由于每个开发者使用的是不同的IDE,最好的办法还是把它设置到系统级别。这可以通过把 php.ini 配置文件中的 xdebug.file_link_format 设置成URL字符串来实现。

如果你没有用Xdebug,另一种方式是把这个URL字符串设置到 SYMFONY__TEMPLATING__HELPER__CODE__FILE_LINK_FORMAT 环境变量中。如果以上任何一种配置信息中的值被设置, ide 选项将被忽略。


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

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,
    ),
));

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

对于所有设置选项,你都可以把一个参数(configuration 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 同时设置。


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 必填项

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

loader 

值类型: 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的magic __call() method

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。否则,验证器会使用一个简单的正则表达式来验证邮箱地址。


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

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


完整的默认配置 

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
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
 
    # 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
 
    # annotation configuration / annotation配置
    annotations:
        cache:                file
        file_cache_dir:       "%kernel.cache_dir%/annotations"
        debug:                "%kernel.debug%"

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

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