Getting Started

Minimal Steps to First Use

Install the Package
```
composer require spatie/laravel-dashboard-belgian-trains-tile
```
Ensure laravel-dashboard is installed (v4+ recommended).
Publish Configuration (if needed)
```
php artisan vendor:publish --provider="Spatie\Dashboard\DashboardServiceProvider" --tag="config"
```
Check config/dashboard.php for tile-specific settings (e.g., API keys, default station pairs).

Register the Tile Add the tile to your dashboard in a controller or service:

use Spatie\Dashboard\Dashboard;
use Spatie\Dashboard\Tiles\BelgianTrainsTile;

public function dashboard()
{
    return Dashboard::create()
        ->tile(BelgianTrainsTile::class, 'Train Connections');
}

Configure API Credentials Set NMBS/SNCB API credentials in .env (if required):
```
NMBS_API_KEY=your_api_key_here
NMBS_API_SECRET=your_secret_here
```
Test the Tile Visit your dashboard route (e.g., /dashboard). The tile should display Belgian train connections in the app’s timezone (verified in 4.0.2).

First Use Case: Displaying Real-Time Train Status

Scenario: Show live train departures from Brussels to Antwerp for a logistics dashboard. Implementation:

Override the tile’s default stations in a custom class:

namespace App\Dashboard\Tiles;

use Spatie\Dashboard\Tiles\BelgianTrainsTile;

class CustomBelgianTrainsTile extends BelgianTrainsTile
{
    public function __construct()
    {
        parent::__construct();
        $this->fromStation = 'Brussels';
        $this->toStation = 'Antwerp';
    }
}

Dashboard::create()->tile(CustomBelgianTrainsTile::class, 'Brussels → Antwerp Trains');

Verify Output: Ensure times render in the app’s timezone (e.g., config/app.php timezone setting).

Where to Look First

Documentation: Spatie Laravel Dashboard Docs (covers tile registration and Livewire integration).
Source Code: BelgianTrainsTile.php (key methods: render(), getTrainData()).
Changelog: Focus on 4.0.2 for the timezone fix and 2.1.0 for locale support.

Implementation Patterns

Core Workflows

1. Tile Registration and Customization

Default Usage: Register the tile with default stations (e.g., Brussels → Brussels-North).
```
Dashboard::create()->tile(BelgianTrainsTile::class, 'Train Status');
```

Custom Stations: Extend the tile to hardcode or dynamically set stations:

class CustomTile extends BelgianTrainsTile
{
    public function __construct()
    {
        $this->fromStation = request('from') ?? 'Brussels';
        $this->toStation = request('to') ?? 'Ghent';
    }
}

Dynamic Data: Fetch stations from a database or user input:

$this->fromStation = User::find(auth()->id())->preferredStation;

2. API Integration

Default Behavior: Uses NMBS/SNCB API via getTrainData() (abstracted in the tile).

Custom API Logic: Override getTrainData() to:

Add authentication headers.

Cache responses (e.g., Redis):

public function getTrainData()
{
    $cacheKey = "trains_{$this->fromStation}_{$this->toStation}";
    return cache()->remember($cacheKey, now()->addMinutes(15), function () {
        return Http::get('https://api.sncb.be/...', [
            'headers' => ['Authorization' => 'Bearer ' . config('nmbs.api_key')],
        ])->json();
    });
}

Error Handling: Gracefully degrade on API failures:

try {
    $data = $this->getTrainData();
} catch (\Exception $e) {
    return view('tiles.belgian-trains::error', ['error' => $e->getMessage()]);
}

3. Timezone Management

Default: Renders times in the app’s timezone (fixed in 4.0.2).

Override Timezone: Force a specific timezone (e.g., for Brussels):

public function render()
{
    Carbon::setDefaultTimezone('Europe/Brussels');
    return parent::render();
}

User-Specific Timezones: Respect user preferences:

Carbon::setDefaultTimezone(auth()->user()->timezone ?? config('app.timezone'));

4. Localization

Default: Supports Belgian Dutch/French (added in 2.1.0).

Custom Locales: Extend the tile to support additional languages:

public function getLocale()
{
    return app()->getLocale() === 'fr' ? 'fr' : 'nl';
}

Integration Tips

Laravel Dashboard Integration

Tile Placement: Use Dashboard::create()->row() to group tiles:

Dashboard::create()
    ->row()
        ->tile(BelgianTrainsTile::class, 'Trains')
        ->tile(WeatherTile::class, 'Weather')
    ->row()
        ->tile(NewsTile::class, 'Updates');

Permissions: Restrict tile visibility via middleware:

if (auth()->user()->can('view_dashboard')) {
    return Dashboard::create()->tile(BelgianTrainsTile::class);
}

Livewire Integration

Real-Time Updates: The tile uses Livewire for dynamic data. To refresh manually:
```
public function refreshTrains()
{
    $this->dispatch('refresh-trains');
}
```

Custom Events: Listen for train updates in your dashboard:

window.addEventListener('refresh-trains', () => {
    Livewire.emit('refreshBelgianTrainsTile');
});

Styling and Theming

Tailwind Overrides: Publish the tile’s views and customize:
```
php artisan vendor:publish --tag="belgian-trains-views"
```
Modify resources/views/vendor/belgian-trains/tile.blade.php.

Dark Mode: Ensure compatibility with Laravel Dashboard’s dark mode:

public function getDarkModeClass()
{
    return config('dashboard.dark_mode') ? 'dark:bg-gray-800' : '';
}

Gotchas and Tips

Pitfalls

1. Timezone Bugs (Pre-4.0.2)

Issue: Before 4.0.2, times rendered in UTC. Verify your Laravel app’s timezone (config/app.php) matches user expectations.

Fix: Upgrade to 4.0.2+ and test with:

Carbon::now()->timezone('Europe/Brussels')->format('H:i');

Debugging: Check the tile’s render() method for timezone overrides.

2. NMBS API Limitations

Rate Limits: NMBS may throttle requests. Implement caching:

return cache()->remember("trains_{$this->fromStation}", now()->addMinutes(5), function () {
    return Http::get('...')->json();
});

Authentication: Ensure API keys are secure (use .env and Laravel’s config()).
Data Scope: The tile fetches departures only. For arrivals or historical data, extend getTrainData().

3. Livewire Version Conflicts

Issue: The tile supports Livewire 2/3 (updated in 2.0.0 and 3.0.0). Conflicts may arise if your project uses an unsupported version.

Fix: Align versions:

composer require livewire/livewire:^3.0

Debugging: Check for LivewireComponent errors in browser console.

4. Station Name Mismatches

Issue: NMBS station codes may differ from user-friendly names (e.g., BRU vs. Brussels-Central).

Fix: Map codes to names in a config file:

'station_mappings' => [
    'BRU' => 'Brussels-Central',
    'ANT' => 'Ant

Laravel Dashboard Belgian Trains Tile Laravel Package