Getting Started

Minimal Setup

Install the Bundle

composer require ob/highcharts-bundle

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

Enable Twig Extensions Ensure Twig is configured in config/packages/twig.yaml:

twig:
    extensions:
        - Ob\HighchartsBundle\Twig\HighchartsExtension

First Chart in Twig Create a basic line chart in a Twig template:

{{ highcharts_chart({
    'title': {'text': 'Basic Chart'},
    'series': [{
        'name': 'Data',
        'data': [1, 2, 3, 4, 5]
    }]
}) }}

Verify Highcharts JS Include the Highcharts library in your base template (check Resources/doc/installation.md for CDN/self-hosted options):
```
<script src="https://code.highcharts.com/highcharts.js"></script>
```

Implementation Patterns

Common Workflows

1. Dynamic Data Binding

Use PHP arrays to bind data from controllers:

// src/Controller/ChartController.php
public function salesChart()
{
    $data = [10, 20, 30, 40, 50];
    return $this->render('chart/sales.html.twig', [
        'chartData' => $data,
    ]);
}

{{ highcharts_chart({
    'series': [{
        'data': chartData
    }]
}) }}

2. Reusable Chart Components

Create a base chart template (_chart.html.twig):

{% macro chart(type, data, options={}) %}
    {{ highcharts_chart({
        'chart': {'type': type},
        'series': [{
            'data': data
        }],
        **options
    }) }}
{% endmacro %}

Usage:

{{ _self.chart('column', [1, 2, 3], {
    'title': {'text': 'Reusable Chart'}
}) }}

3. API-Driven Charts

Fetch data from an API and render dynamically:

// Controller
public function apiChart()
{
    $response = $this->httpClient->request('GET', 'https://api.example.com/data');
    $data = json_decode($response->getContent(), true);
    return $this->render('chart/api.html.twig', ['data' => $data]);
}

{{ highcharts_chart({
    'series': data.series,
    'xAxis': {'categories': data.categories}
}) }}

4. Configuration via Services

Define chart configurations in services (config/services.yaml):

services:
    App\Chart\Configurator:
        arguments:
            $defaultOptions: { 'chart': { 'type': 'line' } }

Inject and extend in controllers:

public function __construct(private Configurator $configurator) {}

public function customChart()
{
    $options = $this->configurator->getOptions();
    $options['series'] = [[ 'data' => [1, 2, 3] ]];
    return $this->render('chart/custom.html.twig', ['options' => $options]);
}

Integration Tips

Laravel-Specific Adaptations

Symfony vs. Laravel Compatibility
- Use Symfony\Bridge\Twig\Extension\ProfilerExtension for debugging in Laravel (if using Symfony components).
- For Laravel’s Blade, wrap Twig templates in @twig directives or use a bridge like laravel-twig.
Asset Management
- Publish bundle assets:
```
php bin/console assets:install
```
- Use Laravel Mix/Vite to bundle Highcharts with your JS:
```
// resources/js/app.js
import 'highcharts';
```

Routing and Controllers

Leverage Laravel’s route model binding for dynamic chart data:

Route::get('/chart/{user}', [ChartController::class, 'userChart']);

public function userChart(User $user)
{
    return view('chart.user', ['data' => $user->stats]);
}

Performance Optimization

Lazy-Loading: Load Highcharts only when needed:

{% if showChart %}
    <script src="https://code.highcharts.com/highcharts.js"></script>
    {{ highcharts_chart(...) }}
{% endif %}

Caching: Cache rendered chart HTML (Laravel’s Cache facade):

$cachedChart = Cache::remember("chart_{$key}", now()->addHours(1), function() {
    return view('chart.template', ['data' => $data])->render();
});

Gotchas and Tips

Pitfalls

1. Twig vs. Blade Conflicts

Issue: Twig functions (e.g., highcharts_chart) won’t work in Blade templates by default.

Fix: Use a Twig bridge or inline Twig in Blade:

@twig
    {{ highcharts_chart(...) }}
@endtwig

2. Highcharts JS Loading Order

Issue: Charts may fail if Highcharts JS loads after the DOM is rendered.

Fix: Defer loading or use document.ready:

<script>
    document.addEventListener('DOMContentLoaded', function() {
        // Highcharts will initialize here
    });
</script>

3. Configuration Merging

Issue: Overwriting default options unintentionally.

Fix: Use array_merge or the bundle’s mergeOptions helper:

{{ highcharts_chart({
    **defaultOptions,
    'series': customSeries
}) }}

4. Data Serialization

Issue: Complex PHP objects may not serialize to JSON correctly.

Fix: Explicitly cast data to arrays:

$data = json_decode(json_encode($complexObject), true);

Debugging

1. Validate JSON Output

Check the rendered HTML for malformed JSON:
```
{{ dump(highcharts_chart(...))|raw }}
```
Use browser dev tools to inspect the highcharts object.

2. Highcharts Console Errors

Enable Highcharts debug mode:

<script src="https://code.highcharts.com/highcharts.js"></script>
<script src="https://code.highcharts.com/modules/exporting.js"></script>
<script>
    Highcharts.setOptions({ debug: true });
</script>

3. Twig Debugging

Enable Twig strict checks in config/packages/twig.yaml:
```
twig:
    strict_variables: true
```

Extension Points

1. Custom Chart Types

Extend the bundle by creating a custom Twig function:

// src/Twig/Extension/CustomHighchartsExtension.php
class CustomHighchartsExtension extends \Twig\Extension\AbstractExtension
{
    public function getFunctions()
    {
        return [
            new \Twig\TwigFunction('custom_chart', [$this, 'renderCustomChart']),
        ];
    }

    public function renderCustomChart(array $options)
    {
        // Custom logic
        return $this->renderChart($options);
    }
}

services:
    App\Twig\Extension\CustomHighchartsExtension:
        tags: ['twig.extension']

2. Dynamic Themes

Override themes via a service:

services:
    Ob\HighchartsBundle\Highcharts\Highcharts:
        arguments:
            $defaultOptions:
                'chart': { 'style': { 'fontFamily': 'YourFont' } }

3. Event Handlers

Attach JavaScript events via Twig:

{{ highcharts_chart({
    'chart': {
        'events': {
            'load': 'function() { console.log("Chart loaded"); }'
        }
    }
}) }}

Configuration Quirks

1. `chart` vs. `highcharts` Object

Gotcha: Highcharts expects a highcharts object, but the bundle uses chart by default.

Fix: Explicitly set the root object:

{{ highcharts_chart({
    'highcharts': {
        'chart': { 'type': 'pie' },
        'series': [...]
    }
}) }}

2. Localization

Set locale in PHP:

$options = [
    'lang' => [
        'decimalPoint' => ',',
        'thousandsSep' => ' ',

Highcharts Bundle Laravel Package