bharatbkj/laravel-report-builder

Natural-language report builder UI and API for Laravel applications.

v1.0.0 2026-05-23 06:48 UTC

Requires

• php: ^8.2
• illuminate/cache: ^11.0|^12.0
• illuminate/database: ^11.0|^12.0
• illuminate/http: ^11.0|^12.0
• illuminate/routing: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• illuminate/view: ^11.0|^12.0
• psr/log: ^2.0|^3.0

MIT

README

Installable Laravel package that converts plain-English report requests into safe read-only reports against the host application's database.

Features

• Compact Report Builder UI.
• JSON report endpoint for admin panel integrations.
• Explicit table allowlist.
• Explicit join allowlist.
• Protected-column filtering.
• Column selection, numeric filters, text filters, ranges, sorting, and counts.
• CSV, JSON, and Print PDF actions in the packaged UI.
• Query execution time and optional audit logs.
• No generated SQL returned to users.

Requirements

• PHP 8.2 or newer.
• Laravel 11 or Laravel 12.

Install

After publishing this package in a Composer repository:

composer require bharatbkj/laravel-report-builder
php artisan vendor:publish --tag=report-builder-config
php artisan vendor:publish --tag=report-builder-migrations
php artisan migrate

For local development from a package directory, add a Composer path repository in the host application's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/report-builder"
        }
    ]
}

Then run:

composer require bharatbkj/laravel-report-builder:@dev

Laravel discovers ReportBuilder\ReportBuilderServiceProvider automatically.

Configure Tables

The package queries no tables by default. In config/report-builder.php, permit business-reporting tables only:

'allowed_tables' => [
    'students' => [
        'label' => 'Students',
        'aliases' => ['student', 'learners'],
    ],
    'student_attendances' => [
        'label' => 'Attendance',
        'aliases' => ['attendance', 'attendances'],
    ],
],

'column_aliases' => [
    'student_attendances' => [
        'attendance_percent' => ['attendance', 'attendance percentage'],
    ],
],

'value_lookup_columns' => [
    'students' => ['name', 'course'],
    'student_attendances' => ['month', 'status'],
],

Only configure lookup columns where discovering values for natural-language matching is acceptable.

Configure Safe Joins

Joins occur only when defined in configuration:

'relationships' => [
    [
        'left_table' => 'students',
        'left_key' => 'id',
        'right_table' => 'student_attendances',
        'right_key' => 'student_id',
        'aliases' => ['attendance', 'attendances'],
    ],
],

Example questions after this configuration:

show BCA students with attendance below 90 only name course marks attendance status
show MBA students with marks above 80 and attendance over 90 only name marks attendance status
count BCA students with attendance below 90

Routes

The UI route is enabled by default with web and auth middleware:

GET  /report-builder
GET  /report-builder/meta
POST /report-builder/query

For an external API integration, first configure a suitable authentication middleware, then enable API routes:

'api' => [
    'enabled' => true,
    'prefix' => 'api/report-builder',
    'middleware' => ['api', 'auth:sanctum', 'throttle:60,1'],
],

API endpoints:

GET  /api/report-builder/meta
POST /api/report-builder/query

Request:

{
    "query": "show BCA students only name and marks with marks above 80"
}

Response:

{
    "question": "show BCA students only name and marks with marks above 80",
    "data": [],
    "columns": [],
    "row_count": 0,
    "summary": "0 rows returned.",
    "suggestions": [],
    "meta": {
        "execution_ms": 10,
        "limited_to": 500,
        "joined": false
    }
}

Security

• Leave authentication enabled for every UI and API route.
• Allowlist only report tables required by the client.
• Configure joins explicitly.
• Keep passwords, tokens, session values, secrets, and private attributes blocked.
• Use a read-only database connection when the report builder connects to a reporting replica or separate database.
• Limit searchable value columns and keep the row limit bounded.
• Publish and run the audit migration for production use.

Customizing The UI

Publish the Blade view:

php artisan vendor:publish --tag=report-builder-views

The host application can then customize:

resources/views/vendor/report-builder/index.blade.php