README

Report Registry and Execution Engine for Laravel

Overview

3neti/report-registry is a Laravel package for defining, discovering, executing, and rendering reports using YAML-based drivers.

It provides:

• Driver-based report definitions (YAML)
• Resolver-driven data execution
• Pluggable output formatters (JSON, HTML, CSV, Text)
• Clean separation between data resolution and rendering

Key Concepts

Report Driver

A YAML file that defines:

• metadata (id, title, description)
• columns
• filters
• resolver class
• optional templates

Resolver

A class that implements:

ReportResolverInterface

Responsible for fetching and returning report data.

Executor

ReportExecutor orchestrates:

• loading the driver
• executing the resolver
• returning either raw data or formatted output

Output Modes

The executor supports two output categories:

1. Raw (machine-readable)

Returns structured PHP array:

$result = $executor->execute('sales', format: 'raw');

Structure:

[
  'report' => [...],
  'data' => [...],
  'meta' => [...]
]

2. Rendered (string output)

Formats:

• json
• html
• csv
• text

$json = $executor->execute('sales', format: 'json');
$html = $executor->execute('sales', format: 'html');

All return strings.

Example Usage

$executor = app(ReportExecutor::class);

// Raw payload
$data = $executor->execute('sales', format: 'raw');

// JSON output
$json = $executor->execute('sales', format: 'json');

// HTML output
$html = $executor->execute('sales', format: 'html');

Resolver Example

class SalesReportResolver implements ReportResolverInterface
{
    public function resolve(
        array $filters = [],
        ?string $sort = null,
        string $sortDirection = 'desc',
        int $perPage = 10,
        int $page = 1,
    ): array {
        return [
            'data' => [
                [
                    'reference' => 'INV-001',
                    'amount' => 1250.50,
                    'status' => 'approved',
                ]
            ],
            'meta' => [
                'total' => 1,
                'page' => 1,
                'per_page' => $perPage,
            ],
        ];
    }
}

CLI Usage

php artisan report:run sales --format=json
php artisan report:run sales --format=html
php artisan report:run sales --format=raw

Options:

• --filter=status:approved
• --sort=created_at
• --sort-dir=asc
• --per-page=50
• --page=1
• --output=report.json

Formatter Contract

All formatters implement:

ReportFormatterInterface

public function format(ReportDriverData $driver, array $data, array $meta): string;

Built-in formatters:

• JSON
• HTML
• CSV
• Text

Driver Structure (YAML)

driver:
  id: sales
  version: 1.1.0
  title: Sales Report

columns:
  - key: reference
    label: Reference
  - key: amount
    label: Amount

resolver: App\Reports\SalesReportResolver

Design Principles

• Separation of concerns
  • Resolver = data
  • Formatter = output
• Driver-driven architecture
• Extensible format system
• API-first execution model

Testing

Run tests:

composer test

Coverage includes:

• driver loading
• version resolution
• execution
• formatting
• output contracts

License

MIT