Laravel Dashboard Coffee Tile Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-dashboard-coffee-tile
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Spatie\DashboardCoffeeTile\DashboardCoffeeTileServiceProvider"
   

2. Register the Tile: Add the tile to your Laravel Dashboard configuration (e.g., config/dashboard.php):

   'tiles' => [
       \Spatie\DashboardCoffeeTile\DashboardCoffeeTile::class,
   ],
   

3. First Use Case:

   • Ensure the Python listener script is running on a Raspberry Pi or similar device to capture coffee machine sounds.
   • Verify the listener is pushing data to your Laravel app (e.g., via HTTP requests to a custom endpoint or database updates).

Implementation Patterns

Workflow Integration

1. Data Collection:

   • Configure the Python listener to send coffee brewing events (e.g., cups brewed, machine status) to your Laravel app. Use a dedicated endpoint (e.g., POST /api/coffee-events) or a queue job for async processing.
   • Example endpoint:

     // routes/api.php
     Route::post('/coffee-events', [CoffeeEventController::class, 'store']);
     

2. Dashboard Tile Customization:

   • Extend the tile’s logic by overriding its methods in a custom class:

     namespace App\Dashboard;
     
     use Spatie\DashboardCoffeeTile\DashboardCoffeeTile as BaseTile;
     
     class CustomCoffeeTile extends BaseTile
     {
         public function getCoffeeStats()
         {
             // Custom logic to fetch/process data
             return [
                 'totalCups' => CoffeeEvent::count(),
                 'todayCups' => CoffeeEvent::today()->count(),
             ];
         }
     }
     

   • Register the custom tile in config/dashboard.php.

3. Real-Time Updates:

   • Use Laravel Echo/Pusher to push coffee stats updates to the dashboard in real-time. Trigger updates via events:

     // Event: CoffeeEventCreated
     class CoffeeEventCreated implements ShouldBroadcast
     {
         public function broadcastOn()
         {
             return new Channel('coffee-stats');
         }
     }
     

4. Testing:

   • Mock the Python listener’s HTTP requests in PHPUnit:

     $response = $this->postJson('/api/coffee-events', ['cups' => 2]);
     $response->assertCreated();
     

Gotchas and Tips

Pitfalls

1. Listener Dependency:

   • The tile relies on an external Python script. Ensure the listener is always running and connected to the network. Monitor its logs for errors (e.g., sound detection failures).
   • Tip: Set up a health check endpoint (/api/coffee-listener/health) to verify the listener’s status.

2. Data Persistence:

   • The package assumes coffee events are stored in a database (e.g., coffee_events table). If not, create a migration:

     php artisan make:migration create_coffee_events_table
     

     Schema::create('coffee_events', function (Blueprint $table) {
         $table->id();
         $table->integer('cups');
         $table->timestamps();
     });
     

3. Rate Limiting:

   • The Python listener may send rapid-fire requests. Protect your endpoint with rate limiting:

     Route::middleware(['throttle:60,1'])->post('/api/coffee-events', ...);
     

Debugging

1. Logs:

   • Enable debug logging for the tile in config/dashboard-coffee-tile.php:

     'log_events' => env('COFFEE_TILE_LOG_EVENTS', false),
     

   • Check Laravel logs (storage/logs/laravel.log) for listener request failures.

2. Network Issues:

   • If the listener fails to connect, verify:
     • Firewall rules allow traffic on the listener’s port.
     • The Raspberry Pi has a static IP or proper DNS resolution.

Extension Points

1. Custom Metrics:

   • Add new metrics to the tile by extending getCoffeeStats():

     public function getCoffeeStats()
     {
         return [
             'totalCups' => CoffeeEvent::count(),
             'avgCupsPerHour' => CoffeeEvent::avgCupsPerHour(), // Custom query
         ];
     }
     

2. Visual Customization:

   • Override the tile’s Blade view (resources/views/vendor/dashboard-coffee-tile/tile.blade.php) to change colors, charts, or layout.

3. Multi-Machine Support:

   • Track multiple coffee machines by adding a machine_id to coffee_events and filtering in getCoffeeStats():

     CoffeeEvent::where('machine_id', $machineId)->count();