如何在已編譯的 Drupal Twig 中除錯

在 Drupal 7 時,我們更新 tpl 檔案後直接重新整理頁面就能看到更新的結果,但是 Drupal 8、9 快取機制已經不同,因此會遇到更新 twig 之後重新整理頁面後內容卻沒有更新的問題,接下來主要會整理與翻譯 Debugging compiled Twig templates 這篇文章來說明 Drupal 的快取機制以及如何在已編譯的 Twig 進行除錯。

Drupal 中的 Twig 如何運作

Twig 預設會將樣板編譯為 PHP,並將編譯後的樣板儲存在文件系統中(預設會在 sites/default/files/php/twig)

在 Twig 完成一些標記(markup)後,Render API 中會有另一層快取。Render API 會取用 Twig 建立的標記,並且通常會以這樣的方式對其進行快取,即在這之後的頁面請求與 Twig 無關(如果快取資料保持不變的話),因此,我們可能會遇到 Twig 的 除錯或 auto_reload 設定沒有作用,實際上是因為需要清除快取(或是禁用快取)。

可以透過 Drupal 的清除快取界面清除快取,對於正在進行開發的網站,可以更改 Drupal 的設定讓 Render API 不快取任何內容。但在測時時一定要開啟快取,否則很容易錯過與快取相關的錯誤,這些錯誤將在啟用快取的環境中發生。

設定 Twig 和 Render API 以進行除錯

為了除錯,必須分別設定 Twig 和 Render API:

  1. Twig 提供選項 以用於除錯設定,自動重新載入(重新編譯)樣板以及將已編譯的樣板快取儲存到文件系統中,這些可以在網站的 services.yml 進行設定
  2. Render API 的快取可以在網站的 settings.php 進行設定

接下來會詳細介紹這兩個階段

1. 設定 Twig 以進行除錯

我們可以使用 Drupal Console 或手動處理,建議是手動處理

如何手動開啟除錯功能

  1. 找到網站的 services.yml,可能位於 sites/default/services.yml
  2. 如果 services.yml 不存在,複製 default.services.yml 並將其重命名為 services.yml
  3. 編輯 services.yml 並視需求啟用以下選項:
    • Twig debugging options
    • Twig auto-reload
    • Twig cache(稍後會有更多資訊,但大多時候不需要設定這個選項)
  4. 重建快取

在 services.yml 中找到 twig.config 並進行設定, 例如:

parameters:
  twig.config:
    debug: true 

Twig 除錯設定選項

注意:請在正式網站時改回這三個選項的預設值!

Edit

debug (default: false)

當 debug: true 時:

  • 每個 Twig 樣板標記周圍會提供 HTML 註釋,這些註釋包含版型資訊,例如樣板檔案名稱建議
  • 請注意,此除錯標記將導致直接檢查渲染的 HTML 的自動化測試失敗。 進行自動化測試時,應將 twig_debug 設定為 false
  • 可以在 Twig 樣板中使用 dump() 印出變數資訊
  • 每當程式碼更改時,將自動重新編譯 Twig 樣板(請參見下面的 auto_reload)
Edit

auto_reload (default: null, determined by debug above)

當 auto_reload: true 時:

  • 每當程式碼更改時,會自動重新編譯 Twig 樣板。 如果不設定 twig_auto_reload,則設定會取絕於 twig_debug 的值
  • 除非有需要 auto_reload 且不進行除錯,否則無需進行此設定。 只需設定 debug: true
Edit

cache (default: true, but overridden by debug above)

當 cache: false 時:

  • 除非有特定的使用情境,否則請不要停用 Twig 快取。 啟用 Twig 除錯時(如果出於某種原因不想啟用除錯模式,則僅啟用 auto_reload),Twig 快取不會阻礙我們。 停用 Twig 快取只會使開發體驗變慢,因為無論是否已編輯每個樣板,都需要對其進行編譯。 此外,如果編譯後的 Twig 樣板(PHP 類別,預設在 sites/default/files/php/twig)沒有進行快取,則無法輕鬆查看或除錯
  • 預設的狀況下,會編譯 Twig 樣板並將其存儲在文件系統中以提高性能。 停用 Twig 快取則會在每次使用樣板時重新編譯它們。 在大多數情況下,應啟用上面的 twig_auto_reload 設定,而不是停用 Twig 快取

如何用 Drupal Console 開啟除錯功能

首先需安裝 Drupal Console 並執行以下指令

drupal site:mode dev

請注意,這會更改很多設定,包含 sites/default/services.yml 中以下值的更改

twig.config: { debug: true }

2. 設定 Render API 快取以進行除錯

預設情況下,Drupal 會對渲染(Render)區塊和實體(entities)進行快取以加快後續頁面載入的速度。 因此 Twig 樣板的更改並不會立即生效。 將渲染快取設為 Null 後端可以有效禁用此功能。

要禁用渲染快取,需要在 settings.php 或 settings.local.php 進行以下設定

// 此行在 settings.php 尚未設定,settings.local.php 則預設已設定
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

// 此兩行 settings.php 尚未設定,settings.local.php 則預設是註解狀態
$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

注意:

  • settings.php:請注意不要將以上設定加入到正式網站(production site)
  • settings.local.php:需先取消 settings.php 內載入 settings.local.php 的註解

這裡建議使用 settings.local.php,如何啟用 settings.local.php:

  1. 取消 settings.php 內載入 settings.local.php 的註解
  2. 複製 sites/example.settings.local.php 到 sites/default/settings.local.php
  3. 重建快取 drush cr

完成了!

設定完 Twig 和 Render API 之後清除所有快取:我們可以使用 Drush,也可以到「設定 -> 效能」清除快取。最後,我們可以在頁面原始碼中看到 Twig 除錯資訊,當我們編輯並儲存 Twig 樣板後重新整理頁面時即可以看到更新後的 Twig 樣板