Statamic Oh Dear Laravel Package

Getting Started

This is a Statamic addon (not a general Laravel package) — it surfaces Oh Dear monitoring data inside the Statamic Control Panel, so you'll want a Statamic 4/5 site with an Oh Dear account before anything else.

1. composer require jonassiewertsen/statamic-oh-dear
2. Publish the config: php please vendor:publish --tag=statamic-oh-dear-config (or php artisan vendor:publish — same thing in a Statamic app).
3. Add your Oh Dear API token to .env (OH_DEAR_API_TOKEN=...) and reference it from config/statamic-oh-dear.php. Generate the token in Oh Dear under Account → API tokens — v2.0.0 talks to API v4, so use a token created for that API.
4. Register the dashboard widget in your CP dashboard config (or via the widget picker in the CP), and clear caches: php please cache:clear && php artisan config:clear.

First use case: drop the Oh Dear widget onto your Statamic dashboard and use it as the "is production healthy?" glance — uptime, broken links, mixed content, and certificate status for each monitored site without leaving the CP. That's the 90% workflow for most teams; everything else (alerts, cron checks) lives in Oh Dear itself.

Implementation Patterns

Treat the config file as the single source of truth. Keep the token in env(), and map each Statamic site handle to its Oh Dear site ID in the config rather than hardcoding IDs in templates. For multi-site installs this mapping is the thing you'll actually edit, and it keeps the widget honest per-site.

Add the widget, don't rebuild the dashboard. The intended integration is Statamic's dashboard widget system — you register the widget and Statamic handles rendering and the CP route. If you want the data elsewhere (a custom CP page, a status badge in a nav), the cleaner pattern is to resolve the package's service/API client from the container and read the typed response objects, rather than scraping the widget's Blade view.

Cache aggressively around the API. Oh Dear's API is rate-limited per token, and dashboard widgets get hit on every CP page load. Wrap calls in Cache::remember() with a short TTL (2–5 minutes is plenty for uptime data) keyed by site ID. This is the single highest-value thing you can do, and it's on you — the package won't do it for you.

Scheduled health checks. If you want uptime data in your own tooling, call the client from a scheduled command or job (app/Console/Kernel.php / routes/console.php) and store the result, rather than calling Oh Dear synchronously in a request. Combine with ->onOneServer() and withoutOverlapping() so multi-server deployments don't multiply your API usage.

Blade-level usage. Publish the views (--tag=statamic-oh-dear-views) and restyle rather than fork. v2.0.0 changed the default styling, so if you'd previously overridden markup for layout reasons, re-diff your published views against the new ones.

Gotchas and Tips

The v2 breaking change is real but narrow. Return types on the package's methods changed to match Oh Dear API 4 (concretely: shapes/types of the data objects returned). The release note says it "should not affect anyone" — that's true if you only used the widget, and false if you: extended the package's classes, type-hinted against its return types, or called the client directly from your own code. Grep your app for the package namespace before upgrading. There's no deprecation path here — it's a hard version bump, so pin ^1.11 first if you have custom integrations and upgrade deliberately.

API version mismatch is the top failure mode. An Oh Dear token that worked on v1.x may not authenticate or may not have the scopes for API 4 endpoints. If you get 401/403 after upgrading, regenerate the token before debugging anything else. Also check the endpoint base URL — a stale published config pointing at a v3 path will silently 404.

Published config wins over package defaults. After upgrading, your published config/statamic-oh-dear.php is not updated. If v2 added or renamed config keys, you won't see them. Diff the package's config against yours on every major upgrade.

config:cache is the classic self-own. Change the token in .env, forget to re-cache config, and you'll swear the API is down. Same for widget registration changes in the Statamic CP config.

Debugging order that actually works: (1) php artisan config:clear, (2) hit the Oh Dear API endpoint directly with curl and the same token to isolate package vs. credentials, (3) check storage/logs/laravel.log — the package surfaces HTTP failures there rather than in the CP UI, so the widget just renders empty. An empty widget almost always means a swallowed HTTP exception, not "no sites monitored."

Extension points to prefer: published config (site mapping, token), published views (styling), and the container-bound API client (custom data needs). Avoid subclassing the package's classes — the v2.0.0 return-type change is exactly the kind of break that bites subclassers, and this package has now demonstrated it will make those changes in a major release without a compatibility shim.