Laravel Highcharts Laravel Package

Getting Started

Minimal Steps to First Chart

1. Install the package:

   composer require bernskioldmedia/laravel-highcharts
   

2. Import the Alpine component in resources/js/app.js:

   import Chart from '../../vendor/bernskioldmedia/laravel-highcharts/resources/js/chart';
   Alpine.data('highchartsChart', Chart);
   

3. Create a Livewire component (e.g., ChartComponent.php):

   use BernskioldMedia\LaravelHighcharts\Highcharts;
   
   public function render()
   {
       return view('livewire.chart-component');
   }
   
   public function chartData()
   {
       return Highcharts::new()
           ->title('Basic Chart')
           ->series([
               Highcharts::series()->name('Data')->data([1, 2, 3, 4, 5])
           ]);
   }
   

4. Render the chart in a Blade view (chart-component.blade.php):

   <div x-data="highchartsChart" x-init="initChart(@this->chartData())"></div>
   

First Use Case: Simple Line Chart

Use this pattern for quick, dynamic charts without manual JavaScript:

// In a Livewire component
public function chartData()
{
    return Highcharts::new()
        ->title('Monthly Sales')
        ->xAxis(['categories' => ['Jan', 'Feb', 'Mar']])
        ->series([
            Highcharts::series()
                ->name('Sales')
                ->type('line')
                ->data([10, 20, 15])
        ]);
}

Implementation Patterns

Livewire Integration Workflow

1. Data Binding: Use chartData() to return a Highcharts builder instance. The method is called automatically by the Alpine component.

   public function chartData()
   {
       return Highcharts::new()
           ->series($this->fetchSeriesData());
   }
   

2. Dynamic Updates: Trigger updates via Livewire events (e.g., emit('refreshChart')) and re-render the component:

   public function updateChart()
   {
       $this->emit('refreshChart');
   }
   

3. Reusable Components: Extend the base Highcharts class for shared configurations:

   class AppHighcharts extends \BernskioldMedia\LaravelHighcharts\Highcharts
   {
       public function __construct()
       {
           parent::__construct();
           $this->theme('dark');
       }
   }
   

Common Chart Types

• Line/Column Charts:

  Highcharts::series()
      ->type('column')
      ->data([1, 2, 3])
  

• Pie Charts:

  Highcharts::series()
      ->type('pie')
      ->data([['name' => 'A', 'y' => 29], ['name' => 'B', 'y' => 71]])
  

• Maps:

  Highcharts::new()
      ->chart(['map' => 'countries/us/us-all'])
      ->series([
          Highcharts::series()
              ->mapData($this->getMapData())
              ->joinBy('hc-key')
      ]);
  

Performance Tips

• Lazy Load Data: Fetch chart data only when needed (e.g., via mount() or updatedProperty).
• Caching: Cache chartData() responses if data doesn’t change frequently:

  public function chartData()
  {
      return Cache::remember('chart-data', now()->addHours(1), function () {
          return Highcharts::new()->series($this->fetchData());
      });
  }
  

Gotchas and Tips

Pitfalls

1. Alpine Component Naming: The Alpine component must be named highchartsChart (case-sensitive). Rename it in app.js if needed, but update all references.

2. Highcharts JS Dependency: Ensure window.Highcharts is available. For CDN usage, add this to your Blade layout:

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

   Or bundle it via Laravel Mix/Vite.

3. Livewire 3 Compatibility: If using Livewire 3, manually bundle AlpineJS (as noted in the README). The package assumes Alpine is pre-loaded.

4. Series Data Format: Highcharts expects series data in a specific format. For example, pie charts require ['name', 'y'] pairs:

   // ❌ Wrong (will fail silently)
   Highcharts::series()->data([10, 20, 30]);
   
   // ✅ Correct
   Highcharts::series()->data([['name' => 'A', 'y' => 10], ['name' => 'B', 'y' => 20]]);
   

Debugging

• Check Console for Errors: Highcharts errors (e.g., missing window.Highcharts) often appear in the browser console. Verify the Alpine component is initialized:

  console.log(window.Alpine.data('highchartsChart')); // Should return the Chart function
  

• Validate Builder Output: Log the chartData() response to ensure it matches Highcharts’ expected format:

  dd($this->chartData()->toArray());
  

Extension Points

1. Custom Highcharts Features: Use the options() method to pass raw Highcharts configuration:

   Highcharts::new()
       ->options(['credits' => ['enabled' => false]])
       ->series([...]);
   

2. Plugin Integration: Load Highcharts plugins (e.g., boost, drilldown) via the options() method:

   Highcharts::new()
       ->options([
           'plugins' => [Highcharts::Plugin::BOOST],
           'boost' => ['useGPUTranslations' => true]
       ]);
   

3. Theming: Apply themes globally by extending the builder:

   class ThemedHighcharts extends \BernskioldMedia\LaravelHighcharts\Highcharts
   {
       public function __construct()
       {
           parent::__construct();
           $this->theme('grid');
       }
   }
   

Config Quirks

• Livewire Property Binding: If chartData() relies on Livewire properties, ensure they’re initialized in mount():

  public $chartType = 'line';
  
  public function mount()
  {
      $this->chartType = request('type', 'line');
  }
  

• Blade Escaping: The Alpine component’s x-init attribute escapes data. Use @this->chartData() (not @json($this->chartData())) to avoid double-encoding.