README

SettleUp Dashboards

Caution

This package is currently in alpha and is not yet ready for production use. APIs and database schemas may change without notice between releases.

A Laravel package that provides a complete API for managing user-configurable dashboards composed of Visualization widgets. The package is API-driven with no frontend opinions, giving you full control over presentation while handling dashboard CRUD, widget management, revision history, and sharing out of the box.

Requirements

• PHP 8.4
• Laravel 12.x or 13.x
• settleup/visualizations ^1.0

Installation

Install the package via Composer:

composer require settleup/dashboards

Publish and run the migrations:

php artisan vendor:publish --tag="dashboards-migrations"
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --tag="dashboards-config"

The published config file contains:

return [
    'user_model' => config('auth.providers.users.model', 'App\\Models\\User'),
];

The user_model key controls which Eloquent model is used for user relationships (dashboard ownership, sharing, revision tracking). It defaults to your application's configured auth user model.

Sections

Every dashboard and widget belongs to a section — a logical grouping that scopes which widgets are available and which dashboards are accessible. Sections are defined by implementing the DefinesDashboardSection interface:

use SettleUp\Dashboards\Contracts\DefinesDashboardSection;

enum DashboardSection: string implements DefinesDashboardSection
{
    case Finance = 'finance';
    case Support = 'support';

    public function getSectionKey(): string
    {
        return $this->value;
    }
}

Registering Routes

The package provides a Route::dashboardSection() macro that mounts all dashboard API routes for a given section. Call it once per section inside your own route group:

use Illuminate\Routing\Middleware\SubstituteBindings;
use Illuminate\Support\Facades\Route;

Route::middleware(['auth:sanctum', SubstituteBindings::class])
    ->prefix('api')
    ->group(function () {
        Route::dashboardSection(DashboardSection::Finance);
        Route::dashboardSection(DashboardSection::Support);
    });

Each call prefixes all routes with the section key, so the two calls above produce routes under /api/finance/ and /api/support/ respectively.

This registers the following routes per section (shown here for a section key of {section}):

Registering Widgets

Widgets are DataGrid, Chart, or Metric classes that implement the ShouldRegisterAsWidget interface. This interface opts a visualization class into the dashboard widget catalog.

Implementing the Interface

Add ShouldRegisterAsWidget to any DataGrid, Chart, or Metric class and implement getSection() to declare which section the widget belongs to:

use SettleUp\Dashboards\Contracts\DefinesDashboardSection;
use SettleUp\Dashboards\Contracts\ShouldRegisterAsWidget;
use SettleUp\Visualizations\DataGrids\Abstracts\DataGrid;

class UsersGrid extends DataGrid implements ShouldRegisterAsWidget
{
    public function getWidgetName(): string
    {
        return 'Users';
    }

    public function getWidgetDescription(): string
    {
        return 'A grid displaying all users in the system.';
    }

    public function getSection(): DefinesDashboardSection
    {
        return DashboardSection::Finance;
    }

    // ... getColumns(), getQuery(), etc.
}

use SettleUp\Dashboards\Contracts\DefinesDashboardSection;
use SettleUp\Dashboards\Contracts\ShouldRegisterAsWidget;
use SettleUp\Visualizations\Charts\Abstracts\Chart;

class RevenueChart extends Chart implements ShouldRegisterAsWidget
{
    public function getWidgetName(): string
    {
        return 'Monthly Revenue';
    }

    public function getWidgetDescription(): string
    {
        return 'A chart showing monthly revenue trends.';
    }

    public function getSection(): DefinesDashboardSection
    {
        return DashboardSection::Finance;
    }

    // ... getLabel(), getDatasets(), getQuery(), etc.
}

use SettleUp\Dashboards\Contracts\DefinesDashboardSection;
use SettleUp\Dashboards\Contracts\ShouldRegisterAsWidget;
use SettleUp\Visualizations\Metrics\Abstracts\Metric;

class ActiveUsersMetric extends Metric implements ShouldRegisterAsWidget
{
    public function getWidgetName(): string
    {
        return 'Active Users';
    }

    public function getWidgetDescription(): string
    {
        return 'Count of users active in the last 30 days.';
    }

    public function getSection(): DefinesDashboardSection
    {
        return DashboardSection::Finance;
    }

    // ... getValue(), etc.
}

Each widget belongs to exactly one section. The widget API only returns widgets that match the section of the route it is called from.

Running the Registration Command

Register all widget classes discovered under app_path():

php artisan widget:register

Or target a specific directory:

php artisan widget:register --path=app/Finance

Or register a specific class by name:

php artisan widget:register "App\\Grids\\UsersGrid"

The command uses updateOrCreate on the widget key, so it is safe to run repeatedly. You may want to call it as part of your deployment process to keep the widget catalog in sync.

API Usage

Dashboards

List Dashboards

GET /api/{section}/dashboards

Returns all dashboards owned by or shared with the authenticated user. Each entry includes id, name, and user_id.

Create a Dashboard

POST /api/{section}/dashboards

{
    "name": "My Dashboard"
}

Show a Dashboard

GET /api/{section}/dashboards/{id}

Returns the full dashboard with its widgets, owner, shared users, and permission flags:

{
    "dashboard": {
        "id": 1,
        "name": "My Dashboard",
        "user_id": 1,
        "user": { "..." },
        "shared_with": [],
        "dashboard_widgets": [
            {
                "id": 1,
                "widget_id": 3,
                "name": "Custom Widget Name",
                "column_span": 6,
                "sort_order": 0,
                "filter_sets": null,
                "sorts": null,
                "visibility": null,
                "widget": { "..." }
            }
        ]
    },
    "can": {
        "update": true,
        "delete": true,
        "share": true
    }
}

The can object tells the frontend which actions to display for the current user.

Update a Dashboard

PATCH /api/{section}/dashboards/{id}

You can update the name, the widgets, or both. A revision of the current state is automatically created before any changes are applied.

{
    "name": "Updated Name",
    "widgets": [
        {
            "widget_id": 3,
            "name": "Custom Name",
            "column_span": 6,
            "filter_sets": null,
            "sorts": null,
            "visibility": [
                { "field": "email", "is_hidden": true }
            ]
        },
        {
            "widget_id": 5,
            "name": null,
            "column_span": 12
        }
    ]
}

The order of the widgets array determines the sort_order on the dashboard. Each widget supports:

Clone a Dashboard

POST /api/{section}/dashboards/{id}/clone

Creates a copy of the dashboard (named "{original} (Copy)") owned by the authenticated user. Both owners and shared users can clone.

Delete a Dashboard

DELETE /api/{section}/dashboards/{id}

Owner only. Returns 204 No Content.

Revisions

Every update and revision restore automatically creates a snapshot of the current dashboard state before making changes. This ensures you always have an undo path. The package keeps the 50 most recent revisions per dashboard.

List Revisions

GET /api/{section}/dashboards/{id}/revisions

Returns up to 50 revisions, ordered newest first, including the user who made each change.

Restore a Revision

POST /api/{section}/dashboards/{id}/revisions/{revision_id}/restore

Restores the dashboard to the state captured in the given revision. A new revision of the current state is created first, so the restore itself can be undone.

Sharing

Dashboard owners can share their dashboards with other users, granting them read-only access (view and clone, but not edit or delete).

Share with a User

POST /api/{section}/dashboards/{id}/shares

{
    "user_id": 5
}

Sharing is idempotent. Sharing with yourself returns a 422 validation error.

Remove a Share

DELETE /api/{section}/dashboards/{id}/shares/{user_id}

Authorization

The package ships with a DashboardPolicy that is automatically registered. The authorization rules are:

Database Schema

The package creates the following tables:

• dashboards - Stores dashboard records with user_id (owner), name, and section
• widgets - Widget catalog with key, name, description, type (datagrid/chart/metric), widget_class, route_path, and section
• dashboard_widgets - Pivot linking dashboards to widgets, storing layout (column_span, sort_order) and state (filter_sets, sorts, visibility)
• dashboard_shares - Pivot linking dashboards to shared users
• dashboard_revisions - Stores JSON snapshots of dashboard state for revision history

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Andrew Leach
• All Contributors

License

The MIT License (MIT). Please see License File for more information.