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
}

---

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

---

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.