Axis Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require epessine/axis
   npm install chart.js apexcharts highcharts  # Choose one or all based on needs
   npm run dev
   

2. Publish Assets (if needed):

   php artisan vendor:publish --provider="Axis\AxisServiceProvider"
   

3. First Chart (Chart.js):

   // app/Http/Controllers/ChartController.php
   use Axis\Chart;
   
   public function showChart()
   {
       $chart = Chart::chartjs()
           ->bar()
           ->labels(['Jan', 'Feb', 'Mar'])
           ->series('Sales', [10, 20, 30]);
   
       return view('charts.example', compact('chart'));
   }
   

4. Render in Blade:

   <!-- resources/views/charts/example.blade.php -->
   <div>{{ $chart }}</div>
   

First Use Case: Dashboard Metrics

Create a simple bar chart for monthly revenue:

$chart = Chart::chartjs()
    ->bar()
    ->title('Monthly Revenue')
    ->labels(['Jan', 'Feb', 'Mar', 'Apr'])
    ->series('Revenue ($)', [5000, 7500, 9000, 12000])
    ->options(['plugins' => ['title' => ['display' => true]]]);

Implementation Patterns

Core Workflows

1. Builder Pattern: Chain methods for fluent configuration:

   Chart::chartjs()
       ->type('line')          // Set chart type
       ->labels($data['months']) // Dynamic data
       ->series('Metric', $data['values'])
       ->options($customOptions);
   

2. Livewire Integration:

   use Axis\Attributes\Axis;
   
   class Dashboard extends Component {
       #[Axis]
       public function revenueChart() {
           return Chart::chartjs()
               ->line()
               ->labels($this->months)
               ->series('Revenue', $this->values);
       }
   }
   

3. Dynamic Data Binding:

   // Controller
   $chart = Chart::apex()
       ->area()
       ->labels($this->getMonths())
       ->series('Users', $this->getUserCounts());
   
   // Livewire
   public function updatedMonths() {
       $this->chart->update(); // Force JS-side refresh
   }
   

Integration Tips

• Asset Management: Use Laravel Mix/Vite to bundle chart libraries. Example resources/js/app.js:

  import Chart from 'chart.js/auto';
  import apexcharts from 'apexcharts';
  import Highcharts from 'highcharts';
  

• Blade Components: Encapsulate charts in reusable components:

  @component('charts.base', ['chart' => $chart])
      @slot('title') Monthly Sales @endslot
  @endcomponent
  

• API-Driven Charts: Fetch data via API and render:

  $response = Http::get('api/metrics');
  $chart = Chart::highcharts()
      ->spline()
      ->series($response['data']);
  

Gotchas and Tips

Common Pitfalls

1. Missing JS Dependencies:

   • Ensure chart.js, apexcharts, or highcharts are included in your build.
   • Debug with browser console: Uncaught ReferenceError: Chart is not defined.

2. Livewire State Mismatch:

   • Forgetting to call $chart->update() after modifying properties.
   • Fix: Use #[Axis] attribute and trigger updates manually.

3. Script Helper Quirks:

   • Multi-line JS in Script::from() requires proper heredoc syntax:

     Script::from(<<<'JS'
         function(ctx) {
             return ctx.dataIndex % 2 === 0 ? 'red' : 'blue';
         }
     JS)
     

4. Highcharts License:

   • Free tier has limitations. For commercial use, purchase a license and configure:

     Chart::highcharts()->license('your-license-key');
     

Debugging Tips

• Inspect Generated HTML:

  <pre>{{ $chart->toHtml() }}</pre>
  

  Reveals raw JS config for troubleshooting.

• Console Logging: Use Script::from() to log data:

  Script::from('console.log("Debug:", data);')
  

Extension Points

1. Custom Libraries: Extend the base Chart class:

   namespace Axis\Charts;
   
   class CustomChart extends Chart {
       public function __construct() {
           $this->library = 'custom';
           $this->config = [...];
       }
   }
   

2. Override Defaults: Publish config and modify:

   php artisan vendor:publish --tag=axis-config
   

   Edit config/axis.php to change default chart options.

3. Livewire Interactions: Access the JS chart instance via $chart magic property:

   public function destroyChart() {
       $this->chart->destroy(); // Calls JS: chart.destroy();
   }
   

Performance Tips

• Lazy Loading: Load chart libraries dynamically:

  @if(request()->wantsJson() || request()->ajax())
      <script src="{{ mix('js/chart.js') }}"></script>
  @endif
  

• Memoization: Cache chart instances in Livewire:

  public function chart() {
      return $this->chartInstance ??= Chart::chartjs()->...;
  }