Mastering PHP Attributes: Core Principles, Practical Use Cases, and Pitfall Guide

Overview

Most applications start with simple decisions hidden in ordinary code: controllers call services, CLI commands have fixed signatures, models carry query scopes, and webhook events map to handlers. As the codebase grows, developers add rules that are not part of business logic using configuration arrays, naming conventions, PHPDoc tags, or large switch statements. This scattering creates implicit coupling and maintenance overhead.

PHP attributes (available as a language feature since PHP 8) offer an alternative: they let you attach structured, machine‑readable metadata directly to classes, methods, properties, constants, or parameters. Frameworks or applications can read this metadata and turn it into actual behavior.

Attributes vs PHPDoc vs Configuration Files

Attributes are often compared with PHPDoc annotations because both sit close to the code, but they serve different purposes.

PHPDoc : Provides documentation and static‑analysis information. PHP itself does not parse it into runtime objects.

Attributes : Native PHP structures with a class definition, constructor, and strong‑type properties. They are read via reflection, making them suitable for runtime metadata consumption.

Configuration files : Store values that change with environment or deployment (e.g., URLs, timeouts). Attributes should not replace such dynamic configuration.

These three mechanisms complement each other; trying to replace one with another usually leads to a confusing API.

Basic Structure of an Attribute

An attribute is a regular class marked with the built‑in Attribute attribute. Three key details are required:

Declaration : #[Attribute(...)] tells PHP that the class can be used as an attribute.

Target restriction : Constants such as Attribute::TARGET_CLASS limit where the attribute may be applied (class, method, property, parameter, etc.). Multiple targets can be combined with bitwise OR.

Constructor as public API : Define typed parameters with clear names and default values; this becomes the attribute’s public contract.

use Attribute;

#[Attribute(Attribute::TARGET_CLASS)]
final readonly class HandlesWebhook {
    public function __construct(
        public string $event,
        public bool $verifySignature = true,
    ) {}
}

Attribute Lifecycle

Define the attribute class.

Attach the attribute to a target declaration.

At runtime, a consumer uses reflection to obtain a ReflectionAttribute object.

The consumer instantiates the attribute with newInstance(), obtaining a strongly‑typed metadata object.

The consumer builds a registry or framework rule based on the metadata.

The pre‑processed rule is used in the hot path.

The attribute itself never executes logic; only the consumer decides what to do with the metadata.

Why Use Attributes

The core value of attributes is proximity : metadata lives next to the code it describes, eliminating separate mapping tables. For example, a webhook handler can declare the event it handles directly on the class:

#[HandlesWebhook(event: 'invoice.paid')]
final class RecordInvoicePayment implements WebhookHandler {
    public function handle(array $payload): void {
        // record payment, update order status
    }
}

This makes the handler self‑documenting: a developer can instantly see the event and whether signature verification is required. Compared with an array‑based map, attributes provide:

Discoverability – metadata is right next to the declaration.

Consistency – a single attribute class defines the contract for all usages.

Framework‑friendly integration – frameworks can read the attribute and generate registration code.

IDE support – navigation to the attribute class and parameter hints.

Early validation – target restrictions and typed constructors surface errors at compile time.

Practical Implementation

First define a behavior interface (the contract), then the attribute, and finally the concrete handler:

interface WebhookHandler {
    public function handle(array $payload): void;
}

#[Attribute(Attribute::TARGET_CLASS)]
final readonly class HandlesWebhook {
    public function __construct(
        public string $event,
        public bool $verifySignature = true,
    ) {}
}

#[HandlesWebhook(event: 'invoice.paid')]
final class RecordInvoicePayment implements WebhookHandler {
    public function handle(array $payload): void {
        // save payment record, update order status
    }
}

The consumer (e.g., a registry) scans a known list of handler classes, reads the attribute, validates uniqueness, and builds a simple lookup table:

final class WebhookHandlerRegistry {
    private array $handlers = [];

    public function __construct(array $handlerClasses) {
        foreach ($handlerClasses as $handlerClass) {
            $attributes = (new ReflectionClass($handlerClass))
                ->getAttributes(HandlesWebhook::class);
            if ($attributes === []) continue;
            /** @var HandlesWebhook $metadata */
            $metadata = $attributes[0]->newInstance();
            if (array_key_exists($metadata->event, $this->handlers)) {
                throw new LogicException("Webhook event [{$metadata->event}] has multiple handlers");
            }
            $this->handlers[$metadata->event] = $handlerClass;
        }
    }

    public function handlerFor(string $event): string {
        return $this->handlers[$event] ?? throw new LogicException("No handler for webhook event [$event]");
    }
}

At request time the dispatcher simply looks up the class name and invokes the handler, avoiding reflection in the hot path.

Target Restrictions and Repeatable Attributes

Target restrictions are part of the attribute design. For example, a header‑extraction attribute belongs on a parameter, not on a class:

#[Attribute(Attribute::TARGET_PARAMETER)]
final readonly class FromHeader {
    public function __construct(public string $name) {}
}

By default an attribute can appear only once on a declaration. For list‑like metadata (e.g., middleware), mark the attribute as repeatable:

#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
final readonly class UsesMiddleware {
    public function __construct(public string $middleware) {}
}

#[UsesMiddleware(Authenticate::class)]
#[UsesMiddleware(VerifyWebhookSignature::class)]
final class PartnerWebhookController {}

Consumers must still decide how to order or combine the values; the attribute only provides the data.

Laravel as a Consumer

Laravel 13 uses attributes for several native features:

Eloquent local scopes: #[Scope] marks a protected method as a query scope.

Contextual dependency injection: #[Config('reports.timezone')] on a constructor parameter tells the container to resolve the configuration value.

use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;

final class Post extends Model {
    #[Scope]
    protected function published(Builder $query): void {
        $query->whereNotNull('published_at');
    }
}

use Illuminate\Container\Attributes\Config;

final readonly class ReportExporter {
    public function __construct(
        #[Config('reports.timezone')] private string $timezone,
    ) {}
}

Laravel reads these attributes at boot time and generates the corresponding runtime behavior.

Attribute Parameters Should Be Pure Data

Parameters should be static, stable values (scalars, arrays, constants, class names). They must not contain runtime function calls, environment variables, or tenant‑specific data. A good attribute API looks like:

#[Attribute(Attribute::TARGET_METHOD)]
final readonly class Cacheable {
    public function __construct(public string $key, public int $seconds) {}
}

#[Cacheable(key: 'catalog.featured', seconds: 300)]
public function featuredProducts(): array {
    // ...
}

If an attribute grows too complex (e.g., many optional keys), it signals that the behavior should be extracted into a dedicated service or configuration object.

Reflection, Performance, and Caching

Reflection is powerful but not free. Creating ReflectionClass, scanning attributes, and instantiating attribute objects incurs overhead. The recommended pattern is to perform reflection once during application boot or a pre‑warm step, cache the resulting map, and use plain arrays in the hot path.

Reflection should be placed at the boundary; the hot path should use ordinary data.

Testing Attribute‑Based Designs

Tests should verify the behavior produced by attribute consumers, not merely the existence of the attribute. For the registry example:

it('resolves the correct handler for a payment event', function (): void {
    $registry = new WebhookHandlerRegistry([
        RecordInvoicePayment::class,
    ]);
    expect($registry->handlerFor('invoice.paid'))
        ->toBe(RecordInvoicePayment::class);
});

it('rejects duplicate event handlers', function (): void {
    new WebhookHandlerRegistry([
        RecordInvoicePayment::class,
        ProcessInvoicePaymentAgain::class,
    ]);
})->throws(LogicException::class);

These tests remain valid even if the implementation later switches from reflection to a generated metadata file.

When Attributes Are a Good Fit

When metadata naturally belongs to a class, method, property, or parameter.

When a clear consumer (framework, package, or service) reads the metadata.

For cross‑cutting concerns such as routing, serialization rules, permission descriptors, cache hints, or dependency resolution.

When the attribute parameters are small, static values.

When validation can happen at startup or during a cache‑pre‑warm phase.

When Attributes Are Not Appropriate

Attributes should not be used to hide required business inputs, store environment‑specific values, replace polymorphism, or obscure the application flow. Over‑stacking attributes (e.g., authorisation, retry, transaction, cache) can make it hard to understand which component performs which action. Attributes also do not provide security; a consumer must still enforce checks.

Simple Decision Checklist

Does the metadata naturally belong to the declaration?

Is it stable source‑level data rather than runtime configuration?

Can I point to the exact consumer code?

Would an interface, constructor parameter, value object, or config make the dependency clearer?

Can the consumer validate it during boot or cache pre‑warm?

Will the hot path use a pre‑processed map instead of repeated reflection?

Can a developer follow the attribute class to the consumer and understand the full behavior?