PHP 属性の使用: すべきこととしてはいけないこと

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. 標準的な反復構成に属性を使用する (実行)

属性は、複雑なロジックを必要としない標準構成に最適です。以下に 3 つの良い例を示します:

• ルートの定義: 属性を使用して、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() {}
  }

• レート制限: スロットル属性を使用して、ユーザーごとのリクエスト数を制限できます。

  #[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')]

• 単一属性での構成の連鎖: 1 つの属性で複数の構成動作を連鎖させないでください。

  #[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() {}
  }

結論

属性は、特に Laravel などの PHP フレームワークで、反復的な構成を処理するエレガントな方法を提供します。

ただし、これらは単純なメタデータとして最適に機能するため、複雑な構成やロジックで過負荷にならないようにすることが重要です。

ベスト プラクティスに従い、属性を軽量で再利用可能なアノテーションとして使用することで、コードベースに不必要な複雑さを加えることなく、その可能性を最大限に活用できます。

---

スポンサー

GitHub スポンサーでスポンサーになって、私のオープンソース活動をサポートしてください!皆様のスポンサーシップにより、開発者コミュニティに役立つ便利な Laravel パッケージ、ツール、教育コンテンツを作成し続けることができます。オープンソースの改善にご協力いただきありがとうございます!

---

Unsplash の Milad Fakurian による写真

以上がPHP 属性の使用: すべきこととしてはいけないことの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。