The Invokable Engine supports PHP 8 Attributes as a powerful declarative way to control filter behavior. Instead of writing validation, transformation, and authorization logic inside your filter methods, you declare it with attributes directly on the method signature.

---

How Annotations Work

When the Invokable Engine processes a filter method, it runs all declared attributes through an Attribute Pipeline before executing the method itself. If any attribute throws a SkipExecution exception, the filter method is skipped entirely. If an attribute throws a StrictnessException, the error propagates up.

#[Trim]
#[Sanitize('lowercase')]
#[Required]
#[In('active', 'pending', 'archived')]
protected function status(Payload $payload)
{
    return $this->builder->where('status', $payload->value);
}

---

Execution Stages

Attributes are sorted by stage before execution, regardless of the order you declare them. This ensures a predictable pipeline:

Order	Stage	Value	Purpose	Description
1	CONTROL	1	Gate / Skip	Decide whether the filter should run
2	TRANSFORM	2	Modify Payload	Clean, convert, or map the input value
3	VALIDATE	3	Assert Correctness	Verify the value meets constraints
4	BEHAVIOR	4	Affect Query	Modify query behavior directly

Pipeline Flow

Incoming Payload
    │
    ▼
┌─────────────────┐
│  CONTROL (1)    │  → #[Authorize], #[SkipIf]
│  Should we run? │  → Throws SkipExecution to abort
└────────┬────────┘
         │ ✓ Pass
         ▼
┌─────────────────┐
│  TRANSFORM (2)  │  → #[Trim], #[Sanitize], #[Cast], #[MapValue], #[DefaultValue], #[Explode]
│  Clean the data │  → Modifies payload.value in place
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  VALIDATE (3)   │  → #[Required], #[In], #[Between], #[Regex]
│  Is data valid? │  → Throws SkipExecution or StrictnessException
└────────┬────────┘
         │ ✓ Pass
         ▼
┌─────────────────┐
│  BEHAVIOR (4)   │  → #[Scope]
│  Affect query   │  → May apply scopes or modify builder
└────────┬────────┘
         │
         ▼
   Filter Method Executes

---

Available Annotations

Control Stage

Attribute	Description
#[Authorize]	Require authorization before running the filter
#[SkipIf]	Skip the filter based on a Payload condition

Transform Stage

Attribute	Description
#[Trim]	Remove whitespace from string values
#[Sanitize]	Apply sanitization rules (lowercase, strip_tags, etc.)
#[Cast]	Cast the value to a specific type
#[MapValue]	Map input values to different values
#[DefaultValue]	Set a fallback value when input is empty
#[Explode]	Split a string value into an array

Validate Stage

Attribute	Description
#[Required]	Ensure the value is present and not empty
#[In]	Validate the value is in an allowed set
#[Between]	Validate the value is within a numeric range
#[Regex]	Validate the value matches a regex pattern

Behavior Stage

Attribute	Description
#[Scope]	Auto-apply an Eloquent scope with the payload value

---

Combining Attributes

You can stack multiple attributes on a single method. They always execute in stage order:

#[SkipIf('empty')]                              // Stage 1: Skip if empty
#[Trim]                                          // Stage 2: Remove whitespace
#[Sanitize('lowercase', 'strip_tags')]           // Stage 2: Clean the value
#[Cast('int')]                                   // Stage 2: Cast to integer
#[Required]                                      // Stage 3: Must have a value
#[Between(min: 1, max: 1000)]                    // Stage 3: Range check
protected function price(Payload $payload)
{
    return $this->builder->where('price', $payload->value);
}

---

Creating Custom Annotations

All annotations implement the MethodAttribute interface:

<?php

namespace Kettasoft\Filterable\Engines\Foundation\Attributes\Contracts;

use Kettasoft\Filterable\Engines\Foundation\Attributes\AttributeContext;

interface MethodAttribute
{
    public static function stage(): int;
    public function handle(AttributeContext $context): void;
}

Example: Custom Annotation

<?php

namespace App\Filters\Annotations;

use Attribute;
use Kettasoft\Filterable\Engines\Foundation\Attributes\Contracts\MethodAttribute;
use Kettasoft\Filterable\Engines\Foundation\Attributes\AttributeContext;
use Kettasoft\Filterable\Engines\Foundation\Attributes\Enums\Stage;

#[Attribute(Attribute::TARGET_METHOD)]
class MinLength implements MethodAttribute
{
    public function __construct(public int $length) {}

    public static function stage(): int
    {
        return Stage::VALIDATE->value;
    }

    public function handle(AttributeContext $context): void
    {
        $payload = $context->payload;

        if (is_string($payload->value) && mb_strlen($payload->value) < $this->length) {
            throw new \Kettasoft\Filterable\Engines\Exceptions\SkipExecution(
                "Value must be at least {$this->length} characters."
            );
        }
    }
}

Usage:

#[MinLength(3)]
protected function search(Payload $payload)
{
    return $this->builder->where('title', 'like', $payload->asLike());
}

---

AttributeContext

The AttributeContext object passed to each annotation's handle() method contains:

Property	Type	Description
engine	Engine	The active engine and its Filterable context
payload	Payload	The current filter payload

Use the engine to access the current filter or builder. Transform annotations can update the payload for attributes that run later in the pipeline:

$filter = $context->engine->getContext();
$builder = $filter->getBuilder();

$context->payload->setValue(trim($context->payload->value));

Contributors: kettasoft

Previous pageOverview

Next pageCustom Attributes