PHPackages                             hasanhawary/report-builder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. hasanhawary/report-builder

ActiveLibrary[PDF & Document Generation](/categories/documents)

hasanhawary/report-builder
==========================

A modular Laravel report builder for cards, charts, and tables.

1.3.2(3w ago)1425↓60%MITPHPPHP >=8.1 <8.6

Since Sep 21Pushed 3w agoCompare

[ Source](https://github.com/hasanhawary/report-builder)[ Packagist](https://packagist.org/packages/hasanhawary/report-builder)[ Docs](https://github.com/hasanhawary/report-builder)[ RSS](/packages/hasanhawary-report-builder/feed)WikiDiscussions main Synced 2d ago

READMEChangelogDependencies (5)Versions (13)Used By (0)

📊 Laravel Report Builder
========================

[](#-laravel-report-builder)

[![Latest Version on Packagist](https://camo.githubusercontent.com/96cded1861683ae4d5178494d1a80e1729e0de4cc43477d1e1426f8dfed7acf6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686173616e6861776172792f7265706f72742d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hasanhawary/report-builder)[![Total Downloads](https://camo.githubusercontent.com/79f79e7c6d2ee1cb7499cee34a65b5f0deb3928a20c56c8eff2317b5ff116077/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f686173616e6861776172792f7265706f72742d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hasanhawary/report-builder)[![License](https://camo.githubusercontent.com/f7f8fb1ce0989559dba5e1e868289ec771f19dffed9176e03007e0e0b8f8cb36/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f686173616e6861776172792f7265706f72742d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

A powerful, modular **report builder for Laravel** that simplifies the generation of **cards, charts, and tables**.
Easily configurable via `config/report.php`, it provides a unified JSON structure perfect for **HighCharts** and modern frontends like Vue, React, or Inertia.

---

✨ Features
----------

[](#-features)

- 🚀 **Unified Data Structure**: Seamlessly generate cards, charts, and tables.
- 📈 **HighCharts Ready**: Pre-configured for popular chart types (Bar, Line, Spline, Area, Column, Pie).
- 🧩 **Modular & Clean**: Define report pages in config and implement logic in dedicated classes.
- 🛠 **Dynamic Filtering**: Built-in support for date ranges and custom advanced filters.
- 🌍 **Multi-language Support**: Automatic translation of labels and titles using Laravel's localization.
- 🎨 **Frontend Agnostic**: Clean JSON response ready for any JS library.

---

📦 Installation
--------------

[](#-installation)

```
composer require hasanhawary/report-builder
```

Publish the configuration files:

```
php artisan vendor:publish --tag=report-builder-config
```

The package registers its own routes automatically. By default:

- `GET /api/report` (`report.index`)

You can disable, move, or rename this route from `config/report.php` if the host project already uses the same URLs or route names.

### Upgrade Note

[](#upgrade-note)

If you previously published `config/report.php`, Composer updates will not overwrite that file. To use the current default package route `GET /api/report`, update your published config manually or republish it:

```
php artisan vendor:publish --tag=report-builder-config --force
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Define your report structure in **`config/report.php`**:

```
return [
    'routes' => [
        'enabled' => true,
        'prefix' => 'api/report',
        'middleware' => ['api'],
        'name_prefix' => 'report.',
        'paths' => [
            'report' => '/',
        ],
        'names' => [
            'report' => 'index',
        ],
    ],

    'namespace' => 'App\\Reports', // Optional global namespace for report classes.

    'translate' => [
        'enabled' => true,
        'trans_file' => 'report',
    ],

    'pages' => [
        'user' => [
            'type' => 'page',
            // Optional explicit class. This is recommended when you do not use a global namespace.
            'class' => App\Reports\UserReport::class,
            'report' => [
                'stats' => [
                    'type' => 'card',
                    'size' => ['cols' => '12', 'md' => '12', 'lg' => '12'],
                ],
                'registered_by_date' => [
                    'type' => 'spline',
                    'size' => ['cols' => '12', 'md' => '6', 'lg' => '6'],
                ],
                'user_list' => [
                    'type' => 'table',
                    'size' => ['cols' => '12', 'md' => '6', 'lg' => '6'],
                ],
            ],
        ]
    ],
];
```

---

🛣 Prepared Routes
-----------------

[](#-prepared-routes)

Report Builder ships its Laravel routes from the package service provider, so host projects do not need to copy routes or controllers into `routes/web.php`, `routes/api.php`, or `app/Http`.

Default prepared routes:

MethodURIRoute nameController`GET``/api/report``report.index``HasanHawary\ReportBuilder\Http\Controllers\ReportController`The default middleware is `['api']`.

For protected report APIs, publish the config and add your auth middleware:

```
'routes' => [
    'enabled' => true,
    'prefix' => 'api/report',
    'middleware' => ['api', 'auth:sanctum'],
    'name_prefix' => 'report.',
],
```

### Avoiding Route Conflicts

[](#avoiding-route-conflicts)

If your Laravel project already has `/api/report` or `report.index`, publish the config and change the package route settings:

```
php artisan vendor:publish --tag=report-builder-config
```

Move the package route under another URL prefix:

```
'routes' => [
    'enabled' => true,
    'prefix' => 'api/report-builder',
    'middleware' => ['api'],
    'name_prefix' => 'report-builder.',
],
```

This changes the default routes to:

- `GET /api/report-builder` (`report-builder.index`)

You can also change only the individual paths and names:

```
'routes' => [
    'enabled' => true,
    'prefix' => 'api',
    'middleware' => ['api'],
    'name_prefix' => 'rb.',
    'paths' => [
        'report' => 'report-builder',
    ],
    'names' => [
        'report' => 'index',
    ],
],
```

Or disable the package routes completely if you only want to instantiate `ReportBuilder`directly:

```
'routes' => [
    'enabled' => false,
],
```

Route configuration is merged with package defaults, so a host project can override only the values it needs. Setting `middleware` to an empty array is supported when you need public or API-only routes:

```
'middleware' => [],
```

---

🛠 Usage
-------

[](#-usage)

### 1. Create your Report Class

[](#1-create-your-report-class)

Extend `BaseReport` and implement methods matching your config keys (prefixed with `get`).

```
namespace App\Reports;

use HasanHawary\ReportBuilder\BaseReport;
use Illuminate\Support\Facades\DB;

class UserReport extends BaseReport
{
    public string $table = 'users';

    /**
     * Data for summary cards
     */
    public function getStats(): array
    {
        $data = [
            'total' => DB::table($this->table)->count(),
            'active' => DB::table($this->table)->where('active', 1)->count(),
        ];

        return $this->cardResponse($data);
    }

    /**
     * Data for a spline chart
     */
    public function getRegisteredByDate(): array
    {
        $data = DB::table($this->table)
            ->selectRaw("DATE_FORMAT(created_at, '%Y-%m-%d') as date, COUNT(*) as count")
            ->groupBy('date')
            ->get();

        return $this->chartResponse('date', $data);
    }

    /**
     * Data for a table
     */
    public function getUserList(): array
    {
        $data = DB::table($this->table)
            ->select('id', 'name', 'email', 'created_at')
            ->limit(10)
            ->get();

        return $this->chartResponse('id', $data); // chartResponse handles 'table' type automatically
    }
}
```

### 2. Fetch the Report

[](#2-fetch-the-report)

Use the package route or instantiate `ReportBuilder` directly.

```
use HasanHawary\ReportBuilder\ReportBuilder;

public function index()
{
    return (new ReportBuilder([
        'page' => 'user',
        'start' => '2024-01-01',
        'end' => '2024-12-31',
    ]))->response();
}
```

---

📊 Available Response Helpers
----------------------------

[](#-available-response-helpers)

Inside your report classes, use these helpers to format data:

- `$this->cardResponse($data)`: Formats simple key-value pairs into card data.
- `$this->chartResponse($groupByField, $data)`: Formats collections into HighCharts-ready structures.
- `$this->guessDateFormat()`: Automatically determines the best date format for chart axes based on filtered range.

---

🌍 Localization
--------------

[](#-localization)

The package reads report titles, card labels, chart categories, chart series names, and table columns from the configured translation file:

```
'translate' => [
    'enabled' => true,
    'trans_file' => 'report',
],
```

With the default value, label keys like `total_users` are resolved from:

```
__('report.total_users')
```

To use another file, set `trans_file`:

```
'translate' => [
    'trans_file' => 'dashboard',
],
```

Then the same key is resolved from:

```
__('dashboard.total_users')
```

---

🎨 Frontend Integration
----------------------

[](#-frontend-integration)

### JSON Response

[](#json-response)

Calling `GET /api/report?page=user` returns a JSON envelope. Frontend chart and card data lives under `data.report`.

```
{
  "status": true,
  "code": 200,
  "message": "Success",
  "data": {
    "report": {
      "cards": {
        "data": [
          {
            "key": "total_users",
            "label": "Total users",
            "value": 120
          }
        ]
      },
      "charts": [
        {
          "type": "spline",
          "title": "registered_by_date",
          "data": {
            "spline": {}
          }
        }
      ],
      "tables": []
    }
  }
}
```

### Vue 3 + Highcharts

[](#vue-3--highcharts)

```

import { ref, onMounted } from 'vue';
import Highcharts from 'highcharts';

const reports = ref(null);

onMounted(async () => {
  const res = await fetch('/api/report?page=user');
  const json = await res.json();
  reports.value = json.data.report;
});

       {{ card.label }}: {{ card.value }}

```

---

✅ Version Support
-----------------

[](#-version-support)

- **PHP**: 8.0+
- **Laravel**: 10, 11, 12, 13

Runtime Boundary
----------------

[](#runtime-boundary)

This package is designed for Laravel applications. The route, controller, request validation, translation, database helpers, and service provider are Laravel-only features and require a Laravel application container.

The package does not depend on any `App\...` class by default. Host applications provide report classes either with `report.namespace` or with a page-specific `report.pages.{page}.class`. If no report class is configured, the package returns a clear configuration error instead of assuming an application namespace.

Plain PHP projects can reuse simple data-shaping ideas from the package, but the shipped implementation expects Laravel helpers such as `config()`, `app()`, `trans()`, and Laravel's database/query components. In non-Laravel runtimes, use this package behind a Laravel adapter or provide your own wrapper around the report classes.

---

📜 License
---------

[](#-license)

MIT © [Hasan Hawary](https://github.com/hasanhawary)

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance94

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 69.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~26 days

Recently: every ~43 days

Total

11

Last Release

26d ago

PHP version history (3 changes)v1.0.0PHP ^8.0

v1.0.1PHP >8.0

1.3.0PHP >=8.1 <8.6

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/33836947?v=4)[Hassan Elhawary](/maintainers/hasanhawary)[@hasanhawary](https://github.com/hasanhawary)

---

Top Contributors

[![hasanhawary](https://avatars.githubusercontent.com/u/33836947?v=4)](https://github.com/hasanhawary "hasanhawary (9 commits)")[![hassanmuhammd](https://avatars.githubusercontent.com/u/126090873?v=4)](https://github.com/hassanmuhammd "hassanmuhammd (4 commits)")

---

Tags

laravelreportdashboardanalyticschartstablesreports

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hasanhawary-report-builder/health.svg)

```
[![Health](https://phpackages.com/badges/hasanhawary-report-builder/health.svg)](https://phpackages.com/packages/hasanhawary-report-builder)
```

###  Alternatives

[moonshine/moonshine

Laravel administration panel

1.3k253.1k81](/packages/moonshine-moonshine)[eliseekn/laravel-metrics

Generate easily metrics and trends data of your models for your dashboards.

1347.7k](/packages/eliseekn-laravel-metrics)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)