Getting Started

Minimal Steps

Install Dependencies:
```
composer require spatie/laravel-dashboard-time-weather-tile
```
Ensure spatie/laravel-dashboard (v3.x+) is installed.

Publish Configuration (if customizing):

php artisan vendor:publish --provider="Spatie\DashboardTimeWeatherTile\DashboardTimeWeatherTileServiceProvider"

Edit .env for API keys (e.g., OPENWEATHERMAP_API_KEY).

Register the Tile: Add to your dashboard configuration (e.g., app/Providers/DashboardServiceProvider):

use Spatie\Dashboard\Dashboard;
use Spatie\DashboardTimeWeatherTile\DashboardTimeWeatherTile;

public function boot()
{
    Dashboard::create()
        ->withTile(DashboardTimeWeatherTile::new());
}

First Use Case: Display a tile showing local time (timezone-aware) and current weather (e.g., temperature, emoji) on your dashboard. Test with:
```
php artisan dashboard
```

Where to Look First

Documentation (Dashboard integration guide).
Tile Class: DashboardTimeWeatherTile (customization entry point).
Blade Template: resources/views/vendor/dashboard-time-weather-tile.blade.php (override for UI tweaks).
Config: .env (API keys) and config/dashboard-time-weather-tile.php (units, caching).

Implementation Patterns

Core Workflows

Basic Integration:
- Register the tile in your dashboard provider (as shown above).
- Ensure config/app.timezone is set correctly (e.g., America/New_York) for accurate time display.

API Configuration:

Use OpenWeatherMap (default) or another provider by extending the tile:

// app/Providers/DashboardServiceProvider.php
use Spatie\DashboardTimeWeatherTile\DashboardTimeWeatherTile;

Dashboard::create()
    ->withTile(DashboardTimeWeatherTile::new()
        ->useWeatherProvider(new CustomWeatherProvider())
    );

Set API keys in .env:
```
OPENWEATHERMAP_API_KEY=your_key_here
```

Localization:
- Leverages Laravel’s App::getLocale() for date formatting (no additional config needed post-v1.0.1).

Caching:

Weather data is cached by default (TTL: 5 minutes). Extend via:

DashboardTimeWeatherTile::new()
    ->cacheFor(seconds: 300) // Custom TTL

Timezone Handling:
- v4.1.0+: Automatically uses config/app.timezone. Override per-user with:
```
DashboardTimeWeatherTile::new()
    ->timezone('Europe/Paris') // Static override
```

Integration Tips

Dashboard Layout: Place the tile in a dedicated column or sidebar for minimal disruption:

Dashboard::create()
    ->column()
        ->withTile(DashboardTimeWeatherTile::new())
    ->endColumn()

Conditional Rendering: Show/hide based on user roles or regions:

if (auth()->user()->isAdmin()) {
    Dashboard::create()->withTile(DashboardTimeWeatherTile::new());
}

Testing: Mock API responses in PHPUnit:

$this->mockWeatherApi()
     ->shouldReturn(['temp' => 20, 'weather' => ['icon' => '01d']]);

Extending Functionality: Add indoor temperature (v1.3.0+):

DashboardTimeWeatherTile::new()
    ->withInsideTemperature(22) // Celsius

Gotchas and Tips

Pitfalls

Timezone Mismatches:
- Issue: Tile may show incorrect time if config/app.timezone is misconfigured.
- Fix: Verify APP_TIMEZONE in .env and test with:
```
php artisan tinker
>>> \Carbon\Carbon::now()->timezone(config('app.timezone'));
```

API Failures:

Issue: Tile crashes if weather API is down (pre-v1.3.1).

Fix: Update to v1.3.1+ or wrap API calls in a try-catch:

try {
    $weather = $provider->getWeather();
} catch (\Exception $e) {
    $weather = null; // Fallback to cached data or placeholder
}

Rate Limits:
- Issue: Free-tier APIs (e.g., OpenWeatherMap) have call limits (~60/min).
- Fix: Cache aggressively (cacheFor(300)) and monitor usage via API dashboard.
Blade Rendering Quirks:
- Issue: Emojis or symbols may render incorrectly in some browsers (pre-v1.2.1).
- Fix: Update to v1.2.1+ or use Unicode escapes:
```
{!! html_entity_decode('&#x1F321;') !!} 
```
Inside Temperature:
- Issue: insideTemperature span appears even when unset (pre-v2.0.2).
- Fix: Update to v2.0.2+ or conditionally render:
```
@if($insideTemperature)
    <span>{{ $insideTemperature }}°C</span>
@endif
```

Debugging Tips

API Debugging: Log raw API responses to .env:

\Log::debug('Weather API Response:', $weatherData);

Check logs with:

tail -f storage/logs/laravel.log

Timezone Debugging: Dump the active timezone:

\Log::info('Active Timezone:', config('app.timezone'));

Caching Issues: Clear cached views and config:

php artisan view:clear
php artisan config:clear

Extension Points

Custom Weather Providers: Implement Spatie\DashboardTimeWeatherTile\Contracts\WeatherProvider:

use Spatie\DashboardTimeWeatherTile\Contracts\WeatherProvider;

class CustomWeatherProvider implements WeatherProvider {
    public function getWeather(): array {
        return ['temp' => 18, 'weather' => ['icon' => '02n']];
    }
}

Blade Overrides: Copy the default template to resources/views/vendor/dashboard-time-weather-tile.blade.php and modify:

<div class="tile">
    <!-- Customize here -->
    <div class="time">{{ now()->format('H:i') }}</div>
    <div class="weather">🌤️ {{ $temperature }}°C</div>
</div>

Dynamic Configuration: Fetch API keys or settings from the database:

$apiKey = \App\Models\Setting::first()->weather_api_key;
config(['dashboard-time-weather-tile.api_key' => $apiKey]);

Unit Testing: Mock the weather provider in tests:

$this->app->bind(
    \Spatie\DashboardTimeWeatherTile\Contracts\WeatherProvider::class,
    function () {
        return new class implements WeatherProvider {
            public function getWeather(): array {
                return ['temp' => 15, 'weather' => ['icon' => '03d']];
            }
        };
    }
);

Configuration Quirks

Units: Defaults to Celsius. Change in config/dashboard-time-weather-tile.php:
```
'units' => 'fahrenheit',
```
Environment Variables: Prefix API keys with DASHBOARD_TIME_WEATHER_TILE_ to avoid conflicts:
```
DASHBOARD_TIME_WEATHER_TILE_OPENWEATHERMAP_API_KEY=your_key
```
Dashboard Version: Ensure compatibility with spatie/laravel-dashboard:
- v4.x: Use spatie/laravel-dashboard-time-weather-tile v4.0.0+.
- v3.x: Use v3.0.0.

Laravel Dashboard Time Weather Tile Laravel Package