Payload

About 967 wordsAbout 3 min

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.
`$rawValue`	`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->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.

Annotations

Payload