Charts Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zaimea/charts
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Zaimea\Charts\ChartsServiceProvider" --tag="config"
   

2. First Use Case: Generate a simple line chart in a Blade view:

   use Zaimea\Charts\Chart;
   
   $chart = Chart::line()
       ->title("Monthly Sales")
       ->labels(["Jan", "Feb", "Mar"])
       ->values([30, 40, 65]);
   

   Render in Blade:

   {!! $chart->render() !!}
   

3. Key Files:

   • config/charts.php (for global defaults)
   • resources/views/vendor/charts/ (custom templates)
   • app/Charts/ (custom chart classes)

Implementation Patterns

Core Workflows

1. Data-Driven Charts: Fetch data from Eloquent models or APIs, then pass to chart methods:

   $users = User::selectRaw('DATE(created_at) as date, COUNT(*) as count')
       ->groupBy('date')
       ->get();
   
   $chart = Chart::bar()
       ->title("User Signups")
       ->labels($users->pluck('date'))
       ->values($users->pluck('count'));
   

2. Dynamic Chart Types: Use a helper to switch chart types based on data:

   $chartType = request('chart_type', 'line');
   $chart = Chart::$chartType()
       ->data($data);
   

3. Reusable Chart Classes: Extend Zaimea\Charts\Chart for project-specific logic:

   namespace App\Charts;
   
   use Zaimea\Charts\Chart;
   
   class SalesChart extends Chart {
       public function __construct() {
           parent::line()
               ->title("Sales Overview")
               ->colors(['#4f46e5', '#10b981']);
       }
   }
   

4. API Integration: Return charts as JSON for SPAs:

   return response()->json([
       'chart' => Chart::pie()
           ->title("Revenue by Region")
           ->data($regions)
           ->toArray()
   ]);
   

Integration Tips

• Laravel Mix/Webpack: Use mix.js() to load ApexCharts JS/CSS:

  mix.js('node_modules/apexcharts/dist/apexcharts.min.js', 'public/js');
  

• Livewire/Alpine: Bind chart updates to user interactions:

  Alpine.data('chart', () => ({
      updateChart() {
          axios.get('/api/chart-data').then(response => {
              this.$refs.chart.updateSeries(response.data);
          });
      }
  }));
  

• Caching: Cache chart configurations for static pages:

  $chart = Cache::remember("chart_{$key}", now()->addHours(1), function() {
      return Chart::line()->data($data);
  });
  

Gotchas and Tips

Common Pitfalls

1. Missing Dependencies: Ensure apexcharts JS/CSS are loaded after the chart HTML:

   {!! $chart->render() !!}
   <script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
   

2. Data Mismatch: Labels/values must match in length. Use ->empty() for zero-length datasets:

   $chart->labels($labels)->values($values)->empty();
   

3. Configuration Overrides: Global config in charts.php may conflict with per-chart settings. Use ->config() to override:

   $chart->config(['chart' => ['type' => 'bar']]);
   

4. Blade Escaping: Use {{ $chart->render() }} instead of !! if chart data contains user input to prevent XSS.

Debugging Tips

• Inspect Rendered HTML: Check the data-config attribute for the final ApexCharts config.
• Console Errors: Enable ApexCharts debug mode:

  $chart->config(['chart' => ['events' => ['click' => 'console.log("Clicked")']]]);
  

• Default Values: Reset to defaults with:

  $chart->reset();
  

Extension Points

1. Custom Templates: Override Blade templates in resources/views/vendor/charts/chart.blade.php:

   <div class="custom-chart-container">
       {!! $chart->script !!}
   </div>
   

2. Plugin Support: Register ApexCharts plugins via config:

   'plugins' => [
       'Zaimea\Charts\Plugins\ExportPlugin',
   ],
   

3. Theming: Use CSS variables for dynamic theming:

   $chart->config([
       'theme' => [
           '--apex-primary' => '#3b82f6',
       ]
   ]);
   

4. Server-Side Rendering: For headless environments, use ->toArray() to generate configs:

   $chartData = Chart::pie()->data($data)->toArray();