README

Description

Tables is the backend engine behind Enso's server-side data tables.

The package reads a JSON table template, validates it, builds the frontend bootstrap payload, turns incoming column and meta state into a normalized request object, applies search and filter pipelines to an Eloquent query, computes row payloads, totals, pagination metadata, and can queue large spreadsheet exports with progress notifications.

It is one of the core Enso infrastructure packages and is designed to be reused by any backend module that exposes list views.

Installation

Install the package:

composer require laravel-enso/tables

Publish the optional assets when you want local overrides:

php artisan vendor:publish --tag=tables-config
php artisan vendor:publish --tag=tables-mail

The package also ships stubs for new table builders, actions, and JSON templates:

php artisan vendor:publish --provider="LaravelEnso\Tables\AppServiceProvider"

When template caching is enabled, clear cached templates on deploy:

php artisan enso:tables:clear

Features

• JSON template DSL for columns, buttons, controls, filters, structure, and styling.
• Dedicated controller traits for init, table data, and Excel export endpoints.
• Search, filter, interval, sort, and pagination normalization through a request/config pipeline.
• Column computors for enums, numbers, dates, datetimes, translations, resources, model methods, and cents.
• Aggregated totals, averages, and custom/raw totals at table level.
• Queue-based spreadsheet exports with chunked fetching, multi-sheet splitting, and mail/database/broadcast notifications.
• Uses laravel-enso/mails for export completion mail layout and preview registration.
• Template caching and optional row-count caching for large datasets.
• Extension points for dynamic templates and batch row actions.
• PHPUnit helpers for datatable endpoint testing.

Usage

1. Implement a table builder

Each table builder implements LaravelEnso\Tables\Contracts\Table:

use Illuminate\Database\Eloquent\Builder;
use LaravelEnso\Tables\Contracts\Table;

class Users implements Table
{
    public function __construct(private TableRequest $request)
    {
    }

    public function query(): Builder
    {
        return User::query()->select(['id', 'email', 'is_active']);
    }

    public function templatePath(): string
    {
        return __DIR__.'/../Templates/users.json';
    }
}

2. Expose the three backend endpoints

The package controller traits are intentionally small:

• Init loads the builder and returns the validated template payload
• Data applies request state and returns rows plus meta
• Excel prepares the queued export flow and emits ExportStarted

use Illuminate\Routing\Controller;
use LaravelEnso\Tables\Traits\Init;
use LaravelEnso\Tables\Traits\Data;
use LaravelEnso\Tables\Traits\Excel;

class InitTable extends Controller
{
    use Init;

    protected string $tableClass = Users::class;
}

class TableData extends Controller
{
    use Data;

    protected string $tableClass = Users::class;
}

class ExportExcel extends Controller
{
    use Excel;

    protected string $tableClass = Users::class;
}

3. Define the JSON template

At minimum, a table template needs:

• routePrefix
• buttons
• columns

Example:

{
    "routePrefix": "administration.users",
    "buttons": ["create", "excel"],
    "controls": ["columns", "length", "reload", "reset", "style"],
    "appends": ["full_name"],
    "filters": [
        {
            "label": "Active",
            "data": "users.is_active",
            "value": null,
            "type": "boolean"
        }
    ],
    "columns": [
        {
            "label": "Email",
            "name": "email",
            "data": "users.email",
            "meta": ["searchable", "sortable"]
        },
        {
            "label": "Balance",
            "name": "balance",
            "data": "users.balance",
            "number": {
                "precision": 2,
                "symbol": "RON ",
                "template": "%s%v"
            },
            "meta": ["filterable", "total"]
        }
    ]
}

Template structure

Top-level attributes accepted by the validator include:

• appends, auth, buttons, controls
• comparisonOperator, countCache, crtNo
• dataRouteSuffix, debounce, dtRowId
• filters, flatten, fullInfoRecordLimit
• lengthMenu, method, model, name
• preview, responsive, searchMode, searchModes
• selectable, strip, templateCache
• defaultSort, defaultSortDirection, totalLabel

Column attributes:

• mandatory: data, label, name
• optional: align, class, dateFormat, enum, meta, number, tooltip, resource

Column meta flags:

• average, boolean, clickable, cents, customTotal
• date, datetime, filterable, icon, method
• notExportable, nullLast, searchable, rawTotal
• rogue, slot, sortable, sort:ASC, sort:DESC
• total, translatable, notVisible

Button structure:

• mandatory: type, icon
• types: global, row, dropdown
• actions: ajax, export, href, router
• optional attributes such as routeSuffix, fullRoute, method, event, postEvent, confirmation, selection, tooltip, and slot

Filters:

• mandatory: label, data, value, type
• optional: slot, multiple, route, translated, params, pivotParams, custom, selectLabel

Defaults also come from config/tables.php:

• cache behavior
• default buttons and controls
• style mapping
• export queue / sheet limits
• search modes and comparison operators

Request and query pipeline

Incoming frontend state is normalized through:

1. ProvidesRequest and FilterAggregator
2. TemplateLoader and Template
3. Config, which merges request meta onto template columns
4. Data\Builders\Data, Meta, and Total

The data pipeline applies:

• global search
• per-column filters
• numeric and date intervals
• default and custom sorting
• pagination limits
• model and array computors
• row actions and row style metadata

Computors and formatting

The package supports two families of computors:

• model computors such as method and resource
• array computors such as enum, number, date, datetime, cents, and translator

That lets you:

• render enum labels from legacy Enso enums or native PHP enums
• format numbers with symbols and precision
• format dates using the configured global or per-column format
• call model methods for derived values
• wrap values in API resources before returning them

Export flow

The export endpoint uses Prepare, then queues either Jobs\Excel or Jobs\EnsoExcel.

During export the package:

• rebuilds the filtered query
• streams rows in chunks through Fetcher
• writes one or more sheets with OpenSpout
• stores the file under storage/app/{export.folder}
• notifies the user with ExportStarted, ExportDone, or ExportError

Large tables can cap the export query chunk by implementing LaravelEnso\Tables\Contracts\CustomExportChunk:

use LaravelEnso\Tables\Contracts\CustomExportChunk;
use LaravelEnso\Tables\Contracts\Table;

class Products implements Table, CustomExportChunk
{
    public function exportChunk(): int
    {
        return 1000;
    }
}

The export service uses the lower value between the automatically computed chunk and the custom chunk, so table builders can reduce memory pressure without increasing the default chunk size for smaller exports.

Caching and extension points

• TemplateLoader caches cacheable template fragments by template path, plus cachePrefix() when the table implements DynamicTemplate
• TableCache can invalidate cached counts on model create/delete
• custom batch jobs can extend LaravelEnso\Tables\Services\Action

Tests

The package ships focused unit coverage for:

• template builders and validators
• search, filter, interval, meta, and export builders
• template cache loading
• TableCache invalidation behavior

Useful local targets:

php artisan test --compact vendor/laravel-enso/tables/tests/units/Services/TemplateLoaderTest.php
php artisan test --compact vendor/laravel-enso/tables/tests/units/Traits/TableCacheTest.php

API

The package exposes three backend endpoints through the controller traits documented in the usage flow:

• Init returns the validated template payload and frontend bootstrap metadata
• Data resolves the request pipeline and returns rows, totals, pagination, and table meta
• Excel starts queued spreadsheet exports and emits the export-start event

At code level, the stable backend contract is LaravelEnso\Tables\Contracts\Table. Custom table builders should implement query() and templatePath(), while downstream modules should treat helper classes such as processors, calculators, computors, and normalizers as internal implementation details unless they are extended deliberately.

Depends On

Required Enso packages:

• laravel-enso/enums ↗
• laravel-enso/filters ↗
• laravel-enso/helpers ↗
• laravel-enso/mails ↗

Companion frontend package:

• @enso-ui/tables ↗

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!