Zum Hauptinhalt springen
Schneespur
Dokumentation durchblättern

Module entwickeln

Wetter & Zeitplanung

Wie Module eigene Wetter-Provider und zeitgesteuerte Aufgaben bereitstellen — austauschbare WeatherProvider, das WeatherData-Objekt und der ScheduledTask mit Cron-Ausdruck und Lauf-Protokoll.

Winterdienst hängt am Wetter, und vieles läuft zeitgesteuert im Hintergrund: Daten abrufen, alte Daten löschen, Berichte erzeugen. Dieser Abschnitt zeigt die zwei Erweiterungspunkte dafür — eigene Wetter-Provider und eigene geplante Aufgaben.

Wetter-Provider

Warum austauschbare Provider

Schneespur bezieht Wetterdaten nicht fest verdrahtet von einer einzigen Quelle, sondern über eine austauschbare Schnittstelle. Jeder Provider liefert dieselbe Datenstruktur, egal woher die Werte stammen. So lässt sich die Datenquelle wechseln, ohne den Rest der Anwendung anzufassen — und ein Modul kann eine zusätzliche Quelle nachrüsten, ohne Core-Dateien zu verändern.

Jeder Provider implementiert dasselbe Interface:

interface WeatherProviderInterface
{
    public function fetchCurrent(float $lat, float $lon): ?WeatherData;

    /** @return array{ok: bool, message: string, latency_ms: int} */
    public function testConnection(float $lat, float $lon): array;

    public function name(): string;
    public function requiresApiKey(): bool;
}

Die vier Methoden teilen sich zwei Aufgaben: fetchCurrent() holt die eigentlichen Wetterwerte für einen Standort, testConnection() prüft im Hintergrund, ob die Quelle erreichbar ist und wie schnell sie antwortet. name() und requiresApiKey() liefern der Oberfläche die Angaben, die sie für die Provider-Auswahl und die Schlüssel-Eingabe braucht.

Mitgelieferte Provider

Im Kern sind mehrere Provider registriert. Welcher davon im Betrieb sinnvoll ist, hängt vom Anbieter, seinen Nutzungsbedingungen und Ihrem Standort ab — die Auswahl treffen Sie in der Oberfläche.

SlugProviderAPI-Schlüssel nötig
openmeteo_freeOpen-Meteo (free tier)Nein
openmeteo_apiOpen-Meteo (API tier)Ja
brightskyBrightSky (DWD-Daten)Nein
met_norwayMet Norway (MET API)Nein

Prüfen Sie vor dem produktiven Einsatz die Nutzungsbedingungen des jeweiligen Anbieters — manche Tarife sind ausdrücklich auf nicht-kommerzielle Nutzung beschränkt. Genau für solche Fälle ist das Provider-System austauschbar: Reicht eine vorhandene Quelle nicht, binden Sie über ein Modul eine eigene ein.

Einen Wetter-Provider als Modul bauen

Ein eigener Provider ist eine Klasse, die WeatherProviderInterface implementiert. Das folgende Beispiel ruft eine externe API ab und übersetzt deren Antwort in ein WeatherData-Objekt:

namespace Schneespur\Module\CustomWeather\Weather;

use App\Models\Setting;
use App\Services\Weather\WeatherData;
use App\Services\Weather\WeatherProviderInterface;
use Illuminate\Support\Facades\Http;

class CustomWeatherProvider implements WeatherProviderInterface
{
    public function fetchCurrent(float $lat, float $lon): ?WeatherData
    {
        $response = Http::get('https://api.custom-weather.com/current', [
            'lat' => $lat,
            'lon' => $lon,
            'key' => Setting::get('custom-weather.api_key'),
        ]);

        if (!$response->successful()) return null;

        $data = $response->json();

        return new WeatherData(
            temperature_c: $data['temp'],
            precipitation_mm: $data['precip'],
            snow_depth_cm: $data['snow_depth'] ?? null, // null = not measured, 0.0 = measured no snow
            wind_kmh: $data['wind_speed'],
            humidity_percent: $data['humidity'],
            condition: $data['condition'] ?? 'clear',
            weather_code: $data['wmo_code'] ?? null,
            provider: 'custom_weather',
            observed_at: \Carbon\Carbon::now(),
        );
    }

    public function testConnection(float $lat, float $lon): array
    {
        $start = microtime(true);
        try {
            $result = $this->fetchCurrent($lat, $lon);
            $ms = (int) ((microtime(true) - $start) * 1000);
            return [
                'ok' => $result !== null,
                'message' => $result ? 'Connection successful' : 'No data returned',
                'latency_ms' => $ms,
            ];
        } catch (\Throwable $e) {
            return [
                'ok' => false,
                'message' => $e->getMessage(),
                'latency_ms' => (int) ((microtime(true) - $start) * 1000),
            ];
        }
    }

    public function name(): string { return 'Custom Weather API'; }
    public function requiresApiKey(): bool { return true; }
}

Zwei Punkte sind hier wichtig. Erstens gibt fetchCurrent() bei einem Fehlschlag null zurück statt eine Ausnahme nach oben durchzureichen — die Anwendung kann dann auf eine andere Quelle ausweichen, statt abzubrechen. Zweitens misst testConnection() die Antwortzeit in Millisekunden und meldet jeden Fehler als lesbare Nachricht zurück; genau diese Angaben zeigt die Oberfläche beim Verbindungstest an.

Registriert wird der Provider in der boot()-Phase Ihres ServiceProviders über die zuständige Registry:

app(WeatherProviderRegistry::class)->register('custom_weather', CustomWeatherProvider::class);

Das WeatherData-Objekt

WeatherData ist das gemeinsame Wertobjekt, in das jeder Provider seine Antwort übersetzt. Weil alle Provider dieselbe Struktur zurückgeben, muss der Rest der Anwendung nie wissen, woher die Daten stammen.

App\Services\Weather\WeatherData ist eine final readonly class. Ihre Konstruktor-Argumente tragen die Namen der folgenden Eigenschaften, in dieser Reihenfolge:

EigenschaftTypBedeutung
temperature_cfloatTemperatur in °C
precipitation_mmfloatNiederschlag in mm
snow_depth_cm?floatSchneehöhe in cm; null, wenn der Anbieter sie nicht misst, 0.0, wenn er keinen Schnee gemessen hat
wind_kmhfloatWindgeschwindigkeit in km/h
humidity_percentintrelative Luftfeuchte in %
conditionstringWetterlage als Slug, etwa "clear" oder "snow"; für die Anzeige über weather.condition_<slug> übersetzt
weather_code?intWMO-Wettercode, null, wenn der Anbieter keinen liefert
providerstringProvider-Slug, etwa "openmeteo_free"
observed_atCarbon\CarbonZeitpunkt, für den die Beobachtung gilt

toArray() liefert dieselben Schlüssel; nur observed_at wird dabei mit toIso8601String() als Zeichenkette ausgegeben.

Der Unterschied zwischen null und 0.0 bei der Schneehöhe ist kein Detail: 0.0 heißt „kein Schnee“, und auf einem Einsatznachweis ist das eine Aussage, für die es eine Messung geben muss. Bis 1.2.1 haben Bright Sky (DWD) und MET Norway, die gar keine Schneehöhe melden, das Feld mit null Zentimetern gefüllt. Ein Kunde las dann „0.0 cm“ auch mitten im Schneefall. Seit 1.2.1 bleibt das Feld dort leer. Misst Ihre Quelle keine Schneehöhe, übergeben Sie null.

Ihr Provider ist dafür zuständig, die Felder der externen API auf genau diese Eigenschaften und Einheiten abzubilden. Liefert eine Quelle etwa Temperaturen in Fahrenheit, rechnen Sie im Provider auf °C um.

Die Schneehöhe läuft durchgehend in Zentimetern – in WeatherData::$snow_depth_cm und in der Spalte weather_snapshots.snow_depth, in die sie geschrieben wird. Meldet die API Ihres Anbieters die Schneehöhe in Metern, wie es Open-Meteo tut, rechnen Sie vor dem Erzeugen von WeatherData um. Genau an dieser Stelle lag der Core bis 1.2.1 um den Faktor hundert daneben: 15 cm erschienen als „0.2 cm“, weil ein Meterwert als Zentimeter gespeichert wurde.

Wetter für einen vergangenen Zeitpunkt (seit 1.2.1)

Hinzugekommen in 1.2.1. WeatherProviderInterface bleibt unverändert. Ein Provider kann seither zusätzlich ArchiveWeatherProviderInterface implementieren und damit das Wetter für einen vergangenen Zeitpunkt liefern. Gebraucht wird das, wenn ein Einsatz nachträglich erfasst wird: Der Einsatznachweis soll das Wetter der Stunde tragen, in der der Einsatz tatsächlich stattfand, und nicht das Wetter des Tages, an dem er eingetippt wurde.

namespace App\Services\Weather;

use Carbon\CarbonInterface;

interface ArchiveWeatherProviderInterface
{
    public function fetchAt(float $lat, float $lon, CarbonInterface $moment): ?WeatherData;
}

Das ist bewusst ein eigenes Interface und keine zusätzliche Methode an WeatherProviderInterface. Eine Pflichtmethode dort würde jeden Provider brechen, den ein Modul bereits registriert hat – die WeatherProviderRegistry ist eine ExtensionRegistry, und Provider ohne Archiv sollen es einfach nicht implementieren. Der Core prüft per instanceof, bevor er fetchAt() aufruft.

$moment wird in UTC gelesen und stundengenau ausgewertet: Runden Sie vor der Abfrage Ihrer eigenen API auf den Beginn der Stunde ab und geben Sie die Beobachtung für genau diese Stunde zurück. Hat Ihr Provider dafür nichts, geben Sie null zurück. Der Aufrufer behandelt das wie jedes andere fehlende Wetter – es greift der bestehende Datenqualitäts-Hinweis „Wetter fehlt“ – und weicht nicht auf das aktuelle Wetter aus.

Von den mitgelieferten Providern implementieren openmeteo_free, openmeteo_api und brightsky das Archiv-Interface. met_norway tut es nicht, weil die MET-API keinen Endpunkt für historische Daten hat. Ein nachträglich erfasster Einsatz bekommt auf einer Installation mit met_norway deshalb kein Wetter statt des falschen.

Konvention: Einheiten der TTL

Die Wetter-Einstellungen verwenden in der Oberfläche Minuten, in der Datenbank dagegen Sekunden (TTL = Gültigkeitsdauer zwischengespeicherter Wetterdaten). Die Umrechnung in beide Richtungen übernimmt der Controller. Wenn Ihr Modul mit den Wetter-TTL-Einstellungen arbeitet, halten Sie sich an dieselbe Konvention, damit die Werte konsistent bleiben.

Geplante Aufgaben

Warum geplante Aufgaben

Manche Arbeit soll nicht auf Knopfdruck laufen, sondern regelmäßig im Hintergrund: täglich abgelaufene Daten löschen, stündlich nach Updates sehen, jede Minute die Warteschlange abarbeiten. Dafür gibt es geplante Aufgaben. Ein Modul kann eigene Aufgaben beisteuern, ohne den Cron-Aufbau der Anwendung zu kennen — es beschreibt nur, was wann laufen soll.

Jede Aufgabe implementiert dieses Interface:

interface ScheduledTaskInterface
{
    public function slug(): string;           // unique identifier
    public function label(): string;          // human-readable name
    public function schedule(): string;       // cron expression
    public function handle(): void;           // task execution
    public function isEnabled(): bool;        // whether task should run
    public function source(): string;         // 'core' or module slug
}

slug() ist die eindeutige Kennung, label() der lesbare Name für die Oberfläche. schedule() legt über einen Cron-Ausdruck fest, wann die Aufgabe läuft, handle() enthält die eigentliche Arbeit. Über isEnabled() kann sich eine Aufgabe abhängig von einer Einstellung selbst stilllegen, und source() weist sie dem Kern ('core') oder einem Modul-Slug zu — so bleibt nachvollziehbar, woher eine Aufgabe stammt.

Mitgelieferte Aufgaben

Im Kern laufen unter anderem diese Aufgaben:

SlugZeitplanBeschreibung
retention-deletetäglichlöscht abgelaufene Daten gemäß Aufbewahrungsregel
update-checktäglichsucht nach Anwendungs-Updates
queue-work* * * * *arbeitet Jobs aus der Warteschlange ab
cron-heartbeat* * * * *hält Cron-Aktivität für die Funktionsprüfung fest

Eine geplante Aufgabe bauen

Das folgende Beispiel erzeugt jeden Morgen um 06:00 Uhr einen Bericht und lässt sich über eine Einstellung an- und abschalten:

namespace Schneespur\Module\Reports\Scheduler;

use App\Models\Setting;
use App\Services\Scheduler\ScheduledTaskInterface;

class DailyReportTask implements ScheduledTaskInterface
{
    public function slug(): string { return 'daily-report'; }
    public function label(): string { return 'Daily Report Generation'; }
    public function schedule(): string { return '0 6 * * *'; } // 06:00 daily

    public function handle(): void
    {
        // Generate and send daily report
        $this->generateReport();
    }

    public function isEnabled(): bool
    {
        return (bool) Setting::get('reports.daily_enabled', false);
    }

    public function source(): string { return 'reports'; }
}

isEnabled() liest hier den Wert reports.daily_enabled aus den Einstellungen. Steht er auf false, überspringt die Anwendung die Aufgabe, ohne dass Sie den Code ändern müssen — Aktivieren und Deaktivieren läuft über die Oberfläche.

Registriert wird die Aufgabe wie der Wetter-Provider in der boot()-Phase über die zuständige Registry:

app(ScheduledTaskRegistry::class)->register('daily-report', DailyReportTask::class);

Läufe nachvollziehen

Die Registry hält fest, wann eine Aufgabe zuletzt lief, ob sie erfolgreich war und wie lange sie brauchte. Das macht Hintergrundarbeit überprüfbar: Eine Aufgabe, die seit Tagen nicht mehr erfolgreich gelaufen ist, fällt so auf.

$registry = app(ScheduledTaskRegistry::class);

// After running a task
$registry->recordRun('daily-report', 'success', null, 1234); // 1234ms

// On failure
$registry->recordRun('daily-report', 'failed', 'Connection timeout', 5000);

// Get last run info
$lastRun = $registry->lastRun('daily-report');
// → object{slug, status, error_message, duration_ms, ran_at}

// Get all tasks with status
$all = $registry->allWithStatus();
// → ['daily-report' => ['task' => ..., 'last_run' => ...]]

recordRun() protokolliert einen einzelnen Lauf samt Status, Fehlermeldung und Dauer. lastRun() liefert den letzten Lauf einer Aufgabe, allWithStatus() alle Aufgaben mit ihrem jeweils letzten Status — genau die Übersicht, die die Oberfläche anzeigt.

Cron-Ausdrücke

Der Zeitplan einer Aufgabe ist ein gewöhnlicher Cron-Ausdruck. Die häufigsten Muster:

AusdruckBedeutung
* * * * *jede Minute
*/5 * * * *alle 5 Minuten
0 * * * *jede volle Stunde
0 6 * * *täglich um 06:00
0 0 * * 1jeden Montag um Mitternacht
0 0 1 * *am ersten Tag jedes Monats

Die genaue API der hier genutzten Registries — WeatherProviderRegistry und ScheduledTaskRegistry — steht unter Registries.