Qubeek.Frame
Поддержка
Ресурсы

Агрегации

Итоговые значения в подвале таблицы

Агрегации позволяют отображать итоговые значения (сумму, среднее, количество и др.) в подвале таблицы. Значения вычисляются на уровне базы данных с учётом текущих фильтров и поиска.

Создание

php artisan frame:summarizer TotalAmount --type=sum

Команда создаст класс в app/Frame/Summarizers/. Параметр --type определяет тип агрегации: sum, avg, count, min, max.

Использование

Чтобы добавить агрегацию к полю, используйте метод summarize():

app/Frame/Resources/OrderResource.php
public function fieldsForIndex(): array
{
    return [
        Text::make('name'),

        Number::make('amount')
            ->summarize(Sum::make()->label('Total')),
    ];
}

Можно добавить несколько агрегаций к одному полю:

Number::make('amount')
    ->summarize([
        Sum::make()->label('Total'),
        Average::make()->label('Average'),
    ]),

Встроенные агрегации

Sum
→ int|float
Сумма значений колонки. Подходит для числовых полей.
Average
→ int|float
Среднее арифметическое значений колонки.
Count
→ int
Количество непустых значений в колонке.
Min
→ mixed
Минимальное значение в колонке.
Max
→ mixed
Максимальное значение в колонке.
Range
→ array{min, max}
Диапазон значений — минимум и максимум одновременно.
Breakdown
→ array
Распределение по значениям колонки. Отображается как горизонтальная полоса с тултипом при наведении.

Breakdown

Агрегация Breakdown визуализирует распределение значений колонки в виде компактной горизонтальной полосы. Подходит для Select, Toggle и других полей с конечным набором вариантов.

app/Frame/Resources/UserResource.php
Select::make('audience')
    ->options(AudienceEnum::class)
    ->summarize(
        Breakdown::make()
            ->label('Audience')
            ->nullLabel('Not set')
            ->colors([
                'Junior' => '#3b82f6',
                'Adult'  => '#10b981',
                '__null' => '#a1a1aa',
            ]),
    ),
colors
array $colors → static
Задаёт цвета сегментов по ключу значения. Используйте __null для записей без значения. Если цвета не указаны — используется палитра по умолчанию.
labels
array $labels → static
Переопределяет названия сегментов. По умолчанию значение переводится через __().
nullLabel
string $label → static
Название для записей с пустым значением. По умолчанию — N/A.

Кастомная агрегация

Для нестандартных вычислений создайте собственный класс:

app/Frame/Summarizers/AverageAge.php
<?php

namespace App\Frame\Summarizers;

use Frame\Laravel\Strategies\Summarizers\Summarizer;
use Illuminate\Contracts\Database\Query\Builder;

class AverageAge extends Summarizer
{
    public function type(): string
    {
        return 'average';
    }

    public function apply(Builder $query, string $column): float|null
    {
        $result = (clone $query)
            ->whereNotNull($column)
            ->selectRaw("AVG(EXTRACT(YEAR FROM AGE({$column}))) as aggregate")
            ->value('aggregate');

        return $result !== null ? round((float) $result, 1) : null;
    }
}
app/Frame/Resources/UserResource.php
DateTime::make('birthday')
    ->format('d.m.Y')
    ->summarize(
        AverageAge::make()->label('Avg age'),
    ),
Метод apply() получает чистый Query Builder без select и orderBy — можно безопасно вызывать агрегатные функции. Используйте clone $query, если добавляете where-условия.

Постраничные итоги

По умолчанию агрегации вычисляются в двух режимах: для текущей страницы («Эта страница») и для всех записей («Все записи»). Если постраничные итоги не нужны — строка «Эта страница» не отображается.

Чтобы исключить агрегацию из постраничных итогов, используйте excludeFromPageSummary():

Number::make('amount')
    ->summarize(
        Sum::make()
            ->label('Total')
            ->excludeFromPageSummary(),
    ),
Если все summarizers поля исключены из постраничных итогов — строка «Эта страница» не появится.

Методы

label
string $label → static
Текстовая метка, отображаемая рядом со значением. Переводится через __() автоматически.
format
string $format → static
Формат отображения значения (зарезервировано для будущего использования).
excludeFromPageSummary
→ static
Исключает агрегацию из строки «Эта страница». Значение будет показано только в строке «Все записи».

Сортировка записей

Ручная сортировка записей с помощью drag and drop

Призмы

Глобальные фильтры и преобразования для ресурсов