Flotr2 Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require babaganoush/flotr2-bundle
   

   Enable it in config/bundles.php:

   Babaganoush\Flotr2Bundle\BabaganoushFlotr2Bundle::class => ['all' => true],
   

2. Basic Usage Inject the Flotr2Service in your controller:

   use Babaganoush\Flotr2Bundle\Service\Flotr2Service;
   
   class ChartController extends AbstractController
   {
       public function showChart(Flotr2Service $flotr2)
       {
           $chart = $flotr2->createChart();
           $chart->setTitle('Sample Chart');
           $chart->addSeries([
               'data' => [1, 2, 3, 4, 5],
               'label' => 'Sample Data'
           ]);
   
           return $this->render('@Flotr2/chart.html.twig', [
               'chart' => $chart->render()
           ]);
       }
   }
   

3. First Template Create a Twig template (e.g., templates/chart.html.twig) with the bundle's base template:

   {% extends '@Flotr2/base.html.twig' %}
   
   {% block flotr2_chart %}
       {{ chart }}
   {% endblock %}
   

Implementation Patterns

Common Workflows

1. Dynamic Data Binding Fetch data from Doctrine or API, then pass it to the chart:

   $data = $entityManager->getRepository(MyEntity::class)->findAll();
   $seriesData = array_map(fn($item) => $item->getValue(), $data);
   
   $chart->addSeries([
       'data' => $seriesData,
       'label' => 'Dynamic Data'
   ]);
   

2. Reusable Chart Components Create a base chart class for consistency:

   class BaseChartService
   {
       public function buildLineChart(Flotr2Service $flotr2, array $data, string $title)
       {
           $chart = $flotr2->createChart();
           $chart->setTitle($title);
           $chart->addSeries($data);
           return $chart;
       }
   }
   

3. Twig Integration Extend the base template to customize chart behavior:

   {% extends '@Flotr2/base.html.twig' %}
   
   {% block flotr2_options %}
       {{ parent() }}
       { "grid": { "hoverable": true } }
   {% endblock %}
   

4. Event-Driven Charts Use Symfony events to trigger chart updates:

   // In a listener
   $chart = $flotr2->createChart();
   $chart->addSeries($newData);
   $this->renderChartTemplate($chart);
   

Integration Tips

• Asset Management Ensure bmatzner/jquery-bundle is installed (dependency) and Flotr2 JS/CSS are loaded via Symfony's asset system.

  {{ encore_entry_link_tags('app') }}  {# If using Webpack Encore #}
  

• Configuration Overrides Override default settings in config/packages/flotr2.yaml:

  babaganoush_flotr2:
      default_options:
          colors: ['#f00', '#0f0', '#00f']
  

• Testing Mock Flotr2Service in PHPUnit:

  $this->mockBuilder()
       ->disableOriginalConstructor()
       ->getMock()
       ->method('render')
       ->willReturn('<div>Mocked Chart</div>');
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies Forgetting to install bmatzner/jquery-bundle will break JS/CSS loading. Verify dependencies with:

   composer require bmatzner/jquery-bundle
   

2. Twig Template Conflicts Overriding @Flotr2/base.html.twig without extending it may break the chart rendering. Always use {% extends %}.

3. Data Format Strictness Flotr2 expects numeric data for series. Non-numeric values (e.g., strings) will cause silent failures. Validate data:

   $seriesData = array_map('floatval', $rawData);
   

4. Caching Issues If charts appear stale, clear Symfony cache:

   php bin/console cache:clear
   

Debugging Tips

1. Inspect Rendered Output Dump the raw chart HTML to debug:

   dump($chart->render());
   

2. Check Console Errors Flotr2 relies on jQuery. Verify no JS errors in browser console (e.g., $ is not defined).

3. Default Options Override Debug option merging by inspecting the final data attribute in rendered HTML:

   {% block flotr2_options %}
       {{ dump(_self.vars.options) }}  {# Debug options #}
   {% endblock %}
   

Extension Points

1. Custom Chart Types Extend the bundle by creating a new service class:

   class PieChartService extends AbstractChartService
   {
       public function __construct(Flotr2Service $flotr2)
       {
           $this->flotr2 = $flotr2;
       }
   
       public function buildPie(array $data)
       {
           $chart = $this->flotr2->createChart();
           $chart->setType('pie');
           $chart->addSeries($data);
           return $chart;
       }
   }
   

2. Event Listeners Hook into flotr2.chart.render event to modify charts globally:

   // src/EventListener/Flotr2Listener.php
   public function onRender(Flotr2Event $event)
   {
       $event->getChart()->addSeries(['data' => [100], 'label' => 'Global Series']);
   }
   

3. Asset Customization Override Flotr2 assets by copying them to public/bundles/flotr2/ and modifying as needed.