The Payload class represents a single filter throughout its lifecycle. It contains the original request value, the sanitized or transformed value, and the resolved field and operator used by the filtering engine.

It also provides utility methods for common patterns such as wildcard search, JSON detection, boolean casting, and more. Successfully applied filters are available as Payload snapshots through Filterable::applied().

---

Overview

When you define filters inside a Filterable class, the filter method receives a Payload object instead of a raw value.

class PostFilter extends Filterable
{
    protected $filters = ['title'];

    protected function title(Payload $payload)
    {
        return $this->builder->where('title', 'like', $payload->like());
    }
}

---

Properties

Property	Type	Description
$field	string	The resolved field used by the engine.
$operator	string	The resolved database operator.
$value	mixed	The sanitized or transformed filter value.
$rawValue	mixed	The original value before sanitization.

---

Public Methods

__toString(): string

Returns the value as string.

(string) $payload; // equivalent to $payload->value

---

setValue(mixed $value): Payload

Set a new value for the payload and return the updated instance.

$payload = $payload->setValue('new value');

---

length(): int

Get the length of the value.
Dealing with array or string

if ($payload->length() > 10) {
    // skip filter
}

---

isEmpty(): bool

Check if the value is empty (null, "", or whitespace).

if ($payload->isEmpty()) {
    // skip filter
}

---

isNotEmpty(): bool

Check if the value is not empty (filterable, ['one', 'tow'], or any data).

if ($payload->isNotEmpty()) {
    // appliy filter
}

---

isNull(): bool

Check if the value is null.

if ($payload->isNull()) {
    // skip filter
}

---

in(...$haystack): bool

Check if the payload value exists inside the given list. Supports both a flat list of values or a single array.

if ($payload->in('active', 'pending', 'archived')) {
    // apply filter
}

---

notIn(...$haystack): bool

Check if the payload value does not exist in the given list.

if ($payload->notIn('banned', 'deleted')) {
    // only include safe records
}

---

is(...$checks): bool

Run multiple is* checks and return true only if all of them pass. Supports negation using ! at the start of the check.

if ($payload->is('!empty', 'string')) {
    // value is not empty AND is a string
}

if ($payload->is('!null', 'numeric')) {
    // value is NOT null AND is numeric
}

You can also reference existing is* methods implicitly:

'notEmpty' → isNotEmpty()'json' → isJson()'!empty' → negated isEmpty()

---

isAny(...$checks): bool

Run multiple is* checks and return true if any one of them passes. Also supports negation with !.

if ($payload->isAny('json', 'array')) {
    // value is json OR array
}

if ($payload->isAny('!empty', 'true')) {
    // value is not empty OR equals true
}

Same rules apply for automatic method mapping and negation.

---

isEmptyString(): bool

Check if the payload is an empty string.

if ($payload->isEmptyString()) {
    // skip filter
}

---

isNotNullOrEmpty(): bool

Check if the payload is neither null nor empty.

if ($payload->isNotNullOrEmpty()) {
    // apply filter
}

---

isBoolean(): bool

Check if the value can be interpreted as boolean.
Supports "true", "false", "1", "0", "yes", "no".

if ($payload->isBoolean()) {
    $this->builder->where('is_active', $payload->asBoolean());
}

---

isJson(): bool

Check if the payload is a valid JSON string.

if ($payload->isJson()) {
    $data = json_decode($payload->value, true);
}

---

asBoolean(): bool|null

Convert value to boolean.
Supports "true", "false", "1", "0", "yes", "no".

$payload->asBoolean(); // true or false

---

asSlug(string $operator = "-"): string

Convert the payload value to a slug.

$payload->asSlug(); // "my-sample-value"
$payload->asSlug("_"); // "my_sample_value"

---

asLike(string $side = "both"): string

Wrap the value with % for SQL LIKE queries.

• both → %value%
• left → %value
• right → value%

$this->builder->where('title', 'like', $payload->asLike());
// WHERE title LIKE "%keyword%"

---

asInt(): int

Cast value to integer.

$payload->asInt(); // 42

---

explode(string $delimiter = ","): array

Split the value into an array using the given delimiter.

$payload->explode(); // ['one', 'two', 'three']

---

split(string $delimiter = ","): array

Alias for explode() method.

$payload->split(); // ['one', 'two', 'three']

---

raw(): mixed

Get the original unmodified value.

$payload->raw();  // equivalent to $payload->rawValue

---

isNumeric(): bool

Check if the value is numeric.

if ($payload->isNumeric()) {
    return $this->builder->where('id', $this->value);
}

---

isString(): bool

Check if the value is string.

if ($payload->isString()) {
    return $this->builder->where('name', $this->value);
}

---

isArray(): bool

Check if the value is array.

if ($payload->isArray()) {
    return $this->builder->where('name', 'in', $this->value);
}

---

isTrue(): bool

Check if the value is true.
Supports "true", "1", "yes".

$payload->isTrue(); // true

---

isFalse(): bool

Check if the value is false.
Supports "false", "0", "no", "".

$payload->isFalse();

---

regex(string $pattern): bool

Check if the value matches the given regular expression pattern.

if ($payload->regex('/^[a-z0-9]+$/i')) {
    // value contains only alphanumeric characters
}

---

isDate(): bool

Check if the value is a valid date string.

if ($payload->isDate()) {
    $this->builder->whereDate('created_at', $payload->value);
}

---

isTimestamp(): bool

Check if the value is a valid timestamp.

if ($payload->isTimestamp()) {
    // value is a valid timestamp
}

---

asArray(): array

If the value is a valid JSON string representing an array/object, it will be decoded into an array. If the value is already an array, it will be returned directly. Otherwise returns null.

$payload->asArray();

---

asCarbon(): Carbon|null

Get the payload value as a Carbon instance.

$payload->asCarbon();

---

toArray(): array

Get the instance as an array

$payload->toArray();

/*
  [
    "field" => "status",
    "operator" => "=",
    "value" => "filterable"
  ]
*/

---

toJson(): string

Get the instance as an json string

$payload->toJson();

/*
  [
    "field" => "status",
    "operator" => "=",
    "value" => "filterable"
  ]
*/

Example Usage

protected function status(Payload $payload)
{
    return $this->builder->where('is_active', $payload->asBoolean());
}

protected function category(Payload $payload)
{
    return $this->builder->where('category_id', $payload->asInt());
}

protected function meta(Payload $payload)
{
    if ($payload->isJson()) {
        return $this->builder->whereJsonContains('meta', $payload->raw());
    }
}

---

Summary

• Payload standardizes how filter values are processed.
• It provides helper methods (asLike, asBoolean, isJson, etc.).
• This reduces repetitive code inside filter classes.

Contributors: Abdalrhman Emad Saad, kettasoft

Previous pageFilterable Facade

Next pageSorter