Report Builder Docs

Appearance

Start Here ​

Use this page to complete a clean end-to-end flow: install the package, define a trusted source, run a preview, and export CSV.

Prerequisites ​

  • PHP 8.3+
  • Laravel 11, 12, or 13
  • Composer

Step 1: Install the package ​

bash
composer require ihasan/report-builder
php artisan vendor:publish --tag="report-builder-config"

Step 2: Register your first data source ​

Register your first source during app boot (for example, in AppServiceProvider):

php
<?php

namespace App\Providers;

use App\Models\Order;
use Illuminate\Support\ServiceProvider;
use Ihasan\ReportBuilder\DataSources\EloquentDataSource;
use Ihasan\ReportBuilder\Enums\AggregateFunction;
use Ihasan\ReportBuilder\Enums\FilterOperator;
use Ihasan\ReportBuilder\ReportBuilder;
use Ihasan\ReportBuilder\Support\Field;

class AppServiceProvider extends ServiceProvider
{
    public function boot(ReportBuilder $reportBuilder): void
    {
        $reportBuilder->registerDataSource(
            new EloquentDataSource(
                key: 'orders',
                label: 'Orders',
                model: Order::class,
                fields: [
                    Field::string('customer_name')
                        ->label('Customer Name')
                        ->column('orders.customer_name')
                        ->sortable()
                        ->filterable([FilterOperator::Like]),
                    Field::string('status')
                        ->column('orders.status')
                        ->sortable()
                        ->filterable([FilterOperator::Equals, FilterOperator::In]),
                    Field::decimal('total_amount')
                        ->label('Total Amount')
                        ->column('orders.total_amount')
                        ->sortable()
                        ->groupable()
                        ->filterable([
                            FilterOperator::Equals,
                            FilterOperator::Between,
                        ])
                        ->aggregates([
                            AggregateFunction::Sum,
                        ]),
                ],
            )
        );
    }
}

Step 3: Build a report definition ​

php
<?php

use Ihasan\ReportBuilder\DTOs\OutputDefinition;
use Ihasan\ReportBuilder\DTOs\ReportDefinition;
use Ihasan\ReportBuilder\DTOs\SelectedColumn;
use Ihasan\ReportBuilder\DTOs\SortDefinition;

$definition = new ReportDefinition(
    sourceKey: 'orders',
    selectedColumns: [
        new SelectedColumn('customer_name', 'Customer'),
        new SelectedColumn('status'),
        new SelectedColumn('total_amount', 'Total'),
    ],
    sortDefinitions: [
        new SortDefinition('total_amount', 'desc'),
    ],
    outputDefinition: new OutputDefinition('csv', 'orders-report.csv'),
);

Step 4: Run a preview ​

php
<?php

use Ihasan\ReportBuilder\Execution\PreviewRunner;

$preview = app(PreviewRunner::class)->preview(
    definition: $definition,
    perPage: 25,
    page: 1,
);

Step 5: Export CSV ​

php
<?php

use Ihasan\ReportBuilder\Execution\ReportRunner;

$export = app(ReportRunner::class)->export($definition);

// $export = [
//   'filename' => 'orders-report.csv',
//   'mime_type' => 'text/csv; charset=UTF-8',
//   'content' => '...'
// ];

Verify ​

  • $preview contains columns, rows, and pagination.
  • $export['filename'] is orders-report.csv.
  • $export['mime_type'] is text/csv; charset=UTF-8.

Common mistakes ​

  • Using old enum names like FilterOperator::Eq instead of FilterOperator::Equals.
  • Forgetting to register your source during app boot, which causes unknown source_key errors.
  • Selecting fields that are not declared in your source definition.
  • Using a sort direction other than asc or desc.

Next ​

Continue with Build Your First Data Source.