Laravel Metric Cards Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require lacodix/laravel-metric-cards
   

2. Publish assets and config:

   php artisan vendor:publish --tag=laravel-metrics-assets --tag=laravel-metric-cards-config
   

3. Verify asset publishing: Check public/vendor/laravel-metrics/dist/metrics.js exists.
4. First metric in Blade:

   <x-metric-card::value
       title="Users"
       value="{{ $userCount }}"
   />
   

First Use Case: Admin Dashboard

Create a dashboard with 3 metrics:

<div class="grid grid-cols-1 md:grid-cols-3 gap-4">
    <x-metric-card::value title="Active Users" value="{{ $activeUsers }}" />
    <x-metric-card::trend title="Revenue" value="{{ $revenue }}" trend="{{ $revenueChange }}" />
    <x-metric-card::pie title="User Distribution" :data="$userDistribution" />
</div>

Implementation Patterns

Core Workflows

1. Metric Creation Pattern

// In a controller or service
public function getMetrics()
{
    return [
        'active_users' => User::active()->count(),
        'revenue' => Order::sum('amount'),
        'user_distribution' => User::selectRaw('role, count(*) as count')
                                ->groupBy('role')
                                ->get()
                                ->toArray(),
    ];
}

2. Livewire Integration

// Create a Livewire component
php artisan make:livewire DashboardMetrics

// In DashboardMetrics.php
public function render()
{
    return view('livewire.dashboard-metrics', [
        'metrics' => $this->getMetrics(),
    ]);
}

// In dashboard-metrics.blade.php
<div class="grid grid-cols-1 md:grid-cols-3 gap-4">
    @foreach($metrics as $name => $data)
        @if($name === 'active_users')
            <x-metric-card::value title="Active Users" value="{{ $data }}" />
        @elseif($name === 'user_distribution')
            <x-metric-card::pie title="User Distribution" :data="$data" />
        @endif
    @endforeach
</div>

3. Dynamic Metric Loading

// In a controller
public function metrics()
{
    $metrics = collect([
        'users' => User::count(),
        'orders' => Order::count(),
        'revenue' => Order::sum('amount'),
    ]);

    return view('metrics.dashboard', compact('metrics'));
}

// In Blade
@foreach($metrics as $name => $value)
    <x-metric-card::value
        title="{{ ucfirst($name) }}"
        value="{{ $value }}"
        link="{{ route('metrics.details', $name) }}"
    />
@endforeach

Integration Tips

1. Caching Strategy:

   // Cache metrics for 5 minutes
   $metrics = Cache::remember('dashboard_metrics', 300, function() {
       return [
           'users' => User::count(),
           'revenue' => Order::sum('amount'),
       ];
   });
   

2. Queue Background Processing:

   // Dispatch metric calculation
   MetricCalculator::dispatch($metricType);
   
   // In MetricCalculator job
   public function handle()
   {
       $this->updateMetrics();
   }
   

3. Custom Metric Components:

   <!-- resources/views/vendor/metric-card/extended-value.blade.php -->
   <x-metric-card::value
       :title="$title"
       :value="$value"
       :link="$link"
       :icon="$icon"
   >
       <div class="text-sm text-gray-500">
           Last updated: {{ now()->format('H:i') }}
       </div>
   </x-metric-card::value>
   

Gotchas and Tips

Common Pitfalls

1. Asset Loading Issues:

   • Problem: Metrics not rendering due to missing JS.
   • Solution: Verify public/vendor/laravel-metrics/dist/metrics.js exists and is included in your layout:

     @stack('scripts')
     @push('scripts')
         @metricCardAssets
     @endpush
     

2. Color Overrides Not Working:

   • Problem: Custom colors in config/metric-cards.php ignored.
   • Solution: Ensure colors_plugin.force_override is true or set colors directly in metric components:

     <x-metric-card::pie
         :data="$data"
         colors="['#6c5cff', '#00c2a8']"
     />
     

3. Division by Zero in Pie Charts:

   • Problem: DivisionByZeroError when displaying pie charts.
   • Solution: Ensure your data includes at least one non-zero value or handle empty datasets:

     $data = $userDistribution->isEmpty()
         ? [['label' => 'No data', 'value' => 0]]
         : $userDistribution->toArray();
     

Debugging Tips

1. Check JavaScript Errors:

   npm run dev  # Rebuild assets locally
   

   Inspect browser console for errors related to LaravelMetrics.

2. Verify Configuration:

   // Dump current config
   dd(config('metric-cards'));
   

3. Inspect Metric Data:

   @dump($metricData)
   

Extension Points

1. Custom Metric Types: Create a new metric component in resources/views/vendor/metric-card/custom.blade.php:

   <div class="metric-card">
       <div class="title">{{ $title }}</div>
       <div class="value">{{ $value }}</div>
       <!-- Custom content -->
       @if($hasTrend)
           <div class="trend {{ $trendClass }}">
               {{ $trend }}%
           </div>
       @endif
   </div>
   

2. Override Default Styling: Publish views and modify:

   php artisan vendor:publish --tag=laravel-metric-cards-views
   

3. Add New Chart Types: Extend the JavaScript bundle by modifying resources/js/metrics.js and rebuilding:

   npm ci
   npm run build
   

Performance Considerations

1. Avoid N+1 Queries:

   // Bad
   $metrics = [
       'users' => User::count(),
       'orders' => Order::count(),
   ];
   
   // Good
   $counts = DB::table('users')->count() . ',' . DB::table('orders')->count();
   $metrics = explode(',', $counts);
   

2. Lazy Load Metrics:

   @if(request()->wantsJson() || request()->has('metrics'))
       @include('metrics.partial', ['metrics' => $metrics])
   @endif
   

3. Use Query Caching:

   $metrics = Cache::rememberForever('app_metrics', function() {
       return [
           'users' => User::count(),
           'revenue' => Order::sum('amount'),
       ];
   });