AboutCommand::add(),不必實作專用指令,就能在 php artisan about 的輸出中加入套件專用的區段。
官方文件中有註冊的基本範例。本頁會深入確認 Laravel 13 的實作,探討收集資訊的時機、JSON 的型別、區段名稱的衝突,以及測試中的註冊狀態。
在提供者中註冊顯示內容
下列範例的前提是,courier.enabled 與 courier.driver 已註冊為套件的設定。設定的註冊方式請參閱套件設定的合併與快取。
runningInConsole() 是用來避免在 HTTP 請求中進行不必要註冊的條件。它並不是只在執行 about 時才成立的條件,其他 Artisan 指令中也會進行註冊。不過,上方閉包內的設定讀取在註冊時並不會執行。
將註冊時機與求值時機分開思考
Laravelv13.35.0 的 add() 不會當場收集資料,而是將註冊用的閉包加入靜態的 $customDataResolvers。執行 about 時才會組成顯示用的資料,並對已註冊的資料取得用閉包求值。
比起在 add() 外部先讀取設定值並固定在陣列中,在閉包內取得更能反映指令執行時的狀態。另一方面,--only 篩選是在資料取得用閉包求值之後才進行。
Acme Courier 的閉包仍會被求值。沒有顯示與沒有處理是兩回事。
因此,附加資訊應從設定值或輕量的本機狀態取得。若加入外部 API 的連通確認、資料庫查詢、檔案改寫等處理,連查看無關區段的指令都可能變慢或失敗。連通確認與修復請拆分到專用的 Artisan 指令中。
兼顧 CLI 顯示與 JSON 型別
若只想確認套件的資訊,請指定將區段名稱轉為小寫 snake case 後的值。以Acme Courier 為例即為 acme_courier。
courier.enabled 為 true、courier.driver 為 log 時,JSON 會是下列形式。
Enabled 會顯示為 ENABLED。AboutCommand::format() 是可分別指定 CLI 用的 console 與 JSON 用的 json 的輔助方法。上方範例只指定了 console,因此 JSON 會回傳原本的 boolean 值。不需要將 CLI 的顯示字串直接沿用到 JSON。
如範例般使用以空白分隔的一般英文單字作為名稱,篩選與 JSON 鍵會更容易處理。自動化處理所參照的鍵可能因顯示名稱的變更而改變,因此請在發布時確認相容性。
區段請使用套件專用的名稱
add() 會將項目附加到同一個區段。指定同名的區段並不會取代先前註冊的全部內容。
請選擇像 Acme Courier 這樣能與其他套件區分的名稱,並僅在必要時才加入 Laravel 標準的 Environment、Cache、Drivers、Storage。
若在同一區段中重複註冊同名項目,CLI 中可能會留下多行,但 JSON 中會彙整到同一個鍵並保留後者的值。此外,即使寫法不同,也請避免轉換為 snake case 後會成為相同鍵的名稱。請將註冊位置集中在一處,設計成在 CLI 與 JSON 中項目都是唯一的。
在測試中處理靜態的註冊狀態
about 開始執行時,顯示用的 $data 會被初始化,但附加資訊的註冊清單 $customDataResolvers 會被保留。這樣每次都能從相同的註冊重新收集資訊,但若在同一個 PHP 行程中重複執行提供者的 boot(),註冊可能會累積。
AboutCommand::flushState() 是清除所有套件的註冊與顯示用資料的方法。請不要為了避免自身區段重複而在正式環境的提供者中呼叫它,否則連其他套件的診斷資訊也會遺失。
若在自有的測試基礎架構中重建應用程式,請決定由誰負責在測試之間初始化狀態。若要初始化,請在啟動目標提供者之前進行,之後再完成所有必要的註冊。也請確認既有的測試基礎架構是否已初始化狀態。
發布前的確認項目
請在以 Orchestra Testbench 測試 Laravel 套件與實際使用的應用程式中確認下列組合。相關頁面
Laravel 套件開發
確認提供者與資源註冊的基礎。
套件設定的合併與快取
確認預設值、使用者覆寫與設定快取之間的關係。