Report Builder Docs

Appearance

Core Types and Enums ​

This reference summarizes the core package types used to define sources, build report definitions, run previews, and export files.

Core classes ​

  • Ihasan\ReportBuilder\ReportBuilder
    • registerDataSource(DataSourceContract $dataSource): void
    • dataSource(string $key): DataSourceContract
    • dataSources(): array
  • Ihasan\ReportBuilder\Execution\PreviewRunner
    • executes a ReportDefinition and returns paginated preview output
  • Ihasan\ReportBuilder\Execution\ReportRunner
    • executes a ReportDefinition and returns export payloads
  • Ihasan\ReportBuilder\DataSources\EloquentDataSource
    • default implementation for model-backed sources
  • Ihasan\ReportBuilder\Support\Field
    • fluent builder for FieldDefinition

Contracts ​

  • DataSourceContract
    • key(): string - stable machine key for report definitions
    • label(): string - human-readable source label
    • fields(): array - all allowed FieldDefinition values
    • field(string $key): ?FieldDefinition - lookup one field by key
    • query(): EloquentBuilder|QueryBuilder - trusted base query for this source
    • applyScope(...): EloquentBuilder|QueryBuilder - apply user/tenant/request scopes
    • authorize(Request $request): bool - controls source access in your app layer

Core DTOs ​

  • ReportDefinition
    • root object containing source_key, selected_columns, filters, sorts, output
  • SelectedColumn
    • a selected field and optional output label override
  • FilterCondition and FilterGroup
    • filter tree with nested and / or logic
  • SortDefinition
    • field key + direction (asc or desc)
  • OutputDefinition
    • output format and optional filename

Column definitions with Field ​

Each field key is part of your public report-definition contract. column() maps that key to a trusted DB column.

php
Field::decimal('total_amount')
    ->label('Total Amount')
    ->column('orders.total_amount')
    ->sortable()
    ->groupable()
    ->filterable([FilterOperator::Equals, FilterOperator::Between])
    ->aggregates([AggregateFunction::Sum]);

Rule of thumb:

  • key = report definition contract
  • column = backend trusted mapping
  • operators/aggregates = allowlist for execution

Execution return contracts ​

  • Preview (PreviewRunner::preview) returns:
    • columns
    • rows
    • pagination
  • Export (ReportRunner::export) returns:
    • filename
    • mime_type
    • content

Enums ​

  • FieldType
    • string, integer, decimal, boolean, date, datetime
  • FilterOperator
    • =, !=, >, >=, <, <=, like, not_like, starts_with, ends_with, in, not_in, between, not_between, is_null, is_not_null, date_equals, date_before, date_after, this_week, this_month, this_year, last_n_days
  • AggregateFunction
    • count, sum, avg, min, max

Exceptions you will commonly see ​

  • DataSourceAlreadyRegisteredException
  • DataSourceNotFoundException
  • InvalidDataSourceConfigurationException
  • InvalidReportDefinitionException