#[Regex]

Stage: VALIDATE (3)

Validates that the payload value matches a given regular expression pattern. If it doesn't match, the filter is skipped.

---

Parameters

Parameter	Type	Required	Default	Description
$pattern	string	✅	—	The regex pattern to match against
$message	string	❌	''	Custom error message when validation fails

---

Usage

Alphabetic Only

use Kettasoft\Filterable\Engines\Foundation\Attributes\Annotations\Regex;

#[Regex('/^[a-zA-Z]+$/')]
protected function status(Payload $payload)
{
    return $this->builder->where('status', $payload->value);
}

Email Validation

#[Regex('/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/')]
protected function email(Payload $payload)
{
    return $this->builder->where('email', $payload->value);
}

Slug Pattern

#[Regex('/^[a-z0-9]+(?:-[a-z0-9]+)*$/')]
protected function slug(Payload $payload)
{
    return $this->builder->where('slug', $payload->value);
}

Numeric Only

#[Regex('/^\d+$/')]
protected function zipCode(Payload $payload)
{
    return $this->builder->where('zip_code', $payload->value);
}

Custom Error Message

#[Regex('/^[A-Z]{2}-\d{4}$/', message: 'Invalid product code format. Expected: XX-1234')]
protected function productCode(Payload $payload)
{
    return $this->builder->where('code', $payload->value);
}

---

Behavior

Scenario	Result
Value matches the pattern	Filter executes normally
Value does not match	Filter is skipped
Value is not a string	Filter is skipped

---

Combining with Transform Attributes

#[Trim]
#[Sanitize('lowercase')]
#[Regex('/^[a-z0-9-]+$/')]
protected function slug(Payload $payload)
{
    // "  My-Slug-123  " → "my-slug-123" → passes regex
    return $this->builder->where('slug', $payload->value);
}