Add Invokable annotations (Trim, Sanitize, MapValue, Between, Regex, Scope, SkipIf) and more

[kettasoft]

Summary

Adds a set of method-level PHP Attributes (Annotations) for the Invokable engine to simplify common transformations, validations, and query behaviors inside filter methods.

This PR introduces multiple reusable attributes that reduce boilerplate and make filter logic more declarative and maintainable.

The update also includes documentation for each attribute, an Invokable engine overview, and a test suite covering the new functionality.

---

Why

Filter methods currently require repetitive code for common operations such as:

• trimming or sanitizing input
• casting values
• validating ranges or formats
• mapping values
• conditionally skipping execution
• applying query scopes

These concerns are often cross-cutting, and embedding them inside every filter method increases duplication and reduces readability.

This PR introduces a set of declarative attributes that separate responsibilities into stages:

CONTROL → TRANSFORM → VALIDATE → BEHAVIOR

Benefits:

• Less boilerplate inside filters
• Clear separation of concerns
• More readable filter methods
• Easier extensibility for future annotations
• Consistent validation and transformation behavior

---

What changed

1. New Attributes

The following PHP Attributes were added and integrated into the Invokable attributes pipeline.

Control Stage

Attributes that control whether the filter method executes.

• Authorize — ensures the filter method is authorized before execution
• Required — ensures the payload value is present
• SkipIf — conditionally skips the filter method using Payload is* helpers (supports negation and repeatable usage)

---

Transform Stage

Attributes that modify or normalize incoming values.

• Trim — trims whitespace (supports left, right, or both, with optional custom characters)

• Sanitize — applies sanitization rules such as:

  • lowercase
  • uppercase
  • ucfirst
  • strip_tags
  • slug
  • trim

• Cast — casts the value to a specific type (int, float, bool, string, etc.)

• Explode — splits a string into an array using a delimiter

• DefaultValue — assigns a default value when the payload value is missing or empty

• MapValue — maps incoming values to different values (supports strict mode)

---

Validate Stage

Attributes responsible for validating incoming values.

• Between — numeric range validation (min / max)
• Regex — validates the value against a regular expression
• In — ensures the value exists within a defined set of allowed values

---

Behavior Stage

Attributes that affect the query or business behavior.

• Scope — applies an Eloquent scope to the query builder

---

2. Supporting Improvements

Small supporting changes were included to improve:

• attribute pipeline wiring
• code clarity and structure
• internal helpers
• documentation consistency

All changes were kept non-breaking.

---

Example Usage

#[Trim]
#[Sanitize('lowercase', 'strip_tags')]
#[MapValue(['active' => 1, 'inactive' => 0], strict: true)]
#[Between(0, 10)]
public function status(Payload $payload)
{
    $this->builder->where('status', '=', $payload->value);
}

Another example:

#[Required]
#[Cast('int')]
#[Between(1, 100)]
public function age(Payload $payload)
{
    $this->builder->where('age', '>=', $payload->value);
}

---

Migration Notes

• No breaking changes expected.
• Attributes are opt-in and only apply to methods where they are declared.

Execution order follows the attribute pipeline stages:

CONTROL → TRANSFORM → VALIDATE → BEHAVIOR