Axis Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require epessine/axis
   

   Publish the config (if needed):

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

2. First Chart in a Blade View:

   @use(Axis\Axis::class)
   {{ Axis::line()->title('Sales Overview')->data([10, 20, 30]) }}
   

3. Livewire Integration:

   use Epessine\Axis\Livewire\AxisComponent;
   
   public function render()
   {
       return view('livewire.chart', [
           'chart' => Axis::line()
               ->title('Live Data')
               ->data($this->fetchData())
       ]);
   }
   

First Use Case: Quick Dashboard Metric

{{ Axis::doughnut()
    ->title('User Distribution')
    ->labels(['Active', 'Inactive'])
    ->data([75, 25])
    ->colors(['#4CAF50', '#F44336'])
}}

Implementation Patterns

Core Workflow: Data-Driven Charts

1. Fetch Data:

   $users = User::selectRaw('status, count(*) as count')
       ->groupBy('status')
       ->get();
   

2. Build Chart:

   $chart = Axis::bar()
       ->title('User Status')
       ->labels($users->pluck('status'))
       ->data($users->pluck('count'))
       ->options(['responsive' => true]);
   

3. Render:

   @livewire('dashboard', ['chart' => $chart])
   

Livewire Integration

• Dynamic Updates:

  public function updatedChartData()
  {
      $this->chart = Axis::line()
          ->data($this->fetchUpdatedData());
  }
  

• Reactive Components:

  public function render()
  {
      return view('livewire.chart', [
          'chart' => Axis::scatter()
              ->title('Real-time Metrics')
              ->data($this->getLiveData())
              ->options(['animation' => true])
      ]);
  }
  

Eloquent Integration

$chart = Axis::area()
    ->title('Monthly Revenue')
    ->labels(Carbon::parse('first day of this year')->format('M'))
    ->data(Revenue::query()
        ->selectRaw('DATE_FORMAT(created_at, "%m") as month, SUM(amount) as total')
        ->groupBy('month')
        ->pluck('total')
    );

Theming & Consistency

// Global config (config/axis.php)
'defaults' => [
    'theme' => 'dark',
    'colors' => ['#3498db', '#e74c3c', '#2ecc71', '#9b59b6'],
],

// Per-chart override
Axis::pie()->colors(['#ff9800', '#795548']);

Gotchas and Tips

Common Pitfalls

1. Livewire Hydration Issues:

   • Ensure chart data is serializable. Use ->toArray() on Eloquent collections.
   • Avoid passing complex objects directly; extract data first:

     $this->chart = Axis::line()->data($this->processData());
     

2. CSS Conflicts:

   • Axis injects its own styles. If charts appear broken:

     Axis::options(['maintainAspectRatio' => false]);
     

   • Or override globally in config/axis.php:

     'styles' => [
         'path' => 'css/axis-custom.css',
     ],
     

3. Performance with Large Datasets:

   • Use ->limit(100) or chunk queries:

     $chart = Axis::line()
         ->data(YourModel::orderBy('created_at')->limit(100)->pluck('value'));
     

Debugging Tips

• Inspect Generated HTML:

  dd(Axis::line()->data([1,2,3])->toHtml());
  

• Check Console for Errors: Axis logs warnings if required JS/CSS assets are missing.

Extension Points

1. Custom Chart Types:

   Axis::extend('myChart', function($chart) {
       $chart->type = 'myChart';
       $chart->options['custom'] = true;
   });
   // Usage: Axis::myChart()->data([...])
   

2. Asset Overrides:

   // config/axis.php
   'assets' => [
       'js' => 'path/to/custom.js',
       'css' => 'path/to/custom.css',
   ],
   

3. Livewire Component Customization:

   // app/Http/Livewire/ExtendedAxis.php
   class ExtendedAxis extends AxisComponent
   {
       public $extraOption = '';
   
       public function render()
       {
           $this->chart->options(['extra' => $this->extraOption]);
           return parent::render();
       }
   }
   

Pro Tips

• Reuse Chart Builders:

  $builder = Axis::line()->title('Reusable Chart');
  // Usage in multiple places:
  {{ $builder->data($data1) }}
  {{ $builder->data($data2) }}
  

• Conditional Rendering:

  @if($hasData)
      {{ Axis::bar()->data($data) }}
  @else
      <p>No data available</p>
  @endif
  

• Server-Side Processing: For large datasets, use ->remoteData() to fetch data via AJAX:

  Axis::line()
      ->remoteData('/api/data')
      ->options(['remoteUpdateInterval' => 5000]);