Laravel Metric Cards Laravel Package

## Getting Started
Install via Composer:
```bash
composer require lacodix/laravel-metric-cards

Publish the package config (if needed):

php artisan vendor:publish --provider="Lacodix\MetricCards\MetricCardsServiceProvider"

First Use Case: Display a basic metric card in a Blade template:

@metricCard('users', 'Total Users', 1500)

Key files to inspect:

• config/metric-cards.php (configuration)
• app/Providers/MetricCardsServiceProvider.php (service binding)
• resources/views/vendor/metric-cards/ (default templates)

Implementation Patterns

Core Workflow

1. Define Metrics: Register metrics in config/metric-cards.php or via service provider:

   MetricCards::register('users', function () {
       return User::count();
   });
   

2. Blade Integration: Use @metricCard directive with optional parameters:

   @metricCard('users', 'Active Users', 1500, ['icon' => 'users', 'color' => 'green'])
   

3. Dynamic Values: Fetch real-time data via closures or cached queries.

Advanced Patterns

• Container Queries: Leverage the new v0.10.0 feature to fetch multiple metrics at once:

  $metrics = MetricCards::query(['users', 'orders', 'revenue']);
  

• Invisible Initial Values: Use the new allow_initial_invisible config to preload metrics without rendering them immediately:

  'allow_initial_invisible' => true,
  

  Then render later via JavaScript or conditional Blade logic.

Integration Tips

• Cache Optimization: Cache metric queries in your provider:

  MetricCards::register('users', function () {
      return Cache::remember('metric-users', now()->addHours(1), fn() => User::count());
  });
  

• Custom Templates: Override default views in resources/views/vendor/metric-cards/.
• API Endpoints: Expose metrics via API routes:

  Route::get('/metrics', [MetricCardsController::class, 'index']);
  

Gotchas and Tips

Pitfalls

• Closure Scope: Ensure closures in register() have access to required models/services (e.g., inject User via constructor or use app binding).
• Template Conflicts: If overriding views, clear cached views (php artisan view:clear).
• Performance: Avoid heavy queries in metric definitions—cache aggressively or use lightweight aggregations.

Debugging

• Missing Metrics: Check if the metric is registered in the config or provider. Use:

  dd(MetricCards::getRegisteredMetrics());
  

• Blade Directive Errors: Ensure @metricCard is used within a Blade template context (not in plain PHP files).
• Container Query Issues: Verify all queried metrics exist in the registered list.

Extension Points

• New Metric Types: Extend the package by creating custom metric classes:

  class CustomMetric extends MetricCards\Metric
  {
      public function render()
      {
          return view('custom.metric', ['value' => $this->value]);
      }
  }
  

  Register via:

  MetricCards::extend('custom', CustomMetric::class);
  

• Event Hooks: Listen for metric.calculated events to modify values dynamically:

  event(new MetricCalculated('users', 1500));
  

• Config Quirks: The allow_initial_invisible flag (v0.10.0) requires explicit rendering via:

  @if(MetricCards::has('users'))
      @metricCard('users')
  @endif