Payload

The Payload class is a lightweight data wrapper used to represent a single filter input.
It normalizes values, provides utility methods, and makes it easier to work with common patterns such as wildcard search, JSON detection, boolean casting, and more.

---

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 field passed from the request.
$operator	string	The operator passed from the request.
$value	mixed	The raw value passed from the request.
$beforeSanitize	mixed	The original value before sanitizing.

---

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
}

---

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

---

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

---

raw(): mixed

Get the original unmodified value.

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

---

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();

---

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();

---

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.