框架配置参考 (FrameworkBundle)

编辑此页

FrameworkBundle 定义了主要的框架配置，从会话（sessions）和翻译到表单（forms）、验证、路由等等。所有这些选项都在应用程序配置的 framework 键下配置。

        1
2
3
4
5
        # displays the default config values defined by Symfony
$ php bin/console config:dump-reference framework

# displays the actual config values used by your application
$ php bin/console debug:config framework
    

提示

当使用 XML 时，你必须使用 http://symfony.ac.cn/schema/dic/symfony 命名空间，相关的 XSD 模式可在以下网址找到：http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd

配置

secret

类型: string 必需

这是一个对你的应用程序来说应该是唯一的字符串，通常用于为安全相关操作增加更多熵。它的值应该是一系列随机选择的字符、数字和符号，建议长度约为 32 个字符。

在实践中，Symfony 使用此值来加密记住我功能中使用的 Cookie，以及在使用 ESI (Edge Side Includes) 时创建签名的 URI。这就是为什么你应该像对待敏感凭据一样对待此值，并且永远不要公开它。

此选项将成为名为 kernel.secret 的服务容器参数，你可以在应用程序需要不可变的随机字符串以增加更多熵时使用它。

与任何其他安全相关的参数一样，最好不时更改此值。但是，请记住，更改此值将使所有签名的 URI 和“记住我”Cookie 失效。这就是为什么在更改此值后，你应该重新生成应用程序缓存并注销所有应用程序用户。

handle_all_throwables

类型: boolean 默认值: true

当设置为 true 时，Symfony 内核将捕获应用程序抛出的所有 \Throwable 异常，并将它们转换为 HTTP 响应。

http_cache

调试

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

如果为 true，则在出现错误时抛出异常。否则，缓存将尝试继续并传递有意义的响应。

trace_level

类型: string 可能的值: 'none', 'short' 或 'full'

对于 'short'，主请求的简明跟踪将作为 HTTP 标头添加。 'full' 将为所有请求（包括 ESI 子请求）添加跟踪。（默认值：在调试模式下为 'full'；否则为 'none'）

trace_header

类型: string

用于跟踪的标头名称。（默认值：X-Symfony-Cache）

default_ttl

类型: integer

当响应中未提供显式新鲜度信息时，缓存条目应被视为新鲜的秒数。显式的 Cache-Control 或 Expires 标头会覆盖此值。（默认值：0）

private_headers

类型: array

触发响应上的“private”缓存控制行为的请求标头集，这些响应未明确声明响应是公共的还是私有的（通过 Cache-Control 指令）。（默认值：Authorization 和 Cookie）

skip_response_headers

类型: array 默认值: Set-Cookie

即使响应可缓存且为公共的，也永远不会缓存的响应标头集。

allow_reload

类型: string

指定客户端是否可以通过在请求中包含 Cache-Control "no-cache" 指令来强制缓存重新加载。为了符合 RFC 2616，请将其设置为 true。（默认值：false）

allow_revalidate

类型: string

指定客户端是否可以通过在请求中包含 Cache-Control "max-age=0" 指令来强制缓存重新验证。为了符合 RFC 2616，请将其设置为 true。（默认值：false）

stale_while_revalidate

类型: integer

指定缓存可以立即返回陈旧响应的默认秒数（粒度为秒，因为 Response TTL 精度为秒），同时在后台重新验证它（默认值：2）。此设置被 stale-while-revalidate HTTP Cache-Control 扩展（参见 RFC 5861）覆盖。

stale_if_error

类型: integer

指定遇到错误时缓存可以提供陈旧响应的默认秒数（粒度为秒）（默认值：60）。此设置被 stale-if-error HTTP Cache-Control 扩展（参见 RFC 5861）覆盖。

http_method_override

类型: boolean 默认值: false

这决定了 _method 请求参数是否在 POST 请求中用作预期的 HTTP 方法。如果启用，Request::enableHttpMethodParameterOverride 方法会被自动调用。它将成为名为 kernel.http_method_override 的服务容器参数。

另请参阅

更改 Symfony 表单的 Action 和 HTTP 方法。

警告

如果你正在使用 HttpCache 反向代理和此选项，内核将忽略 _method 参数，这可能会导致错误。

要解决此问题，请在创建 Request 对象之前调用 enableHttpMethodParameterOverride() 方法

        1
2
3
4
5
6
7
8
        // public/index.php

// ...
$kernel = new CacheKernel($kernel);

Request::enableHttpMethodParameterOverride(); // <-- add this line
$request = Request::createFromGlobals();
// ...
    

trust_x_sendfile_type_header

类型: boolean 默认值: %env(bool:default::SYMFONY_TRUST_X_SENDFILE_TYPE_HEADER)%

7.2

在 Symfony 7.2 中，此选项的默认值已从 false 更改为存储在 SYMFONY_TRUST_X_SENDFILE_TYPE_HEADER 环境变量中的值。

X-Sendfile 是一个特殊的 HTTP 标头，它告诉 Web 服务器用该标头中定义的文件替换响应内容。这提高了性能，因为文件不再由你的应用程序提供服务，而是直接由 Web 服务器提供服务。

此配置选项决定是否信任 x-sendfile 标头用于 BinaryFileResponse。如果启用，Symfony 会自动调用 BinaryFileResponse::trustXSendfileTypeHeader 方法。它将成为名为 kernel.trust_x_sendfile_type_header 的服务容器参数。

trusted_headers

trusted_headers 选项用于配置在负载均衡器或反向代理后面运行 Symfony 时应信任哪些客户端信息（例如，它们的主机）。请参阅如何配置 Symfony 以在负载均衡器或反向代理后面工作。

trusted_proxies

trusted_proxies 选项是必需的，以便在负载均衡器或反向代理后面运行 Symfony 时获取关于客户端的精确信息（例如，它们的 IP 地址）。请参阅如何配置 Symfony 以在负载均衡器或反向代理后面工作。

ide

类型: string 默认值: %env(default::SYMFONY_IDE)%

Symfony 将变量转储和异常消息中看到的文件路径转换为链接，这些链接可以在你的浏览器中直接打开这些文件。如果你希望在你最喜欢的 IDE 或文本编辑器中打开这些文件，请将此选项设置为以下任何值：phpstorm、sublime、textmate、macvim、emacs、atom 和 vscode。

提示

phpstorm 选项在 macOS 和 Windows 上的 PhpStorm 中原生支持；Linux 需要安装 phpstorm-url-handler。

如果你使用其他编辑器，则预期的配置值是 URL 模板，其中包含期望文件路径的 %f 占位符和行号的 %l 占位符（百分号 (%) 必须通过加倍来转义，以防止 Symfony 将它们解释为容器参数）。

        1
2
3
        # config/packages/framework.yaml
framework:
    ide: 'myide://open?url=file://%%f&line=%%l'
    

        1
2
3
4
5
6
7
8
9
10
11
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config ide="myide://open?url=file://%%f&line=%%l"/>
</container>
    

        1
2
3
4
5
6
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->ide('myide://open?url=file://%%f&line=%%l');
};
    

由于每个开发者都使用不同的 IDE，因此启用此功能的推荐方法是在系统级别配置它。首先，你可以在 SYMFONY_IDE 环境变量中定义此选项，当未设置 framework.ide 配置时，Symfony 会自动读取该变量。

另一种选择是在你的 php.ini 配置文件中设置 xdebug.file_link_format 选项。要使用的格式与 framework.ide 选项相同，但无需通过加倍来转义百分号 (%)

        1
2
3
4
5
6
7
8
        // example for PhpStorm
xdebug.file_link_format="phpstorm://open?file=%f&line=%l"

// example for PhpStorm with Jetbrains Toolbox
xdebug.file_link_format="jetbrains://phpstorm/navigate/reference?project=example&path=%f:%l"

// example for Sublime Text
xdebug.file_link_format="subl://open?url=file://%f&line=%l"
    

提示

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

提示

即使未启用 Xdebug 扩展，设置 xdebug.file_link_format ini 选项也有效。

提示

当在容器或虚拟机中运行你的应用时，你可以通过更改文件的前缀来告诉 Symfony 将文件从访客映射到主机。此映射应在使用 & 和 > 作为访客到主机分隔符的 URL 模板末尾指定

        1
2
3
4
5
6
7
        // /path/to/guest/.../file will be opened
// as /path/to/host/.../file on the host
// and /var/www/app/ as /projects/my_project/ also
'myide://%%f:%%l&/path/to/guest/>/path/to/host/&/var/www/app/>/projects/my_project/&...'

// example for PhpStorm
'phpstorm://open?file=%%f&line=%%l&/var/www/app/>/projects/my_project/'
    

test

类型: boolean

如果存在此配置设置（且不为 false），则会加载与测试你的应用程序相关的服务（例如 test.client）。此设置应存在于你的 test 环境中（通常通过 config/packages/test/framework.yaml）。

另请参阅

有关更多信息，请参阅测试。

default_locale

类型: string 默认值: en

如果未设置 _locale 路由参数，则使用默认区域设置。它可通过 Request::getDefaultLocale 方法获得。

另请参阅

你可以在翻译中阅读有关默认区域设置的更多信息。

enabled_locales

类型: array 默认值: [] (空数组 = 启用所有区域设置)

默认情况下，Symfony 应用程序会为所有区域设置生成验证和安全消息的翻译文件。如果你的应用程序仅使用某些区域设置，请使用此选项来限制 Symfony 生成的文件并稍微提高性能

        1
2
3
        # config/packages/translation.yaml
framework:
    enabled_locales: ['en', 'es']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        <!-- config/packages/translation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <enabled-locale>en</enabled-locale>
        <enabled-locale>es</enabled-locale>
    </framework:config>
</container>
    

        1
2
3
4
5
6
        // config/packages/translation.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->enabledLocales(['en', 'es']);
};
    

定义启用的区域设置的一个额外好处是，它们会自动添加为特殊 _locale 参数的要求。例如，如果你将此值定义为 ['ar', 'he', 'ja', 'zh']，则 _locale 路由参数将具有 ar|he|ja|zh 要求。如果某些用户使用未包含在此选项中的区域设置发出请求，他们将看到 404 错误。

set_content_language_from_locale

类型: boolean 默认值: false

如果此选项设置为 true，则响应将包含一个 Content-Language HTTP 标头，并设置为 Request 区域设置。

set_locale_from_accept_language

类型: boolean 默认值: false

如果此选项设置为 true，则 Request 区域设置将自动设置为 Accept-Language HTTP 标头的值。

当传递 _locale 请求属性时，Accept-Language 标头将被忽略。

disallow_search_engine_index

类型: boolean 默认值: 当调试模式启用时为 true，否则为 false。

如果为 true，Symfony 会向所有响应添加 X-Robots-Tag: noindex HTTP 标签（除非您自己的应用程序添加了该标头，在这种情况下不会修改）。这个 X-Robots-Tag HTTP 标头告诉搜索引擎不要索引您的网站。此选项是一种保护措施，以防您意外以调试模式发布您的网站。

trusted_hosts

类型: array | string 默认值: ['%env(default::SYMFONY_TRUSTED_HOSTS)%']

7.2

在 Symfony 7.2 中，此选项的默认值已从 [] 更改为存储在 SYMFONY_TRUSTED_HOSTS 环境变量中的值。

许多不同的攻击已被发现依赖于各种软件（Web 服务器、反向代理、Web 框架等）处理 Host 标头的不一致性。基本上，每次框架生成绝对 URL（例如，在发送电子邮件以重置密码时），主机都可能被攻击者操纵。

另请参阅

您可以阅读 HTTP Host 标头攻击以获取有关这些类型攻击的更多信息。

Symfony Request::getHost() 方法可能容易受到其中一些攻击的影响，因为它取决于您的 Web 服务器的配置。避免这些攻击的一个简单解决方案是配置您的 Symfony 应用程序可以响应的主机列表。这就是 trusted_hosts 选项的目的。如果传入请求的主机名与此列表中的正则表达式之一不匹配，则应用程序将不会响应，并且用户将收到 400 响应。

        1
2
3
        # config/packages/framework.yaml
framework:
    trusted_hosts:  ['^example\.com$', '^example\.org$']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:trusted-host>^example\.com$</framework:trusted-host>
        <framework:trusted-host>^example\.org$</framework:trusted-host>
        <!-- ... -->
    </framework:config>
</container>
    

        1
2
3
4
5
6
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->trustedHosts(['^example\.com$', '^example\.org$']);
};
    

主机也可以配置为响应任何子域，例如通过 ^(.+\.)?example\.com$。

此外，您还可以在前端控制器中使用 Request::setTrustedHosts() 方法设置受信任的主机

        1
2
        // public/index.php
Request::setTrustedHosts(['^(.+\.)?example\.com$', '^(.+\.)?example\.org$']);
    

此选项的默认值是一个空数组，这意味着应用程序可以响应任何给定的主机。

另请参阅

在安全公告博客文章中阅读有关此内容的更多信息。

form

启用

类型: boolean 默认值: true 或 false，具体取决于您的安装

是否在服务容器中启用表单服务。如果您不使用表单，则将此项设置为 false 可能会提高应用程序的性能，因为加载到容器中的服务会减少。

当配置其中一个子设置时，此选项将自动设置为 true。

提示

这将自动启用验证。

另请参阅

有关更多详细信息，请参阅表单。

field_name

类型: string 默认值: _token

这是您应该为表单的 CSRF 令牌字段提供的字段名称。

csrf_protection

另请参阅

有关 CSRF 保护的更多信息，请参阅如何实现 CSRF 保护。

启用

类型: boolean 默认值: true 或 false，具体取决于您的安装

此选项可用于禁用所有表单上的 CSRF 保护。但是您也可以禁用单个表单上的 CSRF 保护。

        1
2
3
4
        # config/packages/framework.yaml
framework:
    # ...
    csrf_protection: true
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony
        http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">
    <framework:config>
        <framework:csrf-protection enabled="true"/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;
return static function (FrameworkConfig $framework): void {
    $framework->csrfProtection()
        ->enabled(true)
    ;
};
    

如果您正在使用表单，但想要避免启动会话（例如，在仅 API 的网站中使用表单），则 csrf_protection 需要设置为 false。

error_controller

类型: string 默认值: error_controller

这是在您的应用程序中的任何位置抛出异常时调用的控制器。默认控制器（ErrorController）在不同的错误条件下呈现特定的模板（请参阅如何自定义错误页面）。

esi

另请参阅

您可以在使用 Edge Side Includes 中阅读有关 Edge Side Includes (ESI) 的更多信息。

启用

类型: boolean 默认值: false

是否在框架中启用 edge side includes 支持。

您还可以将 esi 设置为 true 以启用它

        1
2
3
        # config/packages/framework.yaml
framework:
    esi: true
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:esi/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->esi()->enabled(true);
};
    

fragments

另请参阅

在 HTTP 缓存文章中了解有关片段的更多信息。

启用

类型: boolean 默认值: false

是否启用片段侦听器。片段侦听器用于独立于页面的其余部分呈现 ESI 片段。

当配置其中一个子设置时，此设置会自动设置为 true。

hinclude_default_template

类型: string 默认值: null

设置在片段加载期间或 JavaScript 被禁用时显示的内容。这可以是模板名称或内容本身。

另请参阅

有关 hinclude 的更多信息，请参阅创建和使用模板。

path

类型: string 默认值: /_fragment

片段的路径前缀。仅当请求以此路径开头时，才会执行片段侦听器。

http_client

当安装 HttpClient 组件后，HTTP 客户端将作为名为 http_client 的服务或使用自动装配别名 HttpClientInterface 提供。

可以使用 framework.http_client.default_options 配置此服务

        1
2
3
4
5
6
7
8
        # config/packages/framework.yaml
framework:
    # ...
    http_client:
        max_host_connections: 10
        default_options:
            headers: { 'X-Powered-By': 'ACME App' }
            max_redirects: 7
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:http-client max-host-connections="10">
            <framework:default-options max-redirects="7">
                <framework:header name="X-Powered-By">ACME App</framework:header>
            </framework:default-options>
        </framework:http-client>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
        // config/packages/framework.php
$container->loadFromExtension('framework', [
    'http_client' => [
        'max_host_connections' => 10,
        'default_options' => [
            'headers' => [
                'X-Powered-By' => 'ACME App',
            ],
            'max_redirects' => 7,
        ],
    ],
]);
    

        1
2
3
4
5
6
        $client = HttpClient::create([
    'headers' => [
        'X-Powered-By' => 'ACME App',
    ],
    'max_redirects' => 7,
], 10);
    

可以定义多个预配置的 HTTP 客户端服务，每个服务的服务名称都定义为 scoped_clients 下的键。范围客户端继承为 http_client 服务定义的默认选项。您可以覆盖这些选项，并可以定义一些其他选项

        1
2
3
4
5
6
7
8
        # config/packages/framework.yaml
framework:
    # ...
    http_client:
        scoped_clients:
            my_api.client:
                auth_bearer: secret_bearer_token
                # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:http-client>
            <framework:scoped-client name="my_api.client" auth-bearer="secret_bearer_token"/>
        </framework:http-client>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/framework.php
$container->loadFromExtension('framework', [
    'http_client' => [
        'scoped_clients' => [
            'my_api.client' => [
                'auth_bearer' => 'secret_bearer_token',
                // ...
            ],
        ],
    ],
]);
    

        1
2
3
4
        $client = HttpClient::createForBaseUri('https://...', [
    'auth_bearer' => 'secret_bearer_token',
    // ...
]);
    

为范围客户端定义的选项仅适用于与其 base_uri 或 scope 选项（如果已定义）匹配的 URL。不匹配的 URL 始终使用默认选项。

每个范围客户端还定义了一个相应的命名自动装配别名。例如，如果您使用 Symfony\Contracts\HttpClient\HttpClientInterface $myApiClient 作为参数的类型和名称，则自动装配会将 my_api.client 服务注入到您的自动装配类中。

auth_basic

类型: string

用于创建 HTTP 基本身份验证中使用的 Authorization HTTP 标头的用户名和密码。此选项的值必须遵循 username:password 格式。

auth_bearer

类型: string

用于创建 HTTP Bearer 身份验证（也称为令牌身份验证）中使用的 Authorization HTTP 标头的令牌。

auth_ntlm

类型: string

用于创建 Microsoft NTLM 身份验证协议中使用的 Authorization HTTP 标头的用户名和密码。此选项的值必须遵循 username:password 格式。此身份验证机制需要使用基于 cURL 的传输。

base_uri

类型: string

URI，它合并到相对 URI 中，遵循 RFC 3986 标准中解释的规则。当您发出的所有请求都共享一个公共前缀（例如 https://api.github.com/）时，这很有用，因此您可以避免将其添加到每个请求中。

以下是一些关于 base_uri 合并在实践中如何工作的常见示例

`base_uri`	相对 URI	实际请求的 URI
http://example.org	/bar	http://example.org/bar
http://example.org/foo	/bar	http://example.org/bar
http://example.org/foo	bar	http://example.org/bar
http://example.org/foo/	/bar	http://example.org/bar
http://example.org/foo/	bar	http://example.org/foo/bar
http://example.org	http://symfony.ac.cn	http://symfony.ac.cn
http://example.org/?bar	bar	http://example.org/bar
http://example.org/api/v4	/bar	http://example.org/bar
http://example.org/api/v4/	/bar	http://example.org/bar
http://example.org/api/v4	bar	http://example.org/api/bar
http://example.org/api/v4/	bar	http://example.org/api/v4/bar

bindto

类型: string

网络接口名称、IP 地址、主机名或 UNIX 套接字，用作传出网络接口。

buffer

类型: boolean | Closure

缓冲响应意味着您可以多次访问其内容，而无需再次执行请求。当响应的内容类型为 text/*、application/json 或 application/xml 时，默认启用缓冲。

如果此选项是布尔值，则当值为 true 时，将缓冲响应。如果此选项是闭包，则当返回值为 true 时，将缓冲响应（闭包接收包含响应标头的数组作为参数）。

cafile

类型: string

证书颁发机构文件的路径，该文件包含一个或多个用于验证其他服务器证书的证书。

ciphers

类型: string

TLS 连接允许的密码名称列表。它们可以用冒号、逗号或空格分隔（例如 'RC4-SHA:TLS13-AES-128-GCM-SHA256'）。

crypto_method

类型: integer

要接受的 TLS 的最低版本。该值必须是 PHP 定义的 STREAM_CRYPTO_METHOD_TLSv*_CLIENT 常量之一。

delay

类型: integer 默认值: 1000

用于计算重试之间等待时间的初始延迟（以毫秒为单位）。

启用

类型: boolean 默认值: false

是否启用对重试失败的 HTTP 请求的支持。当配置其中一个子设置时，此设置会自动设置为 true。

extra

类型: array

要传递给 HTTP 客户端以供进一步使用的任意附加数据。当修饰现有客户端时，这尤其有用。

headers

类型: array

在发出请求之前添加的 HTTP 标头的关联数组。此值必须使用 ['header-name' => 'value0, value1, ...'] 格式。

http_codes

类型: array 默认值: DEFAULT_RETRY_STATUS_CODES()

触发请求重试的 HTTP 状态代码列表。

http_version

类型: string | null 默认值: null

要使用的 HTTP 版本，通常为 '1.1' 或 '2.0'。将其保留为 null 以便 Symfony 自动选择最佳版本。

jitter

类型: float 默认值: 0.1（必须介于 0.0 和 1.0 之间）

此选项为延迟添加一些随机性。这对于避免在完全相同的时间向服务器发送多个请求很有用。随机性计算为 delay * jitter。例如：如果延迟为 1000ms 且抖动为 0.2，则实际延迟将是 800 和 1200 之间的数字 (1000 +/- 20%)。

local_cert

类型: string

包含 HTTP 客户端使用的 PEM 格式证书的文件路径。这通常与 local_pk 和 passphrase 选项结合使用。

local_pk

类型: string

包含 local_cert 选项中定义的证书的 PEM 格式私钥的文件路径。

max_delay

类型: integer 默认值: 0

重试之间等待的最长初始毫秒数。使用 0 不限制持续时间。

max_duration

类型: float 默认值: 0

允许请求和响应花费的最长执行时间，以秒为单位。小于或等于 0 的值表示不受限制。

max_host_connections

类型: integer 默认值: 6

定义同时打开到单个主机的最大连接数（将“主机”视为与“主机名 + 端口号”对相同）。此限制也适用于代理连接，其中代理被视为应用此限制的主机。

max_redirects

类型: integer 默认值: 20

要遵循的最大重定向数。使用 0 不跟随任何重定向。

max_retries

类型: integer 默认值: 3

失败请求的最大重试次数。当达到最大值时，客户端返回最后收到的响应。

multiplier

类型: float 默认值: 2

此值在每次重试发生时乘以延迟，以便在时间上分布重试，而不是按顺序进行所有重试。

no_proxy

类型: string | null 默认值: null

不需要代理即可访问的主机的逗号分隔列表，即使配置了代理也是如此。使用 '*' 通配符匹配所有主机，使用空字符串匹配无（禁用代理）。

passphrase

类型: string

用于加密存储在 local_cert 选项中定义的文件中的证书的密码。

peer_fingerprint

类型: array

当协商 TLS 连接时，服务器会发送一个证书来指示其身份。从此证书中提取公钥，如果它与此选项中提供的任何公钥不完全匹配，则在发送或接收任何数据之前中止连接。

此选项的值是 algorithm => hash 的关联数组（例如 ['pin-sha256' => '...']）。

proxy

类型: string | null

用于发出请求的 HTTP 代理。将其保留为 null 以根据您的系统配置自动检测代理。

query

类型: array

在发出请求之前添加到 URL 的查询字符串值的关联数组。此值必须使用 ['parameter-name' => parameter-value, ...] 格式。

rate_limiter

类型: string

用于限制一定时期内 HTTP 请求数量的速率限制器的服务 ID。该服务必须实现 LimiterInterface。

7.1

rate_limiter 选项是在 Symfony 7.1 中引入的。

resolve

类型: array

主机名及其 IP 地址的列表，用于预先填充 HTTP 客户端使用的 DNS 缓存，以避免对这些主机进行 DNS 查找。当在 URL 传递给客户端之前检查 IP 时，此选项对于提高安全性很有用，并且可以使您的测试更容易。

此选项的值是 domain => IP address 的关联数组（例如 ['symfony.com' => '46.137.106.254', ...]）。

retry_failed

类型: array

此选项配置 HTTP 客户端在某些请求失败时的行为，包括要重试的请求类型和重试次数。行为由以下选项定义

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        # config/packages/framework.yaml
framework:
    # ...
    http_client:
        # ...
        default_options:
            retry_failed:
                # retry_strategy: app.custom_strategy
                http_codes:
                    0: ['GET', 'HEAD']   # retry network errors if request method is GET or HEAD
                    429: true            # retry all responses with 429 status code
                    500: ['GET', 'HEAD']
                max_retries: 2
                delay: 1000
                multiplier: 3
                max_delay: 5000
                jitter: 0.3

        scoped_clients:
            my_api.client:
                # ...
                retry_failed:
                    max_retries: 4
    

retry_strategy

类型: string

该服务用于决定是否应重试请求以及计算重试之间等待的时间。默认情况下，它使用使用 http_codes、delay、max_delay、multiplier 和 jitter 选项配置的 GenericRetryStrategy 实例。此类必须实现 RetryStrategyInterface。

scope

类型: string

仅用于范围客户端：URL 必须匹配的正则表达式，然后才能应用所有其他非默认选项。默认情况下，范围从 base_uri 派生。

timeout

类型: float 默认值: 取决于您的 PHP 配置

等待网络活动的时间，以秒为单位。如果连接空闲时间过长，则会抛出 TransportException。其默认值与 PHP 的 default_socket_timeout 配置选项的值相同。

verify_host

类型: boolean 默认值: true

如果为 true，则验证其他服务器发送的证书，以确保其公用名与 URL 中包含的主机匹配。这通常与 verify_peer 结合使用，以同时验证证书的真实性。

verify_peer

类型: boolean 默认值: true

如果为 true，则在协商 TLS 连接时，将验证其他服务器发送的证书的真实性。仅验证证书不足以确保服务器的安全，因此您应将其与 verify_host 选项结合使用。

html_sanitizer

html_sanitizer 选项（及其子项）用于配置自定义 HTML 清理器。在 HTML 清理器文档中阅读有关选项的更多信息。

profiler

启用

类型: boolean 默认值: false

可以通过将此选项设置为 true 来启用分析器。当您使用 Symfony Flex 安装它时，分析器在 dev 和 test 环境中启用。

提示

分析器独立于 Web 开发人员工具栏工作，请参阅 WebProfilerBundle 配置以了解如何禁用/启用工具栏。

collect

类型: boolean 默认值: true

此选项配置分析器在启用时的行为方式。如果设置为 true，则分析器收集所有请求的数据。如果您只想按需收集信息，可以将 collect 标志设置为 false 并手动激活数据收集器

        1
        $profiler->enable();
    

collect_parameter

类型: string 默认值: null

这指定查询参数、请求体参数或请求属性的名称，用于为每个请求启用或禁用分析器的数据收集。将其与 collect 选项结合使用，以按需启用/禁用分析器

如果 collect 选项设置为 true，但此参数存在于请求中并且具有除 true、yes、on 或 1 之外的任何值，则不会收集请求数据；
如果 collect 选项设置为 false，但此参数存在于请求中并且具有 true、yes、on 或 1 的值，则将收集请求数据。

only_exceptions

类型: boolean 默认值: false

当设置为 true 时，仅当在请求处理期间抛出异常时，才会启用分析器。

only_main_requests

类型: boolean 默认值: false

当设置为 true 时，分析器将仅在主请求（而不是子请求）上启用。

dsn

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

用于存储分析信息的 DSN。

collect_serializer_data

类型: boolean 默认值: false

将此选项设置为 true 以启用序列化器数据收集器及其分析器面板。当此选项为 true 时，所有规范化器和编码器都将由可跟踪的实现进行修饰，这些实现收集有关它们的分析信息。

rate_limiter

name

类型: prototype

您要创建的速率限制器的名称。

lock_factory

类型: string 默认值: lock.factory

用于创建锁的服务。该服务必须是 LockFactory 类的实例。

policy

类型: string 必需

要使用的速率限制算法的名称。示例名称为 fixed_window、sliding_window 和 no_limit。有关更多信息，请参阅速率限制器策略）。

request

formats

类型: array 默认值: []

此设置用于将附加请求格式（例如 html）与一个或多个 mime 类型（例如 text/html）关联，这将允许您使用格式和 mime 类型来调用 Request::getFormat($mimeType) 或 Request::getMimeType($format)。

实际上，这很重要，因为 Symfony 使用它来自动设置 Response 上的 Content-Type 标头（如果您未显式设置一个）。如果您传递 mime 类型数组，则第一个将用于标头。

要配置 jsonp 格式

        1
2
3
4
5
        # config/packages/framework.yaml
framework:
    request:
        formats:
            jsonp: 'application/javascript'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>

<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony
        http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:request>
            <framework:format name="jsonp">
                <framework:mime-type>application/javascript</framework:mime-type>
            </framework:format>
        </framework:request>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->request()
        ->format('jsonp', 'application/javascript');
};
    

router

resource

类型: string 必需

主路由资源的路径（例如 YAML 文件），其中包含路由器应加载的路由和导入。

type

类型: string

资源的类型，以提示加载器关于格式。当您将默认路由器与预期的文件扩展名（.xml、.yaml、.php）一起使用时，不需要这样做。

default_uri

类型: string

用于在非 HTTP 上下文中生成 URL 的默认 URI（请参阅在命令中生成 URL）。

http_port

类型: integer 默认值: 80

正常 http 请求的端口（这在匹配方案时使用）。

https_port

类型: integer 默认值: 443

https 请求的端口（这在匹配方案时使用）。

strict_requirements

类型: mixed 默认值: true

确定路由生成器的行为。当生成具有特定参数要求的路由时，如果使用的参数不符合这些要求，生成器的行为可能会有所不同。

该值可以是以下之一

true: 当不满足要求时抛出异常；
false: 当不满足要求时不禁用异常，而是返回 ''；
null: 禁用检查要求（因此，即使要求不匹配也匹配路由）。

在开发环境中建议使用 true，而在生产环境中可能首选 false 或 null。

utf8

类型: boolean 默认值: true

当此选项设置为 true 时，路由参数的要求中使用的正则表达式将使用 utf-8 修饰符运行。例如，在使用 . 时，这将匹配任何 UTF-8 字符，而不是仅匹配单个字节。

如果您的应用程序的字符集是 UTF-8（如在内核的 getCharset() 方法中定义的那样），建议将其设置为 true。这将使非 UTF-8 URL 生成 404 错误。

cache_dir

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

将缓存路由信息的目录。可以设置为 ~ (null) 以禁用路由缓存。

7.1

自 Symfony 7.1 起，设置 cache_dir 选项已被弃用。路由现在始终缓存在 %kernel.build_dir% 目录中。

secrets

启用

类型: boolean 默认值: true

是否启用或不启用密钥管理。

decryption_env_var

类型: string 默认值: base64:default::SYMFONY_DECRYPTION_SECRET

包含 vault 解密密钥的环境变量名称。默认情况下，此值将从 base64 解码。

local_dotenv_file

类型: string 默认值: %kernel.project_dir%/.env.%kernel.environment%.local

本地 .env 文件的路径。此文件必须包含 vault 解密密钥，由 decryption_env_var 选项给出。

vault_directory

类型: string 默认值: %kernel.project_dir%/config/secrets/%kernel.runtime_environment%

用于存储密钥 vault 的目录。默认情况下，路径包含 kernel.runtime_environment 参数的值。

session

storage_factory_id

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

用于创建存储会话的 SessionStorageInterface 的服务 ID。此服务在 Symfony 应用程序中通过 session.storage.factory 服务别名提供。该类必须实现 SessionStorageFactoryInterface。要查看所有可用存储的列表，请运行

        1
        $ php bin/console debug:container session.storage.factory.
    

handler_id

类型: string | null 默认值: null

如果未设置 framework.session.save_path，则此选项的默认值为 null，这意味着使用在 php.ini 中配置的会话处理程序。如果设置了 framework.session.save_path 选项，则 Symfony 使用本机文件会话处理程序存储会话。

可以将会话存储在数据库中，也可以使用 DSN 配置会话处理程序

        1
2
3
4
5
6
7
8
        # config/packages/framework.yaml
framework:
    session:
        # a few possible examples
        handler_id: 'redis://127.0.0.1'
        handler_id: '%env(REDIS_URL)%'
        handler_id: '%env(DATABASE_URL)%'
        handler_id: 'file://%kernel.project_dir%/var/sessions'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">
    <framework:config>
        <!-- a few possible examples -->
        <framework:session enabled="true"
            handler-id="redis://127.0.0.1"
            handler-id="%env(REDIS_URL)%"
            handler-id="%env(DATABASE_URL)%"
            handler-id="file://%kernel.project_dir%/var/sessions"/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // config/packages/framework.php
use function Symfony\Component\DependencyInjection\Loader\Configurator\env;
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...

    $framework->session()
        // a few possible examples
        ->handlerId('redis://127.0.0.1')
        ->handlerId(env('REDIS_URL'))
        ->handlerId(env('DATABASE_URL'))
        ->handlerId('file://%kernel.project_dir%/var/sessions');
};
    

提示

支持的 DSN 协议如下

file
redis
rediss (Redis over TLS)
memcached (需要 symfony/cache)
pdo_oci (需要 doctrine/dbal)
mssql
mysql
mysql2
pgsql
postgres
postgresql
sqlsrv
sqlite
sqlite3

name

类型: string

这指定了会话 Cookie 的名称。

如果未设置，将依赖 php.ini 的 session.name 指令。

类型: integer

这决定了会话的生命周期，以秒为单位。将此值设置为 0 意味着 Cookie 在浏览器会话期间有效。

如果未设置，将依赖 php.ini 的 session.cookie_lifetime 指令。

类型: string

这决定了在会话 Cookie 中设置的路径。

如果未设置，将依赖 php.ini 的 session.cookie_path 指令。

cache_limiter

类型: string 默认值: 0

如果设置为 0，Symfony 将不会设置任何与缓存相关的特定标头，并将依赖 php.ini 的 session.cache_limiter 指令。

与其他会话选项不同，cache_limiter 被设置为常规的容器参数

        1
2
3
4
        # config/services.yaml
parameters:
    session.storage.options:
        cache_limiter: 0
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd">

    <parameters>
        <parameter key="session.storage.options" type="collection">
            <parameter key="cache_limiter">0</parameter>
        </parameter>
    </parameters>
</container>
    

        1
2
3
4
        // config/services.php
$container->setParameter('session.storage.options', [
    'cache_limiter' => 0,
]);
    

请注意，如果您配置了它，您也必须将其他与会话相关的选项设置为参数。

类型: string

这决定了在会话 Cookie 中设置的域。

如果未设置，将依赖 php.ini 的 session.cookie_domain 指令。

类型: string 或 null 默认值: null

它控制当 HTTP 请求并非源自与 Cookie 关联的同一域时，Cookie 的发送方式。建议设置此选项以缓解 CSRF 安全攻击。

默认情况下，浏览器会发送与 HTTP 请求域相关的所有 Cookie。例如，当您访问论坛并且某些恶意评论包含类似 https://some-bank.com/?send_money_to=attacker&amount=1000 的链接时，这可能会成为问题。如果您之前已登录到您的银行网站，则浏览器在发出该 HTTP 请求时将发送所有这些 Cookie。

此选项的可能值是

null，使用 php.ini 的 session.cookie_samesite 指令。
'none'（或 Symfony\Component\HttpFoundation\Cookie::SAMESITE_NONE 常量），当 HTTP 请求源自不同的域时使用它来允许发送 Cookie（以前这是 null 的默认行为，但在较新的浏览器中，如果未设置标头，则会应用 'lax'）
'strict'（或 Cookie::SAMESITE_STRICT 常量），当 HTTP 请求并非源自同一域时，使用它来永不发送任何 Cookie。
'lax'（或 Cookie::SAMESITE_LAX 常量），当请求源自不同的域时，使用它来允许发送 Cookie，但仅当用户有意识地发出请求时（通过单击链接或提交带有 GET 方法的表单）。

类型: boolean 或 'auto'

这决定了 Cookie 是否应仅通过安全连接发送。除了 true 和 false 之外，还有一个特殊的 'auto' 值，表示 HTTPS 请求为 true，HTTP 请求为 false。

如果未设置，将依赖 php.ini 的 session.cookie_secure 指令。

类型: boolean 默认值: true

这决定了 Cookie 是否应仅通过 HTTP 协议访问。这意味着 Cookie 将无法通过脚本语言（如 JavaScript）访问。此设置可以有效地帮助减少通过 XSS 攻击造成的身份盗窃。

gc_divisor

类型: integer

请参阅 gc_probability。

如果未设置，将依赖 php.ini 的 session.gc_divisor 指令。

gc_probability

类型: integer

这定义了每次会话初始化时启动垃圾回收器 (GC) 进程的概率。概率是通过使用 gc_probability / gc_divisor 计算的，例如 1/100 表示每次请求启动 GC 进程的概率为 1%。

如果未设置，Symfony 将使用 session.gc_probability 指令在 php.ini 配置文件中的值。

7.2

在 Symfony 7.2 中引入了依赖 php.ini 的指令作为 gc_probability 的默认值。

gc_maxlifetime

类型: integer

这决定了数据在被视为“垃圾”并可能被清理之前经过的秒数。垃圾回收可能在会话开始时发生，并取决于 gc_divisor 和 gc_probability。

如果未设置，将依赖 php.ini 的 session.gc_maxlifetime 指令。

sid_length

类型: integer

这决定了会话 ID 字符串的长度，它可以是介于 22 和 256 之间的整数（包括两者），32 是建议值。会话 ID 越长，越难猜测。

如果未设置，将依赖 php.ini 的 session.sid_length 指令。

7.2

sid_length 选项在 Symfony 7.2 中已弃用。由于 PHP 8.4 已弃用相关选项，因此未提供替代方案。

sid_bits_per_character

类型: integer

这决定了编码的会话 ID 字符中的位数。可能的值为 4 (0-9, a-f)、5 (0-9, a-v) 和 6 (0-9, a-z, A-Z, "-", ",")。位数越多，会话 ID 越强。5 是大多数环境的建议值。

如果未设置，将依赖 php.ini 的 session.sid_bits_per_character 指令。

7.2

sid_bits_per_character 选项在 Symfony 7.2 中已弃用。由于 PHP 8.4 已弃用相关选项，因此未提供替代方案。

save_path

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

这决定了要传递给保存处理程序的参数。如果您选择默认的文件处理程序，则这是创建会话文件的路径。

如果为 null，将依赖 php.ini 的 session.save_path 指令

        1
2
3
4
        # config/packages/framework.yaml
framework:
    session:
        save_path: ~
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:session save-path="null"/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->session()
        ->savePath(null);
};
    

metadata_update_threshold

类型: integer 默认值: 0

这是更新/写入会话元数据之间等待的秒数。如果您出于某种原因想要限制会话持久化的频率，而不是在每次请求时都这样做，这将非常有用。

启用

类型: boolean 默认值: true

是否在框架中启用会话支持。

        1
2
3
4
        # config/packages/framework.yaml
framework:
    session:
        enabled: true
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:session enabled="true"/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->session()
        ->enabled(true);
};
    

use_cookies

类型: boolean

这指定了会话 ID 是否使用 Cookie 存储在客户端。

如果未设置，将依赖 php.ini 的 session.use_cookies 指令。

ssi

启用

类型: boolean 默认值: false

是否在您的应用程序中启用 SSI 支持。

assets

base_path

类型: string

此选项允许您定义用于 assets 的基本路径

        1
2
3
4
5
        # config/packages/framework.yaml
framework:
    # ...
    assets:
        base_path: '/images'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:assets base-path="/images"/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->assets()
        ->basePath('/images');
};
    

base_urls

类型: array

此选项允许您定义用于 assets 的基本 URL。如果提供了多个基本 URL，Symfony 将在每次生成 asset 的路径时从集合中选择一个

        1
2
3
4
5
6
        # config/packages/framework.yaml
framework:
    # ...
    assets:
        base_urls:
            - 'http://cdn.example.com/'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/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
8
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->assets()
        ->baseUrls(['http://cdn.example.com/']);
};
    

version

类型: string

此选项用于通过全局添加查询参数到所有渲染的 asset 路径来破坏 assets 上的缓存 (例如 /images/logo.png?v2)。这仅适用于通过 Twig asset() 函数（或 PHP 等效项）渲染的 assets。

例如，假设您有以下内容

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

默认情况下，这将渲染一个指向您的图像的路径，例如 /images/logo.png。现在，激活 version 选项

        1
2
3
4
5
        # config/packages/framework.yaml
framework:
    # ...
    assets:
        version: 'v2'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:assets version="v2"/>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->assets()
        ->version('v2');
};
    

现在，相同的 asset 将被渲染为 /images/logo.png?v2。如果您使用此功能，您必须在每次部署之前手动增加 version 值，以便查询参数发生更改。

您还可以通过 version_format 选项控制查询字符串的工作方式。

提示

此参数不能与 version_strategy 或 json_manifest_path 同时设置。

提示

与所有设置一样，您可以将参数用作 version 的值。这使得在每次部署时更容易增加缓存。

version_format

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

这指定了一个 sprintf 模式，该模式将与 version 选项一起使用，以构造 asset 的路径。默认情况下，该模式将 asset 的版本添加为查询字符串。例如，如果 version_format 设置为 %%s?version=%%s，并且 version 设置为 5，则 asset 的路径将为 /images/logo.png?version=5。

提示

格式字符串中的所有百分号 (%) 都必须加倍以转义字符。如果不转义，值可能会被错误地解释为 Service Container。

提示

某些 CDN 不支持通过查询字符串进行缓存失效，因此将版本注入到实际文件路径中是必要的。值得庆幸的是，version_format 不限于生成版本化的查询字符串。

该模式接收 asset 的原始路径和版本作为其第一个和第二个参数。由于 asset 的路径是一个参数，因此您无法就地修改它（例如 /images/logo-v5.png）；但是，您可以使用 version-%%2$s/%%1$s 的模式前缀 asset 的路径，这将导致路径 version-5/images/logo.png。

然后可以使用 URL 重写规则来忽略版本前缀，然后再提供 asset。或者，您可以将 assets 复制到部署过程的相应版本路径，并忘记任何 URL 重写。如果您希望较旧的 asset 版本在其原始 URL 上保持可访问，则后一个选项很有用。

version_strategy

类型: string 默认值: null

应用于 assets 的 asset 版本策略的服务 ID。此选项可以全局设置为所有 assets，也可以单独为每个 asset 包设置

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        # config/packages/framework.yaml
framework:
    assets:
        # this strategy is applied to every asset (including packages)
        version_strategy: 'app.asset.my_versioning_strategy'
        packages:
            foo_package:
                # this package removes any versioning (its assets won't be versioned)
                version: ~
            bar_package:
                # this package uses its own strategy (the default strategy is ignored)
                version_strategy: 'app.asset.another_version_strategy'
            baz_package:
                # this package inherits the default strategy
                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
23
24
25
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:assets version-strategy="app.asset.my_versioning_strategy">
            <!-- this package removes any versioning (its assets won't be versioned) -->
            <framework:package
                name="foo_package"
                version="null"/>
            <!-- this package uses its own strategy (the default strategy is ignored) -->
            <framework:package
                name="bar_package"
                version-strategy="app.asset.another_version_strategy"/>
            <!-- this package inherits the default strategy -->
            <framework:package
                name="baz_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
18
19
20
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->assets()
        ->versionStrategy('app.asset.my_versioning_strategy');

    $framework->assets()->package('foo_package')
        // this package removes any versioning (its assets won't be versioned)
        ->version(null);

    $framework->assets()->package('bar_package')
        // this package uses its own strategy (the default strategy is ignored)
        ->versionStrategy('app.asset.another_version_strategy');

    $framework->assets()->package('baz_package')
        // this package inherits the default strategy
        ->basePath('/images');
};
    

提示

此参数不能与 version 或 json_manifest_path 同时设置。

json_manifest_path

类型: string 默认值: null

指向 manifest.json 文件的文件路径或绝对 URL，该文件包含 asset 名称及其各自编译名称的关联数组。使用“manifest”文件的常见缓存失效技术是通过在前端编译例程期间写出带有附加到其文件名的“哈希”的 assets（例如 main.ae433f1cb.css）来实现的。

提示

Symfony 的 Webpack Encore 支持输出哈希 assets。此外，这可以合并到许多其他工作流程中，包括使用 webpack-manifest-plugin 和 gulp-rev 的 Webpack 和 Gulp 分别。

此选项可以全局设置为所有 assets，也可以单独为每个 asset 包设置

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        # config/packages/framework.yaml
framework:
    assets:
        # this manifest is applied to every asset (including packages)
        json_manifest_path: "%kernel.project_dir%/public/build/manifest.json"
        # you can use absolute URLs too and Symfony will download them automatically
        # json_manifest_path: 'https://cdn.example.com/manifest.json'
        packages:
            foo_package:
                # this package uses its own manifest (the default file is ignored)
                json_manifest_path: "%kernel.project_dir%/public/build/a_different_manifest.json"
                # Throws an exception when an asset is not found in the manifest
                strict_mode: %kernel.debug%
            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
23
24
25
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/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%/public/build/manifest.json">
        <!-- you can use absolute URLs too and Symfony will download them automatically -->
        <!-- <framework:assets json-manifest-path="https://cdn.example.com/manifest.json"> -->
            <!-- this package uses its own manifest (the default file is ignored) -->
            <!-- Throws an exception when an asset is not found in the manifest -->
            <framework:package
                name="foo_package"
                json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json" strict-mode="%kernel.debug%"/>
            <!-- 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
18
19
20
21
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    // ...
    $framework->assets()
        // this manifest is applied to every asset (including packages)
        ->jsonManifestPath('%kernel.project_dir%/public/build/manifest.json');

    // you can use absolute URLs too and Symfony will download them automatically
    // 'json_manifest_path' => 'https://cdn.example.com/manifest.json',
    $framework->assets()->package('foo_package')
        // this package uses its own manifest (the default file is ignored)
        ->jsonManifestPath('%kernel.project_dir%/public/build/a_different_manifest.json')
        // Throws an exception when an asset is not found in the manifest
        ->setStrictMode('%kernel.debug%');

    $framework->assets()->package('bar_package')
        // this package uses the global manifest (the default file is used)
        ->basePath('/images');
};
    

提示

如果指定了全局 manifest 文件，则此参数不能与 version 或 version_strategy 同时设置。此外，如果指定了全局 manifest 文件，则无法在包范围内将此选项置为 null。

提示

如果您请求的 asset 在 manifest.json 文件中未找到，则将返回原始的 - 未修改的 - asset 路径。您可以将 strict_mode 设置为 true，以便在未找到 asset 时抛出异常。

提示

如果设置了 URL，则 JSON manifest 将在每次请求时使用 http_client 下载。

strict_mode

类型: boolean 默认值: false

启用后，严格模式会断言所有请求的 assets 都位于 manifest 文件中。此选项对于检测拼写错误或丢失的 assets 非常有用，建议值为 %kernel.debug%。

translator

cache_dir

类型: string | null 默认值: %kernel.cache_dir%/translations

定义存储翻译缓存的目录。使用 null 禁用此缓存。

启用

类型: boolean 默认值: true 或 false，具体取决于您的安装

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

fallbacks

类型: string|array 默认值: default_locale 的值

当找不到当前语言环境的翻译键时，将使用此选项。

另请参阅

有关更多详细信息，请参阅翻译。

logging

默认值: 启用调试模式时为 true，否则为 false。

当 true 时，每当翻译器找不到给定键的翻译时，都会创建一个日志条目。日志会在 translation 通道的 debug 级别为回退语言环境中存在翻译的键创建，如果根本没有可用的翻译，则会在 warning 级别创建。

formatter

类型: string 默认值: translator.formatter.default

用于格式化翻译消息的服务的 ID。服务类必须实现 MessageFormatterInterface。

paths

类型: array 默认值: []

此选项允许定义组件将在其中查找翻译文件的路径数组。稍后添加的路径具有更高的优先级（来自稍后路径的翻译会覆盖较早路径的翻译）。来自 default_path 的翻译比来自所有这些路径的翻译具有更高的优先级。

default_path

类型: string 默认值: %kernel.project_dir%/translations

此选项允许定义应用程序翻译文件存储的路径。

providers

类型: array 默认值: []

此选项启用并配置翻译提供程序，以将您的翻译推送到/从第三方翻译服务拉取。

property_access

magic_call

类型: boolean 默认值: false

启用后，当调用 property_accessor 服务的 getValue() 方法时，它会使用 PHP 的 magic __call() 方法。

magic_get

类型: boolean 默认值: true

启用后，当调用 property_accessor 服务的 getValue() 方法时，它会使用 PHP 的 magic __get() 方法。

magic_set

类型: boolean 默认值: true

启用后，当调用 property_accessor 服务的 setValue() 方法时，它会使用 PHP 的 magic __set() 方法。

throw_exception_on_invalid_index

类型: boolean 默认值: false

启用后，当您尝试访问数组的无效索引时，property_accessor 服务会抛出异常。

throw_exception_on_invalid_property_path

类型: boolean 默认值: true

启用后，当您尝试访问对象的无效属性路径时，property_accessor 服务会抛出异常。

property_info

启用

类型: boolean 默认值: true 或 false，具体取决于您的安装

validation

auto_mapping

类型: array 默认值: []

定义将进行内省以向其添加自动验证约束的 Doctrine 实体

        1
2
3
4
5
6
7
        framework:
    validation:
        auto_mapping:
            # an empty array means that all entities that belong to that
            # namespace will add automatic validation
            'App\Entity\': []
            'Foo\': ['Foo\Some\Entity', 'Foo\Another\Entity']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:validation>
            <framework:auto-mapping>
                <framework:service namespace="App\Entity\"/>

                <framework:service namespace="Foo\">Foo\Some\Entity</framework:service>
                <framework:service namespace="Foo\">Foo\Another\Entity</framework:service>
            </framework:auto-mapping>
        </framework:validation>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->validation()
        ->autoMapping()
            ->paths([
                'App\\Entity\\' => [],
                'Foo\\' => ['Foo\\Some\\Entity', 'Foo\\Another\\Entity'],
            ]);
};
    

启用

类型: boolean 默认值: true 或 false，具体取决于您的安装

是否启用验证支持。

当配置其中一个子设置时，此选项将自动设置为 true。

enable_attributes

类型: boolean 默认值: true

如果启用此选项，则可以使用 PHP 属性定义验证约束。

translation_domain

类型: string | false 默认值: validators

翻译验证约束错误消息时使用的翻译域。使用 false 禁用翻译。

not_compromised_password

NotCompromisedPassword 约束向公共 API 发出 HTTP 请求，以检查给定的密码是否在数据泄露中泄露。

启用

类型: boolean 默认值: true

如果您将此选项设置为 false，则不会发出 HTTP 请求，并且给定的密码将被视为有效。当您不想或无法发出 HTTP 请求时，例如在 dev 和 test 环境或持续集成服务器中，这非常有用。

endpoint

类型: string 默认值: null

默认情况下，NotCompromisedPassword 约束使用 haveibeenpwned.com 提供的公共 API。此选项允许定义不同的但兼容的 API 端点来进行密码检查。例如，当 Symfony 应用程序在没有公共互联网访问权限的内联网中运行时，这很有用。

static_method

类型: string | array 默认值: ['loadValidatorMetadata']

定义调用以加载类的验证元数据的静态方法的名称。您可以定义一个包含多个方法名称的字符串数组。在这种情况下，将按顺序调用所有这些方法以加载元数据。

email_validation_mode

类型: string 默认值: html5

设置 Email 验证器的“mode”选项的默认值。

mapping

paths

类型: array 默认值: ['config/validation/']

此选项允许定义一个包含文件或目录路径的数组，组件将在其中查找其他验证文件

        1
2
3
4
5
6
        # config/packages/framework.yaml
framework:
    validation:
        mapping:
            paths:
                - "%kernel.project_dir%/config/validation/"
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:validation>
            <framework:mapping>
                <framework:path>%kernel.project_dir%/config/validation/</framework:path>
            </framework:mapping>
        </framework:validation>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->validation()
        ->mapping()
            ->paths(['%kernel.project_dir%/config/validation/']);
};
    

annotations

cache

类型: string 默认值: php_array

此选项可以是以下值之一

php_array: 使用 PHP 数组在内存中缓存注释
file: 使用文件系统缓存注释
none: 禁用注释缓存

file_cache_dir

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

存储注释缓存文件的目录，以防 annotations.cache 设置为 'file'。

调试

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

是否启用缓存的调试模式。如果启用，当原始文件更改时（包括代码和注释更改），缓存将自动更新。出于性能原因，建议在生产环境中禁用调试模式，如果您使用默认值，这将自动发生。

serializer

启用

类型: boolean 默认值: true 或 false，具体取决于您的安装

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

enable_attributes

类型: boolean 默认值: true

在序列化器组件中启用对 PHP 属性的支持。

另请参阅

有关受支持的注释列表，请参阅参考。

name_converter

类型: string

要使用的名称转换器。可以通过使用 serializer.name_converter.camel_case_to_snake_case 值启用 CamelCaseToSnakeCaseNameConverter 名称转换器。

另请参阅

有关更多信息，请参阅如何使用序列化器。

circular_reference_handler

类型 string

用作默认序列化器的循环引用处理程序的服务的 ID。该服务必须实现 magic __invoke($object) 方法。

另请参阅

有关更多信息，请参阅如何使用序列化器。

mapping

paths

类型: array 默认值: []

此选项允许定义一个包含文件或目录路径的数组，组件将在其中查找其他序列化文件。

default_context

类型: array 默认值: []

一个包含默认上下文选项的映射，这些选项将用于每个 serialize 和 deserialize 调用。例如，这可用于通过将 json_encode_options 设置为 json_encode 标志位掩码来设置 json 编码行为。

您可以检查序列化器上下文构建器以发现可用的设置。

php_errors

log

类型: boolean | int 默认值: true

使用应用程序记录器而不是 PHP 记录器来记录 PHP 错误。当使用整数值时，它还会设置日志级别。这些整数值必须与 error_reporting PHP 选项中使用的值相同。

此选项还接受 PHP 错误到日志级别的映射

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        # config/packages/framework.yaml
framework:
    php_errors:
        log:
            !php/const \E_DEPRECATED: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_USER_DEPRECATED: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_NOTICE: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_USER_NOTICE: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_STRICT: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_WARNING: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_USER_WARNING: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_COMPILE_WARNING: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_CORE_WARNING: !php/const Psr\Log\LogLevel::ERROR
            !php/const \E_USER_ERROR: !php/const Psr\Log\LogLevel::CRITICAL
            !php/const \E_RECOVERABLE_ERROR: !php/const Psr\Log\LogLevel::CRITICAL
            !php/const \E_COMPILE_ERROR: !php/const Psr\Log\LogLevel::CRITICAL
            !php/const \E_PARSE: !php/const Psr\Log\LogLevel::CRITICAL
            !php/const \E_ERROR: !php/const Psr\Log\LogLevel::CRITICAL
            !php/const \E_CORE_ERROR: !php/const Psr\Log\LogLevel::CRITICAL
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <!-- in XML configuration you cannot use PHP constants as the value of
             the 'type' attribute, which makes this format way less readable.
             Consider using YAML or PHP for this configuration -->
        <framework:log type="8" logLevel="error"/>
        <framework:log type="2" logLevel="error"/>
        <!-- ... -->
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
        // config/packages/framework.php
use Psr\Log\LogLevel;
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->phpErrors()->log(\E_DEPRECATED, LogLevel::ERROR);
    $framework->phpErrors()->log(\E_USER_DEPRECATED, LogLevel::ERROR);
    // ...
};
    

throw

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

将 PHP 错误作为 \ErrorException 实例抛出。debug.error_handler.throw_at 参数控制阈值。

cache

app

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

cache.app 服务使用的缓存适配器。FrameworkBundle 附带多个适配器：cache.adapter.apcu、cache.adapter.system、cache.adapter.filesystem、cache.adapter.psr6、cache.adapter.redis、cache.adapter.memcached、cache.adapter.pdo 和 cache.adapter.doctrine_dbal。

还有一个名为 cache.adapter.array 的特殊适配器，它使用 PHP 数组在内存中存储内容，用于禁用缓存（主要在 dev 环境中）。

提示

一开始可能很难理解，因此为了避免混淆，请记住所有池都执行相同的操作，但基于它们所基于的适配器在不同的介质上执行。在内部，池包装了适配器的定义。

system

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

cache.system 服务使用的缓存适配器。它支持与 cache.app 服务相同的适配器。

default_doctrine_provider

类型: string

用作默认 Doctrine 提供程序的服务名称。该提供程序作为 cache.default_doctrine_provider 服务提供。

default_psr6_provider

类型: string

用作默认 PSR-6 提供程序的服务名称。它作为 cache.default_psr6_provider 服务提供。

default_redis_provider

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

Redis 提供程序使用的 DSN。该提供程序作为 cache.default_redis_provider 服务提供。

default_memcached_provider

类型: string 默认值: memcached://127.0.0.1

Memcached 提供程序使用的 DSN。该提供程序作为 cache.default_memcached_provider 服务提供。

default_pdo_provider

类型: string 默认值: doctrine.dbal.default_connection

数据库连接的服务 ID，它应该是 PDO 或 Doctrine DBAL 实例。该提供程序作为 cache.default_pdo_provider 服务提供。

pools

类型: array

框架扩展将创建的缓存池列表。

另请参阅

有关池如何工作的更多信息，请参阅缓存池。

要配置默认生命周期为 1 小时的 Redis 缓存池，请执行以下操作

        1
2
3
4
5
6
7
        # config/packages/framework.yaml
framework:
    cache:
        pools:
            cache.mycache:
                adapter: cache.adapter.redis
                default_lifetime: 3600
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        <!-- config/packages/framework.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:cache>
            <framework:pool
                name="cache.mycache"
                adapter="cache.adapter.redis"
                default-lifetime="3600"
            />
        </framework:cache>
        <!-- ... -->
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
        // config/packages/framework.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->cache()
        ->pool('cache.mycache')
            ->adapters(['cache.adapter.redis'])
            ->defaultLifetime(3600);
};
    

name

类型: prototype

您要创建的池的名称。

提示

您的池名称必须与 cache.app 或 cache.system 不同。

adapter

类型: string 默认值: cache.app

要使用的适配器的服务名称。您可以指定遵循 cache.adapter.[type] 模式的默认服务之一。或者，您可以将另一个缓存池指定为基础，这将使此池从基础池继承设置作为默认值。

提示

您的服务需要实现 Psr\Cache\CacheItemPoolInterface 接口。

public

类型: boolean 默认值: false

您的服务是否应该是公共的。

default_lifetime

类型: integer | string

缓存项的默认生命周期。给定一个整数值以秒为单位设置默认生命周期。字符串值可以是 ISO 8601 时间间隔，例如 "PT5M" 或 strtotime() 接受的 PHP 日期表达式，例如 "5 minutes"。

如果未提供值，则缓存适配器将回退到实际缓存存储上的默认值。

provider

类型: string

如果您不想使用在 cache 下配置为 default_X_provider 的内容，请分别覆盖默认服务名称或 DSN。有关如何指定特定提供程序的信息，请参阅上面默认提供程序设置的描述。

clearer

类型: string

用于清除 PSR-6 缓存的缓存清除器。

另请参阅

更多信息，请参阅 Psr6CacheClearer。

prefix_seed

类型: string 默认值: _%kernel.project_dir%.%kernel.container_class%

此值用作缓存项键生成的“命名空间”的一部分。常见的做法是使用应用程序的唯一名称（例如，symfony.com），因为这样可以防止在将多个应用程序部署到同一路径（在不同的服务器上）并共享同一缓存后端时发生命名冲突。

当使用蓝/绿部署策略，以及更普遍地，当您需要抽象出实际的部署目录时（例如，当离线预热缓存时），它也很有用。

提示

prefix_seed 选项在编译时使用。这意味着在容器编译后对此值所做的任何更改都将无效。

        1
2
3
        # config/packages/lock.yaml
framework:
    lock: '%env(LOCK_DSN)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/packages/lock.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:lock>
            <framework:resource name="default">%env(LOCK_DSN)%</framework:resource>
        </framework:lock>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
        // config/packages/lock.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->lock()
        ->resource('default', [env('LOCK_DSN')]);
};
    

另请参阅

更多详情，请参阅使用锁处理并发。

        1
2
3
        # config/packages/semaphore.yaml
framework:
    semaphore: '%env(SEMAPHORE_DSN)%'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/packages/semaphore.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:semaphore>
            <framework:resource name="default">%env(SEMAPHORE_DSN)%</framework:resource>
        </framework:semaphore>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
        // config/packages/semaphore.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->semaphore()
        ->resource('default', ['%env(SEMAPHORE_DSN)%']);
};
    

        1
2
3
4
5
6
        # config/packages/mailer.yaml
framework:
    mailer:
        dsn: 'smtp://127.0.0.1:25'
        envelope:
            recipients: ['[email protected]', '[email protected]']
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/mailer.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">
    <framework:config>
        <framework:mailer dsn="smtp://127.0.0.1:25">
            <framework:envelope>
                <framework:recipient>[email protected]</framework:recipient>
                <framework:recipient>[email protected]</framework:recipient>
            </framework:envelope>
        </framework:mailer>
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        // config/packages/mailer.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return static function (ContainerConfigurator $container): void {
    $container->extension('framework', [
        'mailer' => [
            'dsn' => 'smtp://127.0.0.1:25',
            'envelope' => [
                'recipients' => [
                    '[email protected]',
                    '[email protected]',
                ],
            ],
        ],
    ]);
};
    

headers

类型: array

要添加到电子邮件的标头。键（xml 格式的 name 属性）是标头名称，值是标头值。

另请参阅

更多信息，请参阅全局配置电子邮件

messenger

启用

类型: boolean 默认值: true

是否启用 Messenger。

另请参阅

更多详情，请参阅 Messenger 组件文档。

        1
2
3
4
5
        # config/packages/workflow.yaml
framework:
    workflows:
        my_workflow:
            # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/workflow.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:workflows>
            <framework:workflow
                name="my_workflow"/>
        </framework:workflows>
        <!-- ... -->
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
        // config/packages/workflow.php
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->workflows()
        ->workflows('my_workflow')
            // ...
    ;
};
    

另请参阅

另请参阅关于在 Symfony 应用程序中使用工作流的文章。

property (类型: string 默认值: marking)
service (类型: string)
type (类型: string 允许值: 'method')

from (类型: string 或 array) 来自 places 的值，workflow 和 state_machine 都允许多个值；
guard (类型: string) 用于阻止转换的 ExpressionLanguage 兼容表达式；
name (类型: string) 转换的名称；
to (类型: string 或 array) 来自 places 的值，仅 workflow 允许多个值。

type

类型: string 可能的值: 'workflow' 或 'state_machine'

定义将要创建的工作流的类型，可以是正常工作流或状态机。阅读本文以了解它们之间的差异。

exceptions

类型: array

定义应用于与给定异常类匹配的异常的日志级别和 HTTP 状态代码

        1
2
3
4
5
6
        # config/packages/exceptions.yaml
framework:
    exceptions:
        Symfony\Component\HttpKernel\Exception\BadRequestHttpException:
            log_level: 'debug'
            status_code: 422
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- config/packages/exceptions.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.ac.cn/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.ac.cn/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.ac.cn/schema/dic/services
        http://symfony.ac.cn/schema/dic/services/services-1.0.xsd
        http://symfony.ac.cn/schema/dic/symfony http://symfony.ac.cn/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:exception
            class="Symfony\Component\HttpKernel\Exception\BadRequestHttpException"
            log-level="debug"
            status-code="422"
        />
        <!-- ... -->
    </framework:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
        // config/packages/exceptions.php
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Config\FrameworkConfig;

return static function (FrameworkConfig $framework): void {
    $framework->exception(BadRequestHttpException::class)
        ->logLevel('debug')
        ->statusCode(422)
    ;
};
    

配置异常的顺序很重要，因为 Symfony 将使用与 instanceof 匹配的第一个异常的配置

        1
2
3
4
5
6
7
8
9
10
        # config/packages/exceptions.yaml
framework:
    exceptions:
        Exception:
            log_level: 'debug'
            status_code: 404
        # The following configuration will never be used because \RuntimeException extends \Exception
        RuntimeException:
            log_level: 'debug'
            status_code: 422
    

您可以借助异常类上的 #[WithHttpStatus] 属性将状态代码和一组标头映射到异常

        1
2
3
4
5
6
7
8
9
10
11
        namespace App\Exception;

use Symfony\Component\HttpKernel\Attribute\WithHttpStatus;

#[WithHttpStatus(422, [
   'Retry-After' => 10,
   'X-Custom-Header' => 'header-value',
])]
class CustomException extends \Exception
{
}
    

也可以使用 #[WithLogLevel] 属性在自定义异常类上映射日志级别

        1
2
3
4
5
6
7
8
9
        namespace App\Exception;

use Psr\Log\LogLevel;
use Symfony\Component\HttpKernel\Attribute\WithLogLevel;

#[WithLogLevel(LogLevel::WARNING)]
class CustomException extends \Exception
{
}
    

属性也可以直接添加到接口

        1
2
3
4
5
6
7
8
9
10
11
12
        namespace App\Exception;

use Symfony\Component\HttpKernel\Attribute\WithHttpStatus;

#[WithHttpStatus(422)]
interface CustomExceptionInterface
{
}

class CustomException extends \Exception implements CustomExceptionInterface
{
}
    

7.1

Symfony 7.1 中引入了对在接口上使用 #[WithHttpStatus] 和 #[WithLogLevel] 属性的支持。

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。

TOC

版本