框架設定參考 (FrameworkBundle)

編輯此頁面

FrameworkBundle 定義了主要框架設定，從會期和翻譯到表單、驗證、路由等等。所有這些選項都在您的應用程式設定的 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 時，您必須使用 https://symfony.dev.org.tw/schema/dic/symfony 命名空間，並且相關的 XSD 綱要位於：https://symfony.dev.org.tw/schema/dic/symfony/symfony-1.0.xsd

設定

secret

類型: string 必填

這是一個字串，應該對您的應用程式是唯一的，並且通常用於為安全性相關操作增加更多熵。其值應為一系列隨機選擇的字元、數字和符號，建議長度約為 32 個字元。

實際上，Symfony 使用此值來加密 「記住我」功能 中使用的 Cookie，以及在使用 ESI (邊緣端包含) 時建立簽署的 URI。這就是為什麼您應該將此值視為敏感憑證，並且永遠不要公開。

此選項會變成名為 kernel.secret 的服務容器參數，您可以在應用程式需要不可變的隨機字串以增加更多熵時使用它。

與任何其他安全性相關的參數一樣，定期更改此值是一種好的做法。但是，請記住，更改此值將使所有簽署的 URI 和「記住我」Cookie 失效。因此，在更改此值後，您應該重新產生應用程式快取並登出所有應用程式使用者。

handle_all_throwables

類型: boolean 預設: true

當設定為 true 時，Symfony 核心將捕獲應用程式拋出的所有 \Throwable 例外，並將它們轉換為 HTTP 回應。

http_cache

已啟用

類型: boolean 預設: false

debug

類型: boolean 預設: %kernel.debug%

如果為 true，則在發生錯誤時會拋出例外。否則，快取將嘗試繼續並傳遞有意義的回應。

trace_level

類型: string 可能的值: 'none'、'short' 或 'full'

對於 'short'，主要請求的簡潔追蹤將作為 HTTP 標頭新增。「full」將為所有請求（包括 ESI 子請求）新增追蹤。（預設值：如果在 debug 模式下為 'full'；否則為 'none'）

trace_header

類型: string

用於追蹤的標頭名稱。（預設值：X-Symfony-Cache）

default_ttl

類型: integer

當回應中未提供明確的新鮮度資訊時，快取條目應被視為新鮮的秒數。明確的 Cache-Control 或 Expires 標頭會覆寫此值。（預設值：0）

private_headers

類型: array

一組請求標頭，會在回應未透過 Cache-Control 指令明確聲明回應是公開還是私有時，觸發「私有」快取控制行為。（預設值：Authorization 和 Cookie）

skip_response_headers

類型: array 預設: Set-Cookie

一組回應標頭，即使回應可快取且為公開，也永遠不會被快取。

allow_reload

類型: string

指定用戶端是否可以透過在請求中包含 Cache-Control "no-cache" 指令來強制快取重新載入。設定為 true 以符合 RFC 2616。（預設值：false）

allow_revalidate

類型: string

指定用戶端是否可以透過在請求中包含 Cache-Control "max-age=0" 指令來強制快取重新驗證。設定為 true 以符合 RFC 2616。（預設值：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 表單的動作和 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 標頭，它告訴網頁伺服器將回應內容替換為該標頭中定義的檔案。這提高了效能，因為檔案不再由您的應用程式提供服務，而是直接由網頁伺服器提供服務。

此設定選項決定是否信任 BinaryFileResponse 的 x-sendfile 標頭。如果啟用，Symfony 會自動呼叫 BinaryFileResponse::trustXSendfileTypeHeader 方法。它會變成名為 kernel.trust_x_sendfile_type_header 的服務容器參數。

trusted_headers

當在負載平衡器或反向代理伺服器後方執行 Symfony 時，需要 trusted_headers 選項來設定應信任哪些用戶端資訊（例如其主機）。請參閱 如何設定 Symfony 在負載平衡器或反向代理伺服器後方運作。

trusted_proxies

當在負載平衡器或反向代理伺服器後方執行 Symfony 時，需要 trusted_proxies 選項來取得關於用戶端的精確資訊（例如其 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'

由於每位開發人員都使用不同的 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 將檔案從 guest 對應到 host。此對應應在 URL 範本的末尾指定，使用 & 和 > 作為 guest 到 host 的分隔符

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']

定義啟用的語言環境的另一個好處是，它們會自動新增為特殊的 _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

type: boolean default: 當啟用偵錯模式時為 true，否則為 false。

如果為 true，Symfony 會將 X-Robots-Tag: noindex HTTP 標籤新增至所有回應 (除非您自己的應用程式新增了該標頭，在這種情況下，它不會被修改)。這個 X-Robots-Tag HTTP 標頭 告訴搜尋引擎不要為您的網站建立索引。如果意外地在偵錯模式下發布您的網站，此選項是一種保護措施。

trusted_hosts

type: array | string default: ['%env(default::SYMFONY_TRUSTED_HOSTS)%']

7.2

在 Symfony 7.2 中，此選項的預設值已從 [] 變更為儲存在 SYMFONY_TRUSTED_HOSTS 環境變數中的值。

許多不同的攻擊已被發現，它們依賴於各種軟體 (網路伺服器、反向代理、網路框架等) 處理 Host 標頭時的不一致性。基本上，每次框架產生絕對 URL (例如，在傳送電子郵件以重設密碼時)，主機都可能已被攻擊者操縱。

另請參閱

您可以閱讀 HTTP Host header attacks 以獲取有關這些攻擊的更多資訊。

Symfony 的 Request::getHost() 方法可能容易受到其中一些攻擊，因為它取決於您的網路伺服器的配置。避免這些攻擊的一個簡單解決方案是配置您的 Symfony 應用程式可以回應的主機列表。這就是 trusted_hosts 選項的目的。如果傳入請求的主機名稱與此列表中的任何一個正規表示式不符，則應用程式將不會回應，並且使用者將收到 400 回應。

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

主機也可以設定為回應任何子網域，例如透過 ^(.+\.)?example\.com$。

此外，您也可以使用 Request::setTrustedHosts() 方法在前端控制器中設定受信任的主機。

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

此選項的預設值為空陣列，表示應用程式可以回應任何給定的主機。

另請參閱

請在 Security Advisory Blog post 中閱讀更多相關資訊。

form

已啟用

type: boolean default: true 或 false，取決於您的安裝情況

是否在服務容器中啟用表單服務。如果您不使用表單，將此項設定為 false 可能會提高應用程式的效能，因為載入到容器中的服務會減少。

當配置其中一個子設定時，此選項將自動設定為 true。

注意

這將自動啟用驗證。

另請參閱

有關更多詳細資訊，請參閱表單。

field_name

type: string default: _token

這是您應該給表單的 CSRF 令牌欄位的欄位名稱。

csrf_protection

另請參閱

有關 CSRF 保護的更多資訊，請參閱如何實作 CSRF 保護。

已啟用

type: boolean default: true 或 false，取決於您的安裝情況

此選項可用於停用所有表單的 CSRF 保護。但是您也可以停用個別表單的 CSRF 保護。

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

如果您正在使用表單，但想要避免啟動您的 session (例如，在僅限 API 的網站中使用表單)，則需要將 csrf_protection 設定為 false。

error_controller

type: string default: 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

fragments

另請參閱

在HTTP 快取文章中了解更多關於 fragments 的資訊。

已啟用

類型: boolean 預設: false

是否啟用 fragment listener。Fragment listener 用於獨立於頁面的其餘部分呈現 ESI fragments。

當配置其中一個子設定時，此設定會自動設定為 true。

hinclude_default_template

type: string default: null

設定在 fragment 載入期間或 JavaScript 被停用時顯示的內容。這可以是範本名稱或內容本身。

另請參閱

有關 hinclude 的更多資訊，請參閱建立和使用範本。

path

type: string default: /_fragment

fragments 的路徑前綴。只有當請求以此路徑開頭時，才會執行 fragment listener。

http_client

當安裝 HttpClient 組件後，HTTP client 可作為名為 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

可以定義多個預先配置的 HTTP client 服務，每個服務的服務名稱都定義為 scoped_clients 下的鍵。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
                # ...

為 scoped clients 定義的選項僅適用於符合其 base_uri 或 scope 選項 (如果已定義) 的 URL。不符合的 URL 始終使用預設選項。

每個 scoped client 也定義了對應的具名自動裝配別名。例如，如果您使用 Symfony\Contracts\HttpClient\HttpClientInterface $myApiClient 作為引數的類型和名稱，則自動裝配會將 my_api.client 服務注入到您的自動裝配類別中。

auth_basic

類型: string

用於建立 Authorization HTTP 標頭的使用者名稱和密碼，用於 HTTP Basic 身份驗證。此選項的值必須遵循 username:password 格式。

auth_bearer

類型: string

用於建立 Authorization HTTP 標頭的令牌，用於 HTTP Bearer 身份驗證 (也稱為令牌身份驗證)。

auth_ntlm

類型: string

用於建立 Authorization HTTP 標頭的使用者名稱和密碼，用於 Microsoft NTLM 身份驗證協定。此選項的值必須遵循 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 https://symfony.dev.org.tw https://symfony.dev.org.tw
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 socket。

buffer

type: boolean | Closure

緩衝回應意味著您可以多次存取其內容，而無需再次執行請求。當回應的內容類型為 text/*、application/json 或 application/xml 時，預設會啟用緩衝。

如果此選項是布林值，則當值為 true 時，回應會被緩衝。如果此選項是 closure，則當傳回值為 true 時，回應會被緩衝 (closure 接收一個包含回應標頭的陣列作為引數)。

cafile

類型: string

憑證授權檔案的路徑，其中包含一個或多個用於驗證其他伺服器憑證的憑證。

capath

類型: string

包含一個或多個憑證授權檔案的目錄路徑。

ciphers

類型: string

TLS 連線允許的密碼名稱列表。它們可以用冒號、逗號或空格分隔 (例如 'RC4-SHA:TLS13-AES-128-GCM-SHA256')。

crypto_method

類型: integer

要接受的 TLS 最低版本。該值必須是 PHP 定義的 STREAM_CRYPTO_METHOD_TLSv*_CLIENT 常數之一。

delay

type: integer default: 1000

用於計算重試之間等待時間的初始延遲，以毫秒為單位。

已啟用

類型: boolean 預設: false

是否啟用對重試失敗的 HTTP 請求的支援。當配置其中一個子設定時，此設定會自動設定為 true。

extra

類型: array

要傳遞給 HTTP client 以供進一步使用的任意附加資料。當裝飾現有 client 時，這可能特別有用。

headers

類型: array

在發出請求之前新增的 HTTP 標頭的關聯陣列。此值必須使用 ['header-name' => 'value0, value1, ...'] 格式。

http_codes

type: array default: DEFAULT_RETRY_STATUS_CODES()

觸發請求重試的 HTTP 狀態碼列表。

http_version

type: string | null default: null

要使用的 HTTP 版本，通常為 '1.1' 或 '2.0'。將其保留為 null 以讓 Symfony 自動選擇最佳版本。

jitter

type: float default: 0.1 (必須介於 0.0 和 1.0 之間)

此選項為延遲新增了一些隨機性。這對於避免在完全相同的時間向伺服器發送多個請求非常有用。隨機性計算為 delay * jitter。例如：如果延遲為 1000ms 且 jitter 為 0.2，則實際延遲將介於 800 和 1200 之間的數字 (1000 +/- 20%)。

local_cert

類型: string

包含 HTTP client 使用的 PEM 格式 憑證的檔案路徑。這通常與 local_pk 和 passphrase 選項結合使用。

local_pk

類型: string

包含在 local_cert 選項中定義的憑證的 PEM 格式 私鑰的檔案路徑。

max_delay

type: integer default: 0

重試之間等待的最長初始毫秒數。使用 0 不限制持續時間。

max_duration

type: float default: 0

請求和回應允許花費的最長執行時間，以秒為單位。小於或等於 0 的值表示無限制。

max_host_connections

type: integer default: 6

定義同時開啟到單一主機的最大連線數 (將「主機」視為與「主機名稱 + 連接埠號碼」對相同)。此限制也適用於代理連線，其中代理被視為應用此限制的主機。

max_redirects

type: integer default: 20

要追蹤的最大重新導向次數。使用 0 以不追蹤任何重新導向。

max_retries

type: integer default: 3

失敗請求的最大重試次數。當達到最大值時，client 會傳回最後收到的回應。

multiplier

type: float default: 2

每次發生重試時，此值都會乘以延遲，以便在時間上分散重試，而不是依序進行所有重試。

no_proxy

type: string | null default: null

不需要代理即可連線的主機的逗號分隔列表，即使已配置代理。使用 '*' 萬用字元來比對所有主機，並使用空字串來比對無 (停用代理)。

passphrase

類型: string

用於加密儲存在 local_cert 選項中定義的檔案中的憑證的密碼。

peer_fingerprint

類型: array

當協商 TLS 連線時，伺服器會傳送憑證以指示其身份。從此憑證中提取公鑰，如果它與此選項中提供的任何公鑰都不完全符合，則會在傳送或接收任何資料之前中止連線。

此選項的值是 algorithm => hash 的關聯陣列 (例如 ['pin-sha256' => '...'])。

proxy

type: 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 client 使用的 DNS 快取，以避免對這些主機進行 DNS 查找。當在將 URL 傳遞給 client 之前檢查 IP 時，以及為了讓您的測試更輕鬆，此選項非常有用。

此選項的值是 domain => IP address 的關聯陣列 (例如 ['symfony.com' => '46.137.106.254', ...])。

retry_failed

類型: array

此選項配置 HTTP client 在某些請求失敗時的行為，包括要重試的請求類型和重試次數。該行為由以下選項定義

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

僅適用於 scoped clients：URL 必須符合的正規表示式，然後才能套用所有其他非預設選項。預設情況下，scope 是從 base_uri 衍生而來。

timeout

type: float default: 取決於您的 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 來啟用 profiler。當您使用 Symfony Flex 安裝它時，profiler 在 dev 和 test 環境中啟用。

注意

profiler 的運作獨立於 Web Developer Toolbar，請參閱關於如何停用/啟用工具列的WebProfilerBundle 配置。

collect

類型: boolean 預設: true

此選項配置 profiler 在啟用時的行為方式。如果設定為 true，則 profiler 會收集所有請求的資料。如果您只想按需收集資訊，您可以將 collect 標誌設定為 false 並手動啟動資料收集器

1
$profiler->enable();

collect_parameter

type: string default: null

這指定查詢參數、body 參數或請求屬性的名稱，用於為每個請求啟用或停用 profiler 的資料收集。將其與 collect 選項結合使用以按需啟用/停用 profiler

  • 如果 collect 選項設定為 true，但此參數存在於請求中，並且具有 true、yes、on 或 1 以外的任何值，則不會收集請求資料；
  • 如果 collect 選項設定為 false，但此參數存在於請求中，並且值為 true、yes、on 或 1，則將會收集請求資料。

only_exceptions

類型: boolean 預設: false

當設定為 true 時，只有在處理請求期間拋出例外時，才會啟用 profiler。

only_main_requests

類型: boolean 預設: false

當設定為 true 時，profiler 將僅在主要請求上啟用 (而不是在子請求上)。

dsn

type: string default: file:%kernel.cache_dir%/profiler

用於儲存 profiling 資訊的 DSN。

collect_serializer_data

類型: boolean 預設: false

將此選項設定為 true 以啟用 serializer 資料收集器及其 profiler 面板。當此選項為 true 時，所有 normalizers 和 encoders 都會由可追蹤的實作進行裝飾，這些實作會收集關於它們的 profiling 資訊。

rate_limiter

name

type: prototype

您要建立的速率限制器的名稱。

lock_factory

type: string default: lock.factory

用於建立鎖的服務。該服務必須是 LockFactory 類別的實例。

policy

類型: string 必填

要使用的速率限制演算法的名稱。範例名稱為 fixed_window、sliding_window 和 no_limit。有關更多資訊，請參閱速率限制器策略)。

request

formats

type: array default: []

此設定用於將其他請求格式 (例如 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'

router

resource

類型: string 必填

主要路由資源 (例如 YAML 檔案) 的路徑，其中包含路由器應載入的路由和匯入。

type

類型: string

資源的類型，以提示載入器關於格式。當您使用具有預期檔案副檔名 (.xml、.yaml、.php) 的預設路由器時，這不是必需的。

default_uri

類型: string

用於在非 HTTP 環境中產生 URL 的預設 URI (請參閱在命令中產生 URL)。

http_port

type: integer default: 80

用於正常 http 請求的連接埠 (這在比對 scheme 時使用)。

https_port

type: integer default: 443

用於 https 請求的連接埠 (這在比對 scheme 時使用)。

strict_requirements

type: mixed default: true

決定路由產生器的行為。當產生具有特定參數要求的路由時，如果使用的參數不符合這些要求，產生器的行為可能會有所不同。

該值可以是以下之一

true
當不符合要求時拋出例外；
false
當不符合要求時停用例外，並傳回 '' 作為替代；
null
停用檢查要求 (因此，即使要求不符合也比對路由)。

建議在開發環境中使用 true，而在生產環境中可能偏好 false 或 null。

utf8

類型: boolean 預設: true

當此選項設定為 true 時，用於路由參數需求中的正規表示式將使用 utf-8 修飾符執行。例如，當使用 . 時，這將匹配任何 UTF-8 字元，而不是僅匹配單個位元組。

如果您的應用程式的字元集為 UTF-8（如您的 Kernel 的 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

包含金庫解密密鑰的 env var 名稱。預設情況下，此值將從 base64 解碼。

local_dotenv_file

類型：string 預設值：%kernel.project_dir%/.env.%kernel.environment%.local

本地 .env 檔案的路徑。此檔案必須包含金庫解密金鑰，由 decryption_env_var 選項提供。

vault_directory

類型：string 預設值：%kernel.project_dir%/config/secrets/%kernel.runtime_environment%

用於儲存密鑰金庫的目錄。預設情況下，路徑包含 kernel.runtime_environment 參數的值。

session

storage_factory_id

類型：string 預設值：session.storage.factory.native

用於建立儲存 Session 的 SessionStorageInterface 的服務 ID。此服務可透過 session.storage.factory 服務別名在 Symfony 應用程式中使用。該類別必須實作 SessionStorageFactoryInterface。要查看所有可用儲存的列表，請執行

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

handler_id

type: string | null default: null

如果未設定 framework.session.save_path，則此選項的預設值為 null，這表示使用在 php.ini 中設定的 session 處理器。如果設定了 framework.session.save_path 選項，則 Symfony 使用原生檔案 session 處理器儲存 session。

可以將 session 儲存在資料庫中，也可以使用 DSN 設定 session 處理器

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'

注意

支援的 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

這指定了 session cookie 的名稱。

如果未設定，將依賴 php.ini 的 session.name 指令。

類型: integer

這決定了 session 的生命週期 - 以秒為單位。將此值設定為 0 表示 cookie 在瀏覽器 session 的持續時間內有效。

如果未設定，將依賴 php.ini 的 session.cookie_lifetime 指令。

類型: string

這決定了在 session cookie 中設定的路徑。

如果未設定，將依賴 php.ini 的 session.cookie_path 指令。

cache_limiter

類型：string 預設值：0

如果設定為 0，Symfony 將不會設定任何與快取相關的標頭，並且它將依賴 php.ini 的 session.cache_limiter 指令。

與其他 session 選項不同，cache_limiter 被設定為常規的 容器參數

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

請注意，如果您設定了它，您也必須將其他與 session 相關的選項設定為參數。

類型: string

這決定了在 session 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

這定義了每次 session 初始化時啟動垃圾回收 (GC) 程序的機率。機率是透過使用 gc_probability / gc_divisor 計算的，例如 1/100 表示每次請求都有 1% 的機會啟動 GC 程序。

如果未設定，Symfony 將使用 php.ini 設定檔中 session.gc_probability 指令的值。

7.2

在 Symfony 7.2 中引入了依賴 php.ini 的指令作為 gc_probability 的預設值。

gc_maxlifetime

類型: integer

這決定了數據在多少秒後將被視為「垃圾」並可能被清除。垃圾回收可能在 session 開始時發生，並取決於 gc_divisor 和 gc_probability。

如果未設定，將依賴 php.ini 的 session.gc_maxlifetime 指令。

sid_length

類型: integer

這決定了 session ID 字串的長度，它可以是介於 22 和 256（包括兩者）之間的整數，32 是建議值。較長的 session ID 更難以猜測。

如果未設定，將依賴 php.ini 的 session.sid_length 指令。

7.2

sid_length 選項在 Symfony 7.2 中已被棄用。由於 PHP 8.4 已棄用相關選項，因此未提供替代方案。

sid_bits_per_character

類型: integer

這決定了編碼 session ID 字元中的位元數。可能的值為 4 (0-9, a-f)、5 (0-9, a-v) 和 6 (0-9, a-z, A-Z, "-", ",")。位元越多，session 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

這決定了要傳遞給儲存處理器的引數。如果您選擇預設檔案處理器，則這是建立 session 檔案的路徑。

如果 null，將依賴 php.ini 的 session.save_path 指令

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

metadata_update_threshold

type: integer default: 0

這是更新/寫入 session 元數據之間要等待的秒數。如果由於某些原因，您想要限制 session 持續存在的頻率，而不是在每次請求時都這樣做，這可能會很有用。

已啟用

類型: boolean 預設: true

是否在框架中啟用 session 支援。

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

use_cookies

類型: boolean

這指定了 session ID 是否使用 cookie 儲存在客户端。

如果未設定，將依賴 php.ini 的 session.use_cookies 指令。

ssi

已啟用

類型: boolean 預設: false

是否在您的應用程式中啟用 SSI 支援。

assets

base_path

類型: string

此選項允許您定義用於資源的基本路徑

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

base_urls

類型: array

此選項允許您定義用於資源的基本 URL。如果提供了多個基本 URL，Symfony 將在每次產生資源的路徑時從集合中選擇一個

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

packages

您可以將資源分組到套件中，以為它們指定不同的基本 URL

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

現在您可以在範本中使用 avatars 套件

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

每個套件都可以設定以下選項

version

類型: string

此選項用於透過全域添加查詢參數到所有呈現的資源路徑（例如 /images/logo.png?v2）來失效資源上的快取。這僅適用於透過 Twig asset() 函數（或 PHP 等效項）呈現的資源。

例如，假設您有以下內容

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'

現在，相同的資源將呈現為 /images/logo.png?v2。如果您使用此功能，則在每次部署之前，您必須手動增加 version 值，以便查詢參數發生變更。

您也可以透過 version_format 選項控制查詢字串的工作方式。

注意

此參數不能與 version_strategy 或 json_manifest_path 同時設定。

提示

與所有設定一樣，您可以使用參數作為 version 的值。這使得在每次部署時更容易增加快取。

version_format

類型：string 預設值：%%s?%%s

這指定了一個 sprintf 模式，該模式將與 version 選項一起使用，以建構資源的路徑。預設情況下，該模式會將資源的版本添加為查詢字串。例如，如果 version_format 設定為 %%s?version=%%s 且 version 設定為 5，則資源的路徑將為 /images/logo.png?version=5。

注意

格式字串中的所有百分比符號 (%) 都必須加倍以逸出字元。如果沒有逸出，值可能會在不經意間被解釋為 服務容器。

提示

某些 CDN 不支援透過查詢字串進行快取失效，因此將版本注入到實際檔案路徑中是必要的。值得慶幸的是，version_format 不僅限於產生版本化的查詢字串。

該模式接收資源的原始路徑和版本作為其第一個和第二個參數。由於資源的路徑是一個參數，因此您無法就地修改它（例如 /images/logo-v5.png）；但是，您可以使用 version-%%2$s/%%1$s 的模式為資源的路徑添加前綴，這將導致路徑 version-5/images/logo.png。

然後可以使用 URL 重寫規則來忽略版本前綴，然後再提供資源。或者，您可以將資源複製到適當的版本路徑作為部署過程的一部分，並忘記任何 URL 重寫。如果您希望舊的資源版本在其原始 URL 上保持可存取，則後者選項很有用。

version_strategy

type: string default: null

應用於資源的 資源版本策略的服務 ID。此選項可以針對所有資源全域設定，也可以針對每個資源套件個別設定

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'

注意

此參數不能與 version 或 json_manifest_path 同時設定。

json_manifest_path

type: string default: null

指向 manifest.json 檔案的檔案路徑或絕對 URL，該檔案包含資源名稱及其各自編譯名稱的關聯陣列。使用「manifest」檔案的常見快取失效技術的工作原理是在前端編譯程序期間寫出附加了「雜湊」的檔案名稱的資源（例如 main.ae433f1cb.css）。

提示

Symfony 的 Webpack Encore 支援輸出雜湊資源。此外，這可以整合到許多其他工作流程中，包括使用 webpack-manifest-plugin 的 Webpack 和使用 gulp-rev 的 Gulp。

此選項可以針對所有資源全域設定，也可以針對每個資源套件個別設定

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'

注意

如果指定了全域 manifest 檔案，則此參數不能與 version 或 version_strategy 同時設定。此外，如果指定了全域 manifest 檔案，則不能在套件範圍內將此選項設定為 null。

提示

如果您請求的資源在 manifest.json 檔案中找不到，則將傳回原始的 - 未修改的 - 資源路徑。您可以將 strict_mode 設定為 true，以便在找不到資源時取得例外。

注意

如果設定了 URL，則每次請求時都會使用 http_client 下載 JSON manifest。

strict_mode

類型: boolean 預設: false

啟用後，嚴格模式會斷言所有請求的資源都在 manifest 檔案中。此選項對於偵測錯字或遺失的資源很有用，建議值為 %kernel.debug%。

translator

cache_dir

類型：string | null 預設值：%kernel.cache_dir%/translations

定義儲存翻譯快取的目錄。使用 null 以停用此快取。

已啟用

type: boolean default: true 或 false，取決於您的安裝情況

是否在服務容器中啟用 translator 服務。

fallbacks

類型：string|array 預設值：default_locale 的值

當找不到目前語言環境的翻譯鍵時，使用此選項。

另請參閱

有關更多詳細資訊，請參閱 翻譯。

logging

預設值：當啟用偵錯模式時為 true，否則為 false。

當 true 時，每當翻譯器找不到給定鍵的翻譯時，都會建立日誌條目。日誌會記錄到 translation 通道，對於在後備語言環境中有翻譯的鍵，記錄在 debug 級別，如果根本沒有可用的翻譯，則記錄在 warning 級別。

formatter

類型：string 預設值：translator.formatter.default

用於格式化翻譯訊息的服務 ID。服務類別必須實作 MessageFormatterInterface。

paths

type: array default: []

此選項允許定義組件將在其中尋找翻譯檔案的路徑陣列。稍後添加的路徑優先順序更高（來自稍後路徑的翻譯會覆寫較早路徑的翻譯）。來自 default_path 的翻譯比來自所有這些路徑的翻譯具有更高的優先順序。

default_path

類型：string 預設值：%kernel.project_dir%/translations

此選項允許定義儲存應用程式翻譯檔案的路徑。

providers

type: array default: []

此選項啟用並設定翻譯提供器，以將您的翻譯推送到/從第三方翻譯服務拉取。

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

已啟用

type: boolean default: true 或 false，取決於您的安裝情況

validation

auto_mapping

type: array default: []

定義將被內省以將自動驗證約束添加到它們的 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']

已啟用

type: boolean default: 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

type: string default: null

預設情況下，NotCompromisedPassword 約束使用 haveibeenpwned.com 提供的公用 API。此選項允許定義不同的但相容的 API 端點來進行密碼檢查。例如，當 Symfony 應用程式在無法公開存取網際網路的內部網路中執行時，這很有用。

static_method

類型：string | array 預設值：['loadValidatorMetadata']

定義呼叫以載入類別的驗證元數據的靜態方法的名稱。您可以定義字串陣列，其中包含多個方法的名稱。在這種情況下，將按順序呼叫所有這些方法以載入元數據。

password_strength

PasswordStrength 約束驗證提交的字串熵是否與最小熵值分數匹配。

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/"

annotations

cache

類型：string 預設值：php_array

此選項可以是以下值之一

php_array
使用 PHP 陣列在記憶體中快取註解
file
使用檔案系統快取註解
none
停用註解的快取

file_cache_dir

類型：string 預設值：%kernel.cache_dir%/annotations

用於儲存註解快取檔案的目錄，以防 annotations.cache 設定為 'file'。

debug

類型: boolean 預設: %kernel.debug%

是否啟用快取的偵錯模式。如果啟用，當原始檔案變更時（程式碼和註解變更），快取將自動更新。出於效能考量，建議在生產環境中停用偵錯模式，如果您使用預設值，這將自動發生。

serializer

已啟用

type: boolean default: 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

type: array default: []

此選項允許定義路徑陣列，其中包含組件將在其中尋找其他序列化檔案的檔案或目錄。

default_context

type: array default: []

一個包含預設上下文選項的地圖，將用於每個 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

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 服務相同的可用适配器。

directory

類型：string 預設值：%kernel.cache_dir%/pools

從 cache.adapter.filesystem 适配器（包括 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

type: string default: memcached://127.0.0.1

Memcached 提供者使用的 DSN。此提供者以 cache.default_memcached_provider 服務提供。

default_pdo_provider

type: string default: 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
name

type: prototype

您要建立的池名稱。

注意

您的池名稱必須與 cache.app 或 cache.system 不同。

adapter

type: string default: cache.app

要使用的配接器服務名稱。您可以指定遵循 cache.adapter.[type] 模式的預設服務之一。或者，您可以將另一個快取池指定為基礎，這將使此池繼承基礎池的設定作為預設值。

注意

您的服務需要實作 Psr\Cache\CacheItemPoolInterface 介面。

public

類型: boolean 預設: false

您的服務是否應為公開。

tags

type: boolean | string default: null

您的服務是否應能夠處理標籤。也可以是將儲存標籤的另一個快取池的服務 ID。

default_lifetime

type: integer | string

快取項目的預設生命週期。給定整數值以秒為單位設定預設生命週期。字串值可以是 ISO 8601 時間間隔，例如 "PT5M" 或 strtotime() 接受的 PHP 日期表示式，例如 "5 minutes"。

如果未提供值，快取配接器將回退到實際快取儲存體上的預設值。

provider

類型: string

如果您不想使用在 cache 下設定為 default_X_provider 的內容，請覆寫預設服務名稱或 DSN。請參閱上面預設提供者設定的描述，以取得有關如何指定特定提供者的資訊。

clearer

類型: string

用於清除 PSR-6 快取的快取清除器。

另請參閱

如需更多資訊，請參閱 Psr6CacheClearer。

prefix_seed

type: string default: _%kernel.project_dir%.%kernel.container_class%

此值用作快取項目金鑰產生的「命名空間」的一部分。常見的做法是使用應用程式的唯一名稱（例如 symfony.com），因為這樣可以防止在將多個應用程式部署到共用相同快取後端的相同路徑（在不同的伺服器上）時發生命名衝突。

當使用 藍/綠部署 策略，以及更廣泛地說，當您需要抽象化實際部署目錄時（例如，離線預熱快取時），這也很有用。

注意

prefix_seed 選項在編譯時使用。這表示在容器編譯後對此值所做的任何變更都不會生效。

lock

type: string | array

預設鎖定配接器。如果未定義，則在可用時將值設定為 semaphore，否則設定為 flock。也允許 Store 的 DSN。

已啟用

類型: boolean 預設: true

是否啟用對鎖定的支援。當設定其中一個子設定時，此設定會自動設定為 true。

resources

類型: array

要由框架擴充功能建立的鎖定儲存體對應，其中名稱作為金鑰，DSN 作為值

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

另請參閱

如需更多詳細資訊，請參閱使用鎖定處理並行。

name

type: prototype

您要建立的鎖定名稱。

semaphore

type: string | array

預設號誌配接器。也允許 Store 的 DSN。

已啟用

類型: boolean 預設: true

是否啟用對號誌的支援。當設定其中一個子設定時，此設定會自動設定為 true。

resources

類型: array

要由框架擴充功能建立的號誌儲存體對應，其中名稱作為金鑰，DSN 作為值

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

type: prototype

您要建立的號誌名稱。

mailer

dsn

type: string default: null

郵件程式使用的 DSN。當可能使用多個 DSN 時，請改用 transports 選項（請參閱下方）。

transports

類型: array

郵件程式可以使用的DSN 清單。傳輸名稱是金鑰，而 dsn 是值。

message_bus

type: string default: null 或如果已安裝 Messenger 元件，則為預設匯流排

使用 Messenger 元件 時要使用的訊息匯流排的服務識別碼（例如 messenger.default_bus）。

envelope

sender

類型: string

「信封寄件者」用作 SMTP 會話期間 MAIL FROM 的值。此值會覆寫程式碼中設定的任何其他寄件者。

recipients

類型: array

「信封收件者」用作 SMTP 會話期間 RCPT TO 的值。此值會覆寫程式碼中設定的任何其他收件者。

1
2
3
4
5
6
# config/packages/mailer.yaml
framework:
    mailer:
        dsn: 'smtp://127.0.0.1:25'
        envelope:
            recipients: ['admin@symfony.com', 'lead@symfony.com']

headers

類型: array

要新增至電子郵件的標頭。金鑰（xml 格式的 name 屬性）是標頭名稱，值是標頭值。

另請參閱

如需更多資訊，請參閱全域設定電子郵件

messenger

已啟用

類型: boolean 預設: true

是否啟用 Messenger。

另請參閱

如需更多詳細資訊，請參閱 Messenger 元件 文件。

已啟用

type: boolean default: true 或 false，取決於您的安裝情況

將 Link HTTP 標頭新增至回應。

webhook

webhook 選項（及其子選項）用於設定應用程式中定義的 webhook。請在 Webhook 文件中閱讀有關選項的更多資訊。

workflows

類型: array

要由框架擴充功能建立的工作流程清單

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

另請參閱

另請參閱關於在 Symfony 應用程式中使用工作流程的文章。

已啟用

類型: boolean 預設: false

是否啟用對工作流程的支援。當設定其中一個子設定時，此設定會自動設定為 true。

name

type: prototype

您要建立的工作流程名稱。

audit_trail

類型: boolean

如果設定為 true，則將啟用 AuditTrailListener。

initial_marking

type: string | array

places 或 empty 之一。如果非 null 且支援的物件尚未透過工作流程初始化，則將設定此位置。

marking_store

類型: array

每個標記儲存體都可以定義下列任何選項

  • property (type: string default: marking)
  • service (type: string)
  • type (type: string allow value: 'method')
metadata

類型: array

工作流程組態可用的中繼資料。請注意，places 和 transitions 也可以有自己的 metadata 條目。

places

類型: array

工作流程組態的所有可用位置（type: string）。

supports

type: string | array

工作流程組態支援的物件的 FQCN（完整類別名稱），如果支援多個物件，則為 FQCN 陣列。

support_strategy

類型: string

transitions

類型: array

每個標記儲存體都可以定義下列任何選項

  • from (type: string 或 array) 來自 places 的值，workflow 和 state_machine 都允許多個值；
  • guard (type: string) ExpressionLanguage 相容表示式，用於封鎖轉換；
  • name (type: string) 轉換的名稱；
  • to (type: string 或 array) 來自 places 的值，僅 workflow 允許使用多個值。
type

type: string possible values: '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

您設定例外狀況的順序很重要，因為 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
    版本