Laravel: PHP8 Attributes 深入淺出

隨著 PHP 8 推出新的特性「Attributes」，Laravel 開發者可以使用更直覺的方式來描述類別、方法、甚至是屬性的 Metadata，讓程式更容易被理解與維護。

但 Attributes 到底是什麼？和我們過去習慣使用的註解（DocBlock）相比，它又有哪些關鍵的差異呢？事實上，過去常用的註解僅僅作為輔助的說明文字存在，無法真正影響程式的運行邏輯；而 Attributes 則是 PHP 原生支援的結構化元資料，能夠直接被程式於執行時解析並應用於業務邏輯之中，帶來更具體且功能性的效益。

那麼該如何在 Laravel 中實際運用 Attributes，才能真正發揮它的價值？在本篇文章中，我們將以淺顯易懂的基礎概念出發，逐步探索並實作 Laravel 專案中能透過 Attributes 受益的具體場景。

什麼是 Attributes ?

PHP 8 中引入的「Attributes」是一種語言層級的結構化元資料（metadata），用來標註程式碼的類別、方法、屬性、函式或參數等元素，使得這些標註能夠在執行時透過 Reflection API 讀取並加以運用。它的出現，解決了以往只能靠 DocBlock 註解、並由第三方工具解析的限制，將元資料與程式碼的關聯性提升一個層級。

Attributes 支援的標註類型（Targets）

下圖這些「標註類型（Targets）」是用來告訴 PHP 編譯器你的 Attribute 可以套用在哪些語法元素上。也就是說，當你定義一個自訂 Attribute 類別時，你可以限制它只能用在「類別」或「方法」上，避免誤用(程式會拋出錯誤)。

TIP:若不想指定，Attribute::TARGET_ALL預設即可標註在所有可用的目標上。

Attributes（屬性） vs DocBlock（註解）

在 PHP 8 推出 Attributes 之前，我們通常開發會使用 DocBlock（也就是 /** ... */ 的多行註解）來為類別、方法或屬性加上說明。然而，DocBlock 的功能僅止於靜態說明文字，實際上並不會影響程式的執行行為，而 PHP 8 的 Attributes 則是語言層級支援的結構化標註。

Attributes × Enum 使用範例

在實際專案中，我們常會遇到某些「狀態值」需要同時兼顧：

• 資料庫儲存的數值（例如：0, 1, 2…）
• 系統內部判斷的邏輯意義（如：待付款、已付款、已出貨）
• 前端畫面需要顯示的中文文字（如：「尚未付款」）

過去，我們可能會在不同地方 hard-code 這些文字與狀態值，造成維護混亂，也容易有不一致的風險。現在可以透過 Enum + Attribute 的方式將這些資訊集中定義。

建立 Attribute 類別：Display.php

放在 app/Attributes/Display.php，我們讓這個 Attribute 能接收彈性參數，例如 name、color、icon 等等（視前端 UI 需要而定）：

這裡用 Attribute::TARGET_CLASS_CONSTANT 限定只能標註在 enum case 上，表示這是用來描述「常數值」的。

定義 Enum 類別：OrderStatus.php

放在 app/Enums/OrderStatus.php，我們可以這樣定義各種狀態：

這樣的做法，不僅讓狀態值與名稱一目了然，也讓前端畫面所需的標籤（如中文文字、顏色）統一由後端提供，避免中英文錯配或狀態遺漏的問題，且提高前後端一致性，降低維護成本。

預期的輸出結果：

這樣就可以提供這組資料給 API 使用，統一管理狀態與顯示，避免 hard-code。

Conclusion

可以想像 Attributes 就像為每個狀態值貼上一張清楚的標籤，不只自己一看就懂，前端工程師也能直接拿來使用，避免彼此資訊不同步的困擾。這種清晰且一致的管理方式，能讓你的 Laravel 專案更好維護，徹底避免硬編碼的混亂與風險。