Laravel Dashboard Belgian Trains Tile Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require spatie/laravel-dashboard-belgian-trains-tile
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Spatie\DashboardBelgianTrainsTile\DashboardBelgianTrainsTileServiceProvider"
   

2. Register the Tile Add the tile to your dashboard in app/Providers/DashboardServiceProvider.php:

   public function boot()
   {
       Dashboard::create()
           ->row()
               ->tile(\Spatie\DashboardBelgianTrainsTile\Tiles\BelgianTrainsTile::class)
               ->width(4) // Adjust width as needed
           ->endRow();
   }
   

3. First Use Case Visit your dashboard (/dashboard). The tile will display real-time Belgian train connections (e.g., departure/arrival times for a predefined station). Defaults to Brussels Central unless configured otherwise.

Implementation Patterns

Core Workflows

1. Customizing Station Data Override the default station via config (config/dashboard-belgian-trains-tile.php):

   'station' => 'ANTW', // Antwerp Central
   

   Or dynamically in the tile class:

   public function getStationCode(): string
   {
       return request('station', config('dashboard-belgian-trains-tile.station'));
   }
   

2. Integration with API Responses The tile fetches data from the NMBS API. Cache responses for 5 minutes (default) to avoid rate limits:

   // Override cache duration in config
   'cache_minutes' => 10,
   

3. Styling and Layout Extend the tile’s Blade template (resources/views/vendor/dashboard-belgian-trains-tile/tile.blade.php) to:

   • Add custom CSS classes.
   • Modify the display of train statuses (e.g., highlight delays).
   • Include additional metadata (e.g., line colors).

4. Conditional Rendering Disable the tile based on user roles or time (e.g., weekends):

   public function shouldRender(): bool
   {
       return auth()->user()->can('view-trains') && now()->dayOfWeek !== \Carbon\Carbon::SUNDAY;
   }
   

5. Event-Driven Updates Use Laravel events to refresh the tile dynamically (e.g., after a user action):

   event(new \Spatie\DashboardBelgianTrainsTile\Events\RefreshTrainsTile);
   

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The NMBS API has strict rate limits. Exceeding them may return 429 errors.
   • Fix: Increase cache_minutes or implement a fallback (e.g., static data) in handle():

     try {
         return $this->fetchTrains();
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         return view('dashboard-belgian-trains-tile::fallback', ['error' => 'API unavailable']);
     }
     

2. Station Code Validation

   • Invalid station codes (e.g., BRUX) return empty data.
   • Fix: Validate in getStationCode():

     $validStations = ['BRUX', 'ANTW', 'GNT']; // Add your list
     if (!in_array($station, $validStations)) {
         throw new \InvalidArgumentException("Invalid station code.");
     }
     

3. Time Zone Mismatches

   • The API returns times in UTC. Convert to the user’s timezone in the Blade template:

     {{ $train->departure->setTimezone(auth()->user()->timezone)->format('H:i') }}
     

4. Dashboard Compatibility

   • Ensure your Laravel Dashboard version matches the tile’s requirements (check composer.json).
   • Fix: Pin the version in composer.json:

     "spatie/laravel-dashboard": "^2.0"
     

Tips

1. Local Testing Mock the API response for development:

   // In a test or service provider
   \Spatie\DashboardBelgianTrainsTile\BelgianTrainsTile::shouldReceive('fetchTrains')
       ->andReturn([/* Mock data */]);
   

2. Accessibility

   • Add ARIA labels to the tile’s Blade template for screen readers:

     <div role="region" aria-label="Belgian train connections for {{ $station }}">
     

3. Internationalization

   • Localize train statuses (e.g., "Delayed" → "Vertraagd") by extending the tile’s language lines:

     // config/app.php
     'dashboard-belgian-trains-tile' => [
         'lang' => 'nl',
     ];
     

4. Performance

   • Lazy-load the tile if it’s not critical:

     public function shouldLazyLoad(): bool
     {
         return true;
     }
     

5. Extending Functionality

   • Add a search feature to dynamically change stations:

     <input type="text" wire:model="station" placeholder="Enter station code">
     

     Update the tile class to handle the live wire model:

     public $station = 'BRUX';
     

6. Logging

   • Log API failures for debugging:

     catch (\Exception $e) {
         \Log::error("Belgian Trains API failed: {$e->getMessage()}");
         return view('...')->with('error', 'Service unavailable');
     }