Highcharts Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ob/highcharts-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Ob\HighchartsBundle\ObHighchartsBundle::class => ['all' => true],
   ];
   

2. First Chart in Twig:

   {{ render_highchart({
       'type': 'line',
       'title': { 'text': 'Sample Chart' },
       'series': [{
           'name': 'Data',
           'data': [1, 2, 3, 4, 5]
       }]
   }) }}
   

3. Key Files to Review:

   • Resources/doc/usage.md (core usage patterns)
   • Resources/doc/cookbook.md (practical examples)
   • Resources/doc/installation.md (Symfony 5/6 compatibility notes)

First Use Case: Dynamic Data Binding

// Controller
public function salesChartAction()
{
    $data = [100, 200, 150, 300, 250]; // From DB or service
    return $this->render('chart.html.twig', [
        'chartData' => $data
    ]);
}

// Twig
{{ render_highchart({
    'type': 'column',
    'series': [{
        'name': 'Sales',
        'data': chartData
    }]
}) }}

Implementation Patterns

Core Workflow: PHP-First Configuration

1. Define Chart Structure in PHP:

   use Ob\HighchartsBundle\Highcharts\Highchart;
   
   $chart = new Highchart();
   $chart->chart->type('line')
          ->title('Monthly Visits')
          ->series([
              new \Ob\HighchartsBundle\Highcharts\Series([
                  'name' => 'Users',
                  'data' => [10, 20, 15, 30, 45]
              ])
          ]);
   

2. Twig Integration:

   {{ render_highchart(chart) }}
   

Common Patterns

Data Binding

• Static Data:

  $chart->series([['data' => [1, 2, 3]]]);
  

• Dynamic Data (from Doctrine):

  $data = $entityRepository->getMonthlyStats();
  $chart->series([['data' => array_column($data, 'value')]]);
  

Reusable Components

• Create a Chart Builder Service:

  // src/Service/ChartBuilder.php
  class ChartBuilder {
      public function buildSalesChart(array $data): Highchart {
          $chart = new Highchart();
          $chart->chart->type('column')
                 ->title('Sales Overview');
          $chart->series([['name' => 'Revenue', 'data' => $data]]);
          return $chart;
      }
  }
  

• Use in Controller:

  $chart = $this->get('chart_builder')->buildSalesChart($salesData);
  return $this->render('dashboard.html.twig', ['chart' => $chart]);
  

Event-Driven Updates

• AJAX Data Fetching:

  // Frontend JS
  $.get('/api/sales-data', function(data) {
      Highcharts.chart('container', {
          series: [{
              data: data
          }]
      });
  });
  

  Pair with Symfony’s JsonResponse:

  return new JsonResponse($data);
  

Theming

• Global Theme (via Twig):

  {% set highchartsOptions = {
      'lang': {
          'noData': 'Loading data...'
      },
      'colors': ['#3f51b5', '#ff5722']
  } %}
  {{ render_highchart(chart, highchartsOptions) }}
  

Gotchas and Tips

Pitfalls

1. Twig vs. PHP Configuration:

   • Issue: Mixing Twig and PHP config can lead to unexpected behavior.
   • Fix: Prefer PHP objects (Highchart, Series) for complex charts; use Twig for simple overrides.
   • Example:

     {# Avoid this for complex charts #}
     {{ render_highchart({
         'series': [{'data': complex_data_logic_here}]
     }) }}
     

2. Highcharts JS Version Mismatch:

   • Issue: Bundle assumes Highcharts JS is loaded in your layout.
   • Fix: Include the script in your base template:

     <script src="https://code.highcharts.com/highcharts.js"></script>
     

3. Caching Static Charts:

   • Issue: Dynamic data in "static" charts can cause stale renders.
   • Fix: Use cache: false in Twig or clear cache when data changes:

     {{ render_highchart(chart, {'cache': false}) }}
     

Debugging Tips

1. Inspect Generated JSON:

   • Use browser dev tools to check the data-highcharts-options attribute on rendered <div> elements.
   • Example:

     console.log(document.querySelector('[data-highcharts-options]').dataset.highchartsOptions);
     

2. Validate Highcharts API:

   • Use the Highcharts API Validator to check configuration syntax.

3. Symfony Debug Toolbar:

   • Enable ObHighchartsBundle's profiler data (if supported) to inspect chart generation.

Extension Points

1. Custom Series Types:

   • Extend Ob\HighchartsBundle\Highcharts\Series for domain-specific logic:

     class CustomSeries extends Series {
         public function setCustomProperty($key, $value) {
             $this->options[$key] = $value;
         }
     }
     

2. Override Twig Rendering:

   • Create a custom Twig extension:

     // src/Twig/Extension/CustomHighchartsExtension.php
     class CustomHighchartsExtension extends \Twig_Extension {
         public function getFunctions() {
             return [
                 new \Twig_SimpleFunction('render_custom_chart', [$this, 'renderChart']),
             ];
         }
     }
     

3. Integrate with Doctrine:

   • Use Ob\HighchartsBundle\Highcharts\Data\DataProviderInterface to fetch data from repositories:

     $chart->series([new Series([
         'data' => $this->getDoctrine()->getRepository(MyEntity::class)->getChartData()
     ])]);
     

Performance Quirks

1. Large Datasets:

   • Use turboThreshold for performance:

     $chart->chart->turboThreshold(1000);
     

   • Note: Highcharts may switch to "turbo mode" for datasets > threshold.

2. Lazy Loading:

   • For AJAX-heavy apps, preload Highcharts JS asynchronously:

     {# app.js #}
     require(['https://code.highcharts.com/highcharts.js'], function(Highcharts) {
         // Initialize charts
     });
     

Configuration Tips

1. Default Options:

   • Set global defaults in config/packages/ob_highcharts.yaml:

     ob_highcharts:
         default_options:
             chart:
                 type: 'line'
             plotOptions:
                 series:
                     animation: false
     

2. Localization:

   • Override Highcharts language settings:

     $chart->lang->noData('No data available for this period.');