Reports Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require egb/reports-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Egb\ReportsBundle\EgbReportsBundle::class => ['all' => true],
   ];
   

2. First Report Define a report class (e.g., src/Report/UserReport.php):

   namespace App\Report;
   
   use Egb\ReportsBundle\Report\AbstractReport;
   
   class UserReport extends AbstractReport
   {
       protected $title = 'User Activity Report';
       protected $columns = [
           'id' => 'ID',
           'name' => 'Name',
           'email' => 'Email',
       ];
       protected $data = []; // Populate via query builder or array
   
       public function getData()
       {
           return $this->data;
       }
   }
   

3. Route & Controller

   // routes.yaml
   reports_user:
       path: /reports/user
       controller: App\Controller\ReportController::userReport
   

   // src/Controller/ReportController.php
   use Egb\ReportsBundle\Report\ReportManager;
   
   class ReportController
   {
       public function userReport(ReportManager $reportManager)
       {
           $report = new UserReport();
           $report->setData(User::all()->toArray()); // Example data source
           return $reportManager->render($report);
       }
   }
   

4. View Template Create a Twig template (templates/reports/user_report.html.twig):

   {% extends 'EgbReportsBundle::report.html.twig' %}
   {% block report_title %}{{ report.title }}{% endblock %}
   

Implementation Patterns

Data Fetching Workflows

1. Query Builder Integration Use Eloquent or Doctrine queries to populate $data:

   $report->setData(User::where('active', true)->get()->toArray());
   

2. Dynamic Columns Define columns dynamically in buildColumns():

   protected function buildColumns()
   {
       return [
           'created_at' => 'Registration Date',
           'role' => 'Role',
       ];
   }
   

3. Export Formats Leverage the ReportManager for CSV/Excel exports:

   $reportManager->export($report, 'csv');
   

Templating Patterns

1. Custom Styling Override Twig blocks in your template:

   {% block report_header %}
       <h1>{{ report.title }} ({{ report.data|length }} records)</h1>
   {% endblock %}
   

2. Conditional Rendering Use Twig logic to hide/show columns:

   {% if report.showColumn('email') %}
       <th>{{ report.getColumnTitle('email') }}</th>
   {% endif %}
   

Advanced Use Cases

1. Multi-Source Reports Merge data from multiple queries:

   $report->setData([
       'users' => User::all()->toArray(),
       'stats' => Stat::whereYear('created_at', date('Y'))->get()->toArray(),
   ]);
   

2. Parameterized Reports Inject parameters via constructor:

   class UserReport extends AbstractReport
   {
       public function __construct($startDate, $endDate)
       {
           $this->startDate = $startDate;
           $this->endDate = $endDate;
       }
   
       public function getData()
       {
           return User::whereBetween('created_at', [$this->startDate, $this->endDate])
                       ->get()
                       ->toArray();
       }
   }
   

3. API-Driven Reports Return JSON for frontend consumption:

   return $reportManager->toArray($report);
   

Gotchas and Tips

Common Pitfalls

1. Data Structure Requirements

   • The bundle expects $data to be an array of associative arrays.
   • Fix: Use toArray() on Eloquent collections or ensure Doctrine entities are hydrated to arrays.

2. Column Name Mismatches

   • If $columns keys don’t match array keys in $data, columns will render empty.
   • Tip: Use getColumnTitle() with fallback:

     {{ report.getColumnTitle('non_existent', 'N/A') }}
     

3. Caching Headaches

   • Reports with dynamic data (e.g., now()) may not refresh.
   • Solution: Disable caching for the route or use cache:clear after updates.

4. Twig Template Overrides

   • Forgetting to extend EgbReportsBundle::report.html.twig will break rendering.
   • Tip: Use {% extends 'EgbReportsBundle::report.html.twig' %} as the first line.

Debugging Tips

1. Inspect Report Data Dump the report object in the controller:

   dd($reportManager->toArray($report));
   

2. Check Column Definitions Verify $columns in your report class matches the data structure:

   // Debug column keys
   $this->columns = array_flip(array_keys($this->data[0] ?? []));
   

3. Export Issues

   • If CSV/Excel exports fail, ensure the league/csv or phpoffice/phpexcel packages are installed.
   • Fix: Run composer require league/csv or composer require phpoffice/phpexcel.

Extension Points

1. Custom Report Types Extend AbstractReport to add methods like formatValue():

   protected function formatValue($key, $value)
   {
       if ($key === 'created_at') {
           return (new \DateTime($value))->format('Y-m-d H:i');
       }
       return $value;
   }
   

2. Override Rendering Logic Replace the Twig template entirely by injecting a custom renderer:

   # config/packages/egb_reports.yaml
   egb_reports:
       renderer: 'App\Renderer\CustomReportRenderer'
   

3. Add Actions to Rows Include action buttons/links in the report:

   {% for row in report.data %}
       <tr>
           {% for column in report.columns %}
               <td>{{ row[column] }}</td>
           {% endfor %}
           <td>
               <a href="{{ path('user_edit', {'id': row.id}) }}">Edit</a>
           </td>
       </tr>
   {% endfor %}
   

Configuration Quirks

1. Default Export Format Set the default export format in config/packages/egb_reports.yaml:

   egb_reports:
       default_export: 'csv' # or 'excel'
   

2. Disable Pagination If using large datasets, disable pagination in the Twig template:

   {% set pagination = false %}
   {% include 'EgbReportsBundle::report.html.twig' %}
   

3. Localization Translate column titles via translation files:

   # messages.en.yaml
   reports.columns.id: 'User ID'
   reports.columns.name: 'Full Name'
   

   Then reference in the report:

   protected $columns = [
       'id' => 'reports.columns.id',
       'name' => 'reports.columns.name',
   ];