PHP 属性の使用: すべきこととしてはいけないこと-PHPチュートリアル-php.cn

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

属性は、複雑なロジックを必要としない標準構成に最適です。以下に 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() {}
}