Laravel Dashboard Time Weather Tile Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require spatie/laravel-dashboard-time-weather-tile
   

2. Publish the config (if customization is needed):

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

3. Register the tile in your dashboard configuration (e.g., config/dashboard.php):

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

4. Configure the weather API (e.g., OpenWeatherMap) in .env:

   WEATHER_API_KEY=your_api_key_here
   WEATHER_API_UNITS=metric  # or imperial
   

5. Add the tile to your dashboard view (if not auto-registered):

   <x-dashboard-tile :tile="$dashboardTimeWeatherTile" />
   

First Use Case

Display a time and weather tile in your Laravel Dashboard for internal tools or admin panels. Example:

// In a controller or service
use Spatie\DashboardTimeWeatherTile\DashboardTimeWeatherTile;

public function showDashboard()
{
    $tile = new DashboardTimeWeatherTile(
        timezone: config('app.timezone'),
        weatherApiKey: config('services.openweathermap.api_key'),
        location: 'New York' // Optional: Override default location
    );

    return view('dashboard', ['dashboardTimeWeatherTile' => $tile]);
}

Implementation Patterns

Core Workflows

1. Basic Integration:

   • Use the tile as-is with default settings (timezone from config/app.timezone, weather from OpenWeatherMap).
   • Example:

     $tile = new DashboardTimeWeatherTile();
     

   • Renders time in the configured timezone and fetches weather for the default location (or a specified one).

2. Custom Location:

   • Pass a location (city/country) to override defaults:

     $tile = new DashboardTimeWeatherTile(location: 'London,UK');
     

3. Units Configuration:

   • Set temperature units (metric/imperial) via config or constructor:

     $tile = new DashboardTimeWeatherTile(units: 'imperial');
     

   • Or in config/dashboard-time-weather-tile.php:

     'units' => 'metric',
     

4. Caching:

   • Weather data is cached by default (TTL: 5 minutes). Extend the Spatie\DashboardTimeWeatherTile\WeatherService to customize caching logic.

5. Blade Integration:

   • Use the tile in Blade views directly:

     <x-dashboard-time-weather-tile :tile="$dashboardTimeWeatherTile" />
     

   • Or render manually:

     {!! $dashboardTimeWeatherTile->render() !!}
     

Advanced Patterns

1. Dynamic Timezone:

   • Fetch the user’s timezone from a session/database and pass it to the tile:

     $tile = new DashboardTimeWeatherTile(timezone: auth()->user()->timezone);
     

2. Weather Provider Swap:

   • Extend the WeatherService to support alternative APIs (e.g., Buienradar):

     use Spatie\DashboardTimeWeatherTile\WeatherService;
     
     class CustomWeatherService extends WeatherService
     {
         public function getWeatherData(string $location): array
         {
             // Custom logic for Buienradar or other APIs
         }
     }
     

   • Bind the service in a provider:

     $this->app->bind(
         \Spatie\DashboardTimeWeatherTile\WeatherService::class,
         CustomWeatherService::class
     );
     

3. Conditional Rendering:

   • Disable weather display if the API is unavailable:

     $tile = new DashboardTimeWeatherTile(showWeather: env('SHOW_WEATHER', true));
     

4. Testing:

   • Mock the WeatherService in tests:

     $weatherService = Mockery::mock(WeatherService::class);
     $weatherService->shouldReceive('getWeatherData')
         ->andReturn(['temp' => 20, 'description' => 'Clear']);
     
     $tile = new DashboardTimeWeatherTile(weatherService: $weatherService);
     

Gotchas and Tips

Pitfalls

1. Timezone Mismatch:

   • Issue: Time displayed may not match user expectations if config/app.timezone is not set correctly.
   • Fix: Ensure APP_TIMEZONE in .env is accurate (e.g., America/New_York). Release 4.1.0 resolves this by using the configured timezone automatically.

2. Weather API Failures:

   • Issue: Tile crashes if the weather API is down or returns invalid data.
   • Fix: Use the showWeather flag to disable weather display:

     $tile = new DashboardTimeWeatherTile(showWeather: false);
     

   • Or extend the WeatherService to handle errors gracefully.

3. Caching Issues:

   • Issue: Stale weather data if caching is misconfigured.
   • Fix: Clear cache manually or adjust TTL in config/dashboard-time-weather-tile.php:

     'cache_ttl_minutes' => 5,
     

4. Location Ambiguity:

   • Issue: Weather data for ambiguous locations (e.g., "Paris" could be Paris, France or Paris, Texas).
   • Fix: Specify full location (e.g., Paris,FR) or implement a location resolver.

5. CSS Conflicts:

   • Issue: Tile styles may clash with existing dashboard CSS.
   • Fix: Override styles in your app’s CSS:

     .dashboard-time-weather-tile {
         /* Custom styles */
     }
     

Debugging Tips

1. Log Weather Data:

   • Temporarily log weather API responses to debug issues:

     $weatherService = app(WeatherService::class);
     $data = $weatherService->getWeatherData('New York');
     \Log::info('Weather Data:', $data);
     

2. Check API Key:

   • Verify WEATHER_API_KEY in .env is correct and not expired.

3. Test Timezone:

   • Confirm the timezone is set in .env:

     APP_TIMEZONE=America/New_York
     

4. Disable Weather:

   • Temporarily disable weather to isolate issues:

     $tile = new DashboardTimeWeatherTile(showWeather: false);
     

Extension Points

1. Custom Weather Icons:

   • Override the default emoji-based icons by extending the tile’s view:

     @extends('dashboard-time-weather-tile::tile')
     
     @section('weather-icon')
         @if($weather['description'] === 'Clear')
             <i class="fas fa-sun"></i>
         @endif
     @endsection
     

2. Add Forecast:

   • Extend the WeatherService to fetch forecast data:

     public function getForecastData(string $location): array
     {
         // Implement logic for 5-day forecast
     }
     

   • Update the tile’s view to display forecast data.

3. Localization:

   • Customize date/time formatting by overriding the tile’s locale logic:

     $tile = new DashboardTimeWeatherTile(locale: 'fr_FR');
     

4. Dark Mode Support:

   • Add dark mode classes to the tile’s HTML output:

     $tile->addClass('dark:bg-gray-800');
     

5. Event Listeners:

   • Listen for weather updates or tile rendering events:

     \Event::listen(
         \Spatie\DashboardTimeWeatherTile\Events\WeatherUpdated::class,
         function ($event) {
             \Log::info('Weather updated:', $event->data);
         }
     );