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

2021-06-30 By poliphilo

在 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 樣板

  • poliphilo 的 BLOG