Laravel Dashboard Velo Tile Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-dashboard-velo-tile
   

   Ensure spatie/laravel-dashboard is installed (this package is a tile for it).

2. Register the Tile: Add the tile to your dashboard configuration in config/dashboard.php:

   'tiles' => [
       \Spatie\Dashboard\Tiles\VeloTile::class,
       // ... other tiles
   ],
   

3. First Use Case: Display real-time Velo bike availability on your dashboard. The tile fetches and renders data automatically—no manual API calls needed.

Where to Look First

• Tile Configuration: Check config/dashboard.php for tile-specific settings (e.g., API endpoints, caching).
• Documentation: Spatie Dashboard Docs for tile integration.
• Source Code: Review \Spatie\Dashboard\Tiles\VeloTile for customization hooks (e.g., modifying the API request or response parsing).

Implementation Patterns

Core Workflow

1. Data Fetching: The tile uses Spatie’s Http facade to call the Velo API. Override the getData() method in a custom tile class to modify the request:

   use Spatie\Dashboard\Tiles\VeloTile;
   
   class CustomVeloTile extends VeloTile {
       protected function getData(): array {
           $response = $this->http->get('https://api.velo.be/v2/stations', [
               'query' => ['station_id' => 123],
           ]);
           return $response->json();
       }
   }
   

2. Rendering: The tile renders data in a predefined Blade template (resources/views/vendor/dashboard/tiles/velo.blade.php). Extend this template by publishing and overriding it:

   php artisan vendor:publish --tag=dashboard-tiles
   

   Customize the view in resources/views/vendor/dashboard/tiles/velo.blade.php.

3. Integration with Dashboard:

   • Dynamic Updates: Use Laravel Echo/Pusher to refresh the tile in real-time (requires additional setup).
   • Conditional Display: Add logic in shouldBeDisplayed() to show/hide the tile based on user roles or settings:

     protected function shouldBeDisplayed(): bool {
         return auth()->user()->can('view-velo-dashboard');
     }
     

4. Caching: Leverage Laravel’s cache to reduce API calls. Configure in config/dashboard.php:

   'tiles' => [
       \Spatie\Dashboard\Tiles\VeloTile::class => [
           'cache_for' => '10 minutes', // Cache data for 10 minutes
       ],
   ],
   

Advanced Patterns

• Multi-Station Tracking: Fetch data for multiple stations and merge it in getData():

  protected function getData(): array {
      $stations = [123, 456, 789];
      $data = collect($stations)->map(fn ($id) => $this->http->get("https://api.velo.be/v2/stations/{$id}"));
      return $data->pluck('json')->all();
  }
  

• Custom Styling: Use CSS variables or inline styles in the published Blade template to match your dashboard’s theme.

• Event-Driven Updates: Listen for Velo API updates via webhooks (requires custom backend logic) and trigger tile refreshes via JavaScript:

  Echo.channel('velo-updates')
      .listen('VeloUpdated', (data) => {
          window.location.reload(); // Force tile refresh
      });
  

Gotchas and Tips

Pitfalls

1. API Rate Limiting:

   • The Velo API may throttle requests. Use caching (cache_for) aggressively or implement exponential backoff in getData().
   • Monitor API responses for 429 Too Many Requests errors and handle them gracefully.

2. Data Parsing Issues:

   • The Velo API response structure may change. Validate the response in getData():

     $response = $this->http->get('...');
     $data = $response->json();
     if (!isset($data['stations'])) {
         throw new \RuntimeException('Invalid API response format');
     }
     

3. Time Zone Mismatches:

   • Velo’s API returns timestamps in UTC. Convert to the user’s time zone in the Blade template:

     {{ $station['last_update']->setTimezone(auth()->user()->timezone) }}
     

4. Dashboard Compatibility:

   • Ensure your Laravel Dashboard version matches the tile’s requirements. Check composer.json for constraints.

Debugging Tips

1. Log API Responses: Add debug logs in getData() to inspect raw API responses:

   \Log::debug('Velo API Response:', $response->json());
   

2. Test Locally: Use Laravel’s HTTP client to mock the Velo API during development:

   $this->http->fake([
       'https://api.velo.be/v2/stations' => Http::response([
           'stations' => [['id' => 123, 'free_bikes' => 5]],
       ]),
   ]);
   

3. Check Network Requests: Use browser dev tools (Network tab) to verify the tile’s API calls and payloads.

Extension Points

1. Custom Tile Class: Extend \Spatie\Dashboard\Tiles\VeloTile to add features like:

   • Geospatial Filtering: Filter stations by proximity to a user’s location.
   • Historical Data: Store and compare bike availability over time.

2. Blade Template Hooks: Override the published Blade template to:

   • Add interactive maps (e.g., Leaflet.js) for station locations.
   • Include user-specific actions (e.g., "Reserve Bike" buttons).

3. Configuration: Expose tile settings via config/dashboard.php:

   'tiles' => [
       \Spatie\Dashboard\Tiles\VeloTile::class => [
           'default_station_id' => 123,
           'show_map' => true,
       ],
   ],
   

   Access these in your custom tile class via config('dashboard.tiles.velo').

4. Localization: Translate tile labels and messages using Laravel’s localization features:

   {{ __('dashboard::velo.free_bikes', ['count' => $station['free_bikes']]) }}
   

Pro Tips

• Performance: Lazy-load the tile’s JavaScript/CSS to improve dashboard load times. Use Laravel Mix to split assets.

• Accessibility: Ensure the tile’s Blade template adheres to WCAG standards (e.g., ARIA labels for interactive elements).

• Documentation: Add inline PHPDoc comments to your custom tile class for future maintainability:

  /**
   * Fetches Velo station data with custom query parameters.
   *
   * @return array Raw API response data.
   * @throws \RuntimeException If API response is invalid.
   */
  protected function getData(): array { ... }