使用 PHP 屬性：注意事項-php教程-PHP中文網

Working with PHP Attributes: Do’s & Don’ts

PHP 中的屬性可讓您直接使用元資料註解程式碼元素，從而簡化程式碼配置，從而可能減少 Laravel 等框架中的樣板檔案。然而，與任何功能一樣，屬性可能會被過度使用或誤用，導致控制器混亂和程式碼難以維護。

在這篇文章中，我們將探索以增強程式碼清晰度的方式使用屬性的最佳實踐。我還將提供一個“該做和不該做”的表格，其中包含每次比較的範例，突出顯示屬性運作良好的場景以及可能不工作的場景。

1. 理解PHP中的屬性

這是定義和使用屬性來提供一些上下文的快速範例：

#[Attribute]
class MyCustomAttribute {
    public function __construct(public string $description) {}
}

#[MyCustomAttribute("This is a test class")]
class MyClass {
    #[MyCustomAttribute("This is a test method")]
    public function myMethod() {}
}

登入後複製

2. 注意事項：快速概述

下表總結了最佳實踐和常見陷阱：

Do’s	Don’ts
Use attributes for standard, repetitive configurations (e.g., HTTP methods, caching).	Don’t overload attributes with complex configurations or conditional logic.
Leverage attributes for metadata rather than core application logic.	Avoid embedding business logic or intricate rules within attributes.
Apply attributes for simple, reusable annotations (e.g., #[Throttle], #[Cache]).	Don’t try to replace Laravel’s route files entirely with attribute-based routing.
Cache attribute-based reflections when possible to improve performance.	Don’t rely solely on attributes for configurations that need flexibility or change often.
Document your attributes, so team members understand their purpose and usage.	Avoid using attributes for configurations where traditional methods work better (e.g., middleware settings).

3. 實例詳細比較

讓我們透過具體範例深入了解每個比較。

1. 使用屬性進行標準、重複的配置（執行）

屬性非常適合不需要複雜邏輯的標準配置。以下是三個很好的例子：

定義路由：使用屬性透過 HTTP 方法和路徑定義簡單的路由。

#[Attribute]
class MyCustomAttribute {
    public function __construct(public string $description) {}
}

#[MyCustomAttribute("This is a test class")]
class MyClass {
    #[MyCustomAttribute("This is a test method")]
    public function myMethod() {}
}

登入後複製

快取控制：使用屬性指定方法的快取持續時間。

  #[Attribute]
  class Route {
      public function __construct(public string $method, public string $path) {}
  }

  class ProductController {
      #[Route('GET', '/products')]
      public function index() {}
  }

登入後複製

速率限制：Throttle 屬性可用來限制每個使用者的請求數量。

  #[Attribute]
  class Cache {
      public function __construct(public int $duration) {}
  }

  class ProductController {
      #[Cache(3600)]
      public function show($id) {}
  }

登入後複製

不要使用複雜的配置來重載屬性（不要）

避免對需要多個參數或條件的配置使用屬性。以下是不該做的事：

使用多個配置重載：避免在屬性中新增多個參數。

  #[Attribute]
  class Throttle {
      public function __construct(public int $maxAttempts) {}
  }

  class UserController {
      #[Throttle(5)]
      public function store() {}
  }

登入後複製

屬性中的條件邏輯：避免屬性內的條件設定。

  #[Attribute]
  class Route {
      public function __construct(
          public string $method,
          public string $path,
          public ?string $middleware = null,
          public ?string $prefix = null
      ) {}
  }

  #[Route('POST', '/users', middleware: 'auth', prefix: '/admin')]

登入後複製

單一屬性中的連結配置：避免在一個屬性中連結多個配置行為。

  #[Attribute]
  class Condition {
      public function __construct(public string $condition) {}
  }

  class Controller {
      #[Condition("isAdmin() ? 'AdminRoute' : 'UserRoute'")]
      public function index() {}
  }

登入後複製

2. 利用元資料的屬性（執行）

使用屬性作為標記或元數據，而不是在其中嵌入應用程式邏輯。方法如下：

驗證註解：使用屬性將欄位標記為必填。

  #[Attribute]
  class Combined {
      public function __construct(
          public int $cacheDuration,
          public int $rateLimit
      ) {}
  }

  #[Combined(cacheDuration: 300, rateLimit: 5)]

登入後複製

指定 HTTP 方法作為元資料：使用屬性來標記 HTTP 方法類型。

  #[Attribute]
  class Required {}

  class User {
      #[Required]
      public string $name;
  }

登入後複製

指示存取等級：使用屬性來指示存取等級要求。

  #[Attribute]
  class Get {}

  class BlogController {
      #[Get]
      public function list() {}
  }

登入後複製

不要在屬性中嵌入業務邏輯（不要）

避免使用屬性直接確定應用程式行為。以下是不該做的事：

避免在屬性中使用直接條件：不要在屬性中放置條件檢查。

  #[Attribute]
  class RequiresAdmin {}

  class SettingsController {
      #[RequiresAdmin]
      public function update() {}
  }

登入後複製

避免在屬性中呼叫方法：不要在屬性中放置函數呼叫或業務邏輯。

  #[Attribute]
  class AccessControl {
      public function __construct(public string $role) {}
  }

  #[AccessControl(role: isAdmin() ? 'admin' : 'user')]

登入後複製

避免在屬性中使用計算值：屬性應該是靜態元數據，而不是計算值。

  #[Attribute]
  class ConditionalCache {
      public function __construct(public int $duration) {}
  }

  #[ConditionalCache(duration: userHasPremium() ? 3600 : 300)]

登入後複製

3. 將屬性應用於簡單、可重複使用的註解（執行）

屬性非常適合可重複使用的輕量級註解。以下是一些可重複使用的註解範例：

Simple Throttle：用於限制請求速率的簡單節流屬性。

#[Attribute]
class MyCustomAttribute {
    public function __construct(public string $description) {}
}

#[MyCustomAttribute("This is a test class")]
class MyClass {
    #[MyCustomAttribute("This is a test method")]
    public function myMethod() {}
}

登入後複製

快取控制：使用單一持續時間參數新增快取控制屬性。

  #[Attribute]
  class Route {
      public function __construct(public string $method, public string $path) {}
  }

  class ProductController {
      #[Route('GET', '/products')]
      public function index() {}
  }

登入後複製

棄用警告：將方法標記為棄用以提醒開發人員。

  #[Attribute]
  class Cache {
      public function __construct(public int $duration) {}
  }

  class ProductController {
      #[Cache(3600)]
      public function show($id) {}
  }

登入後複製

不要過度使用其他格式更容易的配置屬性（不要）

某些配置在屬性之外可以得到更好的管理。以下是不該做的事：

中間件配置：避免直接在屬性中配置中間件。

  #[Attribute]
  class Throttle {
      public function __construct(public int $maxAttempts) {}
  }

  class UserController {
      #[Throttle(5)]
      public function store() {}
  }

登入後複製

授權規則：複雜的授權配置最好放在策略檔案中。

  #[Attribute]
  class Route {
      public function __construct(
          public string $method,
          public string $path,
          public ?string $middleware = null,
          public ?string $prefix = null
      ) {}
  }

  #[Route('POST', '/users', middleware: 'auth', prefix: '/admin')]

登入後複製

複雜的驗證規則：將驗證邏輯排除在屬性之外。

  #[Attribute]
  class Condition {
      public function __construct(public string $condition) {}
  }

  class Controller {
      #[Condition("isAdmin() ? 'AdminRoute' : 'UserRoute'")]
      public function index() {}
  }

登入後複製