Report Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (mirror repo):

   composer require chill-project/report
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Chill\ReportBundle\ChillReportBundle" --tag="config"
   

2. First Use Case Generate a basic report (assuming a Report facade or service):

   use Chill\ReportBundle\Report;
   
   $report = Report::create()
       ->setTitle('User Activity')
       ->addColumn('id', 'ID')
       ->addColumn('name', 'Username')
       ->fetchFromModel(\App\Models\User::class)
       ->render();
   

   Output the result (e.g., CSV, PDF, or HTML):

   return $report->toCSV()->download('user_activity.csv');
   

3. Key Files to Review

   • config/chill_report.php (default settings for formats, storage, etc.).
   • src/Chill/ReportBundle/Report.php (core class for report generation).
   • src/Chill/ReportBundle/Service/Renderer/ (format-specific renderers like CSVRenderer, PDFRenderer).

Implementation Patterns

1. Report Generation Workflow

• Chainable Methods: Use a fluent interface to build reports:

  $report = Report::create()
      ->setTitle('Sales Overview')
      ->addColumn('product', 'Product Name')
      ->addColumn('revenue', 'Total Revenue', fn($item) => '$' . number_format($item->revenue))
      ->filter('date', '>', now()->subMonth())
      ->fetchFromQuery(\DB::table('orders')->select('product', \DB::raw('SUM(amount) as revenue'))->groupBy('product'))
      ->render();
  

• Dynamic Data Sources:

  • Models: fetchFromModel(User::class, ['id', 'name']).
  • Queries: fetchFromQuery($builder).
  • Arrays: fetchFromArray($data).
  • APIs: Extend with a custom DataFetcher (see Extension Points).

• Formatting Columns:

  ->addColumn('created_at', 'Date', fn($date) => $date->format('Y-m-d'))
  ->addColumn('status', 'Status', fn($status) => ucfirst($status))
  

2. Output Handling

• Download Directly:

  return $report->toPDF()->download('report.pdf');
  

• Stream to Browser:

  return $report->toHTML()->stream();
  

• Store in Storage:

  $report->toCSV()->saveAs('storage/reports/user_activity.csv');
  

3. Reusable Report Definitions

Define report templates in config or a dedicated service:

// config/chill_report.php
'reports' => [
    'user_activity' => [
        'title' => 'User Activity Report',
        'columns' => [
            ['field' => 'id', 'label' => 'ID'],
            ['field' => 'name', 'label' => 'Username'],
        ],
        'model' => \App\Models\User::class,
    ],
],

Load via:

$report = Report::fromConfig('user_activity')->render();

4. Integration with Laravel Features

• Events: Trigger post-render events:

  Report::create()->onRendered(fn($report) => Log::info('Report generated', $report->toArray()));
  

• Commands: Schedule report generation:

  // app/Console/Commands/GenerateDailyReport.php
  public function handle() {
      Report::fromConfig('daily_sales')->toCSV()->saveAs('storage/reports/daily.csv');
  }
  

Gotchas and Tips

Pitfalls

1. Archived Package Risk:

   • The repo is archived (no active maintenance). Validate compatibility with your Laravel version (e.g., test with laravel/framework:^8.0 or ^9.0).
   • Fork the repo if critical fixes are needed.

2. Renderer Limitations:

   • PDF rendering may require dompdf or tcpdf (not bundled). Install via:

     composer require dompdf/dompdf
     

   • HTML rendering assumes Blade templates in resources/views/chill_report/. Override defaults by publishing assets:

     php artisan vendor:publish --tag="chill-report-views"
     

3. Memory Issues:

   • Large datasets may cause timeouts. Use chunking for queries:

     ->fetchFromQuery($query->cursor())
     

4. AGPL License:

   • Ensure compliance with AGPL-3.0 if distributing modified versions.

Debugging Tips

• Enable Logging: Set debug: true in config/chill_report.php to log report generation steps.
• Inspect Data: Dump raw data before rendering:

  $data = $report->getData()->toArray();
  dd($data);
  

• Renderer Errors: Check if the Renderer interface is implemented for custom formats. Extend AbstractRenderer for new formats.

Extension Points

1. Custom Data Fetchers:

   // app/Providers/ReportServiceProvider.php
   public function register() {
       Report::extend('api', function($report) {
           return new ApiDataFetcher($report);
       });
   }
   

   Usage:

   Report::create()->fetchFrom('api', 'https://api.example.com/data');
   

2. New Renderers:

   // app/Renderers/ExcelRenderer.php
   class ExcelRenderer extends AbstractRenderer {
       public function render(): void {
           Excel::create('Report', function($excel) use ($this) {
               $excel->sheet('Report', $this->data);
           })->download('report.xlsx');
       }
   }
   

   Register in config/chill_report.php:

   'renderers' => [
       'excel' => \App\Renderers\ExcelRenderer::class,
   ],
   

3. Override Defaults:

   • Publish and modify config/chill_report.php.
   • Override views in resources/views/vendor/chill_report/.

Performance Optimizations

• Cache Reports:

  $report = Report::fromConfig('user_activity')->cacheFor(3600)->render();
  

• Lazy Loading: Use cursor() for large datasets to avoid loading all rows into memory.

Testing

• Mock the Report facade in tests:

  $this->mock(Report::class)->shouldReceive('create')->andReturnSelf()->andReturn($mockReport);