使用 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. 使用属性进行标准、重复的配置（执行）

属性非常适合不需要复杂逻辑的标准配置。以下是三个很好的例子：

• 定义路由：使用属性通过 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() {}
  }

结论

属性提供了一种优雅的方式来处理重复配置，特别是在 Laravel 这样的 PHP 框架中。

但是，它们作为简单的元数据效果最好，并且必须避免使用复杂的配置或逻辑使它们过载。

通过遵循最佳实践并将属性用作轻量级、可重用的注释，您可以充分利用它们的潜力，而不会给代码库增加不必要的复杂性。

---

赞助

通过在 GitHub 赞助商上赞助我来支持我的开源工作！您的赞助帮助我不断创建有用的 Laravel 软件包、工具和教育内容，让开发者社区受益。感谢您帮助让开源变得更好！

---

照片由 Milad Fakurian 在 Unsplash 上拍摄

以上是使用 PHP 属性：注意事项的详细内容。更多信息请关注PHP中文网其他相关文章！