[Baspa]

Contains #49 (merged in to resolve a conflict in src/Buienradar.php): merge #49 first, then this diff shrinks to the feature. In the resolution actualForecastForStation() now uses the guarded stationMeasurements() helper.

What

Exposes data the JSON feed already contains but the package didn't return.

• sunrise(): ?DateTimeImmutable and sunset(): ?DateTimeImmutable: parse actual.sunrise / actual.sunset (local time without offset) in Europe/Amsterdam. Return null when the value is missing, isn't a string, or isn't exactly Y-m-d\TH:i:s. Partial dates, offsets and rolled-over dates like 02-30 are rejected.
• stations(): array<int, ActualForecast>: every current station measurement, list-indexed.
• nearestStation(float $lat, float $lon): ?ActualForecast: nearest station by haversine great-circle distance. A measurement without numeric lat/lon in the raw feed is skipped, because ActualForecast::fromArray would otherwise default it to 0.0, 0.0. Returns null when no station has coordinates.
• Each method fetches the feed once, the same way actualForecastForStation() does. Calling sunrise() and sunset() (or stations() and nearestStation()) therefore downloads the feed twice until Every call re-downloads the whole feed #42 adds per-instance caching.
• README: new section "Sun, all stations and nearest station".

Usage

$sunrise = $buienradar->sunrise();   // 2026-11-13 07:55:00 Europe/Amsterdam
$sunset = $buienradar->sunset();

$stations = $buienradar->stations(); // array<int, ActualForecast>

$station = $buienradar->nearestStation(52.1, 5.18);
echo $station?->stationname;         // 'Meetstation De Bilt'

• Review follow-ups: the README "Error handling" line now lists nearestStation(), sunrise() and sunset() as returning null on failure; failure-path tests (non-2xx, malformed actual / stationmeasurements) for all four new methods.

Tests

28 tests / 57 assertions pass (14 new in tests/StationsTest.php), PHPStan clean.

• Sunrise and sunset in Europe/Amsterdam, including summer time (+02:00).
• null when the feed has no sun times (the fixture has none) and for malformed values: date only, no seconds, with offset, impossible date, non-string, empty.
• stations() against the fixture returns 3 ActualForecasts with list keys.
• nearestStation(52.1, 5.18) against the fixture returns De Bilt, and a point near Volkel returns Volkel.
• A station without coordinates is skipped. null is returned when no station has both coordinates.
• An empty feed returns [] from stations() and null from the other methods.

Also checked against the live feed: 40 stations, sunrise 2026-11-13T07:55:00+01:00.

Closes #43

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.14%. Comparing base (1548600) to head (780917a).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #50      +/-   ##
============================================
- Coverage     92.85%   87.14%   -5.72%     
- Complexity       40       64      +24     
============================================
  Files             4        4              
  Lines           168      210      +42     
============================================
+ Hits            156      183      +27     
- Misses           12       27      +15     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.