README

A Laravel package that provides a complete API for managing user-configurable dashboards composed of DataGrid and Chart 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.3+
Laravel 11.x or 12.x
strucura/datagrids ^2.x
strucura/charts ^0.2

Installation

Install the package via Composer:

composer require strucura/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.

Registering Routes

The package provides a Route::dashboards() macro that mounts all dashboard API routes. Call it inside your own route group to control the prefix, middleware, and guards:

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

Route::middleware(['auth:sanctum', SubstituteBindings::class])
    ->prefix('api/dashboards')
    ->group(function () {
        Route::dashboards();
    });

This registers the following routes:

Method	URI	Description
`GET`	`/widgets`	List all available widgets
`GET`	`/`	List dashboards accessible by the authenticated user
`POST`	`/`	Create a new dashboard
`GET`	`/{dashboard}`	Show a dashboard with its widgets and permissions
`PATCH`	`/{dashboard}`	Update a dashboard's name and/or widgets
`POST`	`/{dashboard}/clone`	Clone a dashboard
`DELETE`	`/{dashboard}`	Delete a dashboard
`GET`	`/{dashboard}/revisions`	List revision history
`POST`	`/{dashboard}/revisions/{revision}/restore`	Restore a previous revision
`POST`	`/{dashboard}/shares`	Share a dashboard with a user
`DELETE`	`/{dashboard}/shares/{user}`	Remove a user's access to a shared dashboard

Registering Widgets

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

Implementing the Interface

Add the ShouldRegisterAsWidget interface to any DataGrid or Chart class:

use Strucura\Dashboards\Contracts\ShouldRegisterAsWidget;
use Strucura\DataGrid\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.';
    }

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

use Strucura\Charts\Abstracts\Chart;
use Strucura\Dashboards\Contracts\ShouldRegisterAsWidget;

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

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

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

Running the Registration Command

php artisan widget:register

Or register a specific class:

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/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/dashboards

{
    "name": "My Dashboard"
}

Show a Dashboard

GET /api/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/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:

Field	Type	Description
`widget_id`	integer, required	References a registered widget
`name`	string, nullable	Custom display name (falls back to widget's default name)
`column_span`	integer, required	Width in a 12-column grid (min: 3, max: 12)
`filter_sets`	array, nullable	Persisted filter configuration
`sorts`	array, nullable	Persisted sort configuration
`visibility`	array, nullable	Array of `{ field, is_hidden }` objects for datagrid columns

Clone a Dashboard

POST /api/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/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/dashboards/{id}/revisions

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

Restore a Revision

POST /api/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/dashboards/{id}/shares

{
    "user_id": 5
}

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

Remove a Share

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

Authorization

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

Action	Who Can Perform
View	Owner or any shared user
Create	Any authenticated user
Update	Owner only
Delete	Owner only
Share	Owner only
Restore Revision	Owner only

Database Schema

The package creates the following tables:

dashboards - Stores dashboard records with user_id (owner) and name
widgets - Widget catalog with key, name, description, type (datagrid/chart), widget_class, and route_path
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

License

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

strucura / dashboards

Maintainers

Details