Reportbuilderbundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the package via Composer:

   composer require brown298/reportbuilderbundle
   

   Register the bundle in config/app.php under providers:

   Brown298\ReportBuilderBundle\ReportBuilderBundle::class,
   

2. First Use Case: Basic Report Generation

   • Publish the bundle’s assets and configuration:

     php artisan vendor:publish --provider="Brown298\ReportBuilderBundle\ReportBuilderBundle" --tag="config"
     

   • Define a simple report in a controller or service:

     use Brown298\ReportBuilderBundle\ReportBuilder;
     
     public function generateReport()
     {
         $report = new ReportBuilder();
         $report->setTitle('Sample Report')
                ->addColumn('ID', 'id')
                ->addColumn('Name', 'name')
                ->setDataSource($this->fetchDataFromDatabase())
                ->generate('pdf', 'storage/app/reports/sample.pdf');
     }
     

3. Where to Look First

   • Configuration: Check config/reportbuilder.php for default settings (e.g., output formats, storage paths).
   • Documentation: Review the README.md in the repository for API references and examples.
   • Service Container: Inspect the bundle’s service providers (ReportBuilderBundle) for registered services (e.g., ReportBuilder, ReportRenderer).

Implementation Patterns

Common Workflows

1. Dynamic Report Generation Use the ReportBuilder class to construct reports programmatically:

   $report = new ReportBuilder();
   $report->setTitle($request->input('title'))
          ->addColumn($request->input('column_name'), 'column_key')
          ->setDataSource($this->getFilteredData($request->all()))
          ->generate($request->input('format'), $outputPath);
   

2. Reusable Report Templates Extend the ReportBuilder class to create domain-specific report builders:

   class SalesReportBuilder extends ReportBuilder
   {
       public function __construct()
       {
           $this->setTitle('Monthly Sales Report')
                ->addColumn('Product', 'product_name')
                ->addColumn('Revenue', 'revenue', 'currency')
                ->setDefaultFormat('xlsx');
       }
   }
   

3. Integration with Laravel Views Render reports as HTML for inline preview or email attachments:

   $html = $report->generate('html');
   return new Response($html);
   // Or send via Mail:
   Mail::send([], [], function ($message) use ($html) {
       $message->subject('Your Report')
               ->setBody($html, 'text/html');
   });
   

4. Data Source Flexibility Support Eloquent models, collections, or raw arrays:

   // Eloquent Model
   $report->setDataSource(User::where('active', 1)->get());
   
   // Raw Array
   $report->setDataSource([
       ['id' => 1, 'name' => 'John'],
       ['id' => 2, 'name' => 'Jane'],
   ]);
   

5. Scheduled Reports Use Laravel’s task scheduling to generate reports periodically:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule)
   {
       $schedule->call(function () {
           $report = new ReportBuilder();
           $report->setDataSource($this->getDailySales())
                  ->generate('pdf', 'storage/app/reports/daily_sales.pdf');
       })->daily();
   }
   

Integration Tips

• Storage: Configure storage_path() or custom paths in config/reportbuilder.php for output files.
• Dependencies: Ensure dompdf (for PDF) or phpoffice/phpspreadsheet (for Excel) is installed if using those formats.
• Caching: Cache frequent reports using Laravel’s cache system:

  $cacheKey = 'report_' . md5($request->input());
  $reportData = Cache::remember($cacheKey, now()->addHours(1), function () use ($report) {
      return $report->generate('pdf');
  });
  

Gotchas and Tips

Pitfalls

1. Format-Specific Dependencies

   • PDF: Requires dompdf/dompdf. Install via:

     composer require dompdf/dompdf
     

   • Excel: Requires phpoffice/phpspreadsheet. Install via:

     composer require phpoffice/phpspreadsheet
     

   • Error: If formats fail silently, check storage/logs/laravel.log for missing dependencies.

2. Data Source Mismatches

   • Issue: Reports may render incorrectly if data keys don’t match column definitions.
   • Fix: Validate data structure before passing to setDataSource():

     $data = $this->validateReportData($rawData);
     $report->setDataSource($data);
     

3. Memory Limits

   • Issue: Large datasets may hit PHP’s memory limit (Allowed memory size exhausted).
   • Fix: Use chunking for data processing or increase memory_limit in php.ini.

4. Configuration Overrides

   • Issue: Bundle settings may not update after publishing config.
   • Fix: Clear config cache:

     php artisan config:clear
     

Debugging

• Log Output: Enable debug mode in config/reportbuilder.php to log generation steps:

  'debug' => env('APP_DEBUG', false),
  

• Test with Minimal Data: Start with 1-2 rows to isolate rendering issues.
• Check Renderer Errors: Wrap generation in a try-catch:

  try {
      $report->generate('pdf', $path);
  } catch (\Exception $e) {
      Log::error('Report generation failed: ' . $e->getMessage());
      throw $e;
  }
  

Extension Points

1. Custom Renderers Extend the ReportRenderer interface to support new formats (e.g., CSV, JSON):

   class CustomRenderer implements ReportRenderer
   {
       public function render(array $data, string $format): string
       {
           // Custom logic (e.g., JSON serialization)
           return json_encode($data);
       }
   }
   

   Register the renderer in the bundle’s service provider.

2. Column Formatting Override column rendering via a callback:

   $report->addColumn('Price', 'price', null, function ($value) {
       return '$' . number_format($value, 2);
   });
   

3. Event Listeners Listen for report generation events (e.g., ReportGenerating, ReportGenerated) to log or modify reports:

   // In a service provider
   $this->app->booted(function () {
       event(new ReportGenerating($report));
   });
   

4. Localization Support multi-language reports by overriding the setTitle() and column labels dynamically:

   $report->setTitle(__('report.title'))
          ->addColumn(__('report.columns.name'), 'name');