Statamic Oh Dear Laravel Package

Technical Evaluation

What changed (v2.0.0)

• Upstream dependency moved from Oh Dear API v3 to API v4 (PR #15). This is the substantive change; the rest is cosmetic plus a major-version bump.
• Breaking change: method return types changed. The maintainer states this "should not affect anyone," which is a plausible but unverified claim — it holds only if no consumer extends the addon's classes, type-hints against its return values, or overrides them in their own code.
• Styling adjustments to the Control Panel views — low functional risk, but any published views or CSS overrides will need re-checking.
• No new features, no deprecations announced, no changes to stated support matrix in the notes.

Architecture fit

• This is a Statamic addon, not a general Laravel package. It requires a Laravel app running Statamic, and it renders Oh Dear monitoring data (uptime, broken links, SSL, DNS, scheduled tasks) as Control Panel widgets.
• Integration surface is narrow and read-only: outbound HTTP to the Oh Dear API, config-driven credentials, Blade views registered via the addon service provider. It does not touch the database schema, queue, or auth.
• Because it is a presentation-layer addon, blast radius of a failure is limited to the CP dashboard — no customer-facing or data-integrity impact.

Integration feasibility

• Low-to-moderate. Standard Composer install into a Statamic project, publish config, supply an Oh Dear API token.
• The real feasibility question is API v4 parity: are all widgets the addon previously offered (broken links, certificate health, application health, cron monitoring) backed by equivalent v4 endpoints, and do the response shapes still map cleanly onto the existing view models? Return type changes suggest at least some DTO/response reshaping occurred.
• Auth model for v4 should be validated — a token scheme change would be the most likely hidden migration step beyond composer update.

Technical risk (ranked)

1. BC break with an unverified blast radius. "Should not affect anyone" is a maintainer assertion, not a guarantee. Mitigation: grep the codebase for direct references to the addon's namespaces/classes before upgrading.
2. API v3 sunset. The stronger risk is not upgrading — Oh Dear API v3 will eventually be withdrawn, at which point v1.x stops working. This upgrade is effectively time-boxed.
3. Single-maintainer, small-audience package. Contributions come from a small set of authors; release cadence is driven by upstream API changes rather than a product roadmap. Treat it as a lightly-maintained dependency.
4. Visual regression. Styling changes may conflict with any CP customisation or published views, but this is cosmetic and reversible.
5. Support matrix ambiguity. The notes do not state supported Statamic, Laravel, or PHP versions for v2 — a hard compatibility gate we must confirm from composer.json before scheduling.

Key questions for the maintainer / our own review

• What are the exact PHP / Laravel / Statamic version constraints for v2.0.0, and did any of them increase?
• Which methods changed signature, and what is the migration for anyone overriding them?
• Is feature parity achieved with API v4 across every widget shipped in v1.11.0, or were any capabilities dropped or deferred?
• What is Oh Dear's stated end-of-life date for API v3?
• Does v2 change the config file shape or the expected token/permissions scope?

Integration Approach

Stack fit

• Only relevant to projects that (a) run Statamic on Laravel and (b) already use Oh Dear for monitoring. If either is false, take no action — there is no transitive dependency forcing the upgrade.
• For projects that do qualify, the addon is a CP convenience layer: dev-owned, editor-facing, no runtime dependency for the public site.

Migration path

1. Read composer.json on the v2.0.0 tag and confirm PHP/Laravel/Statamic constraints against the target application.
2. Audit the codebase for references to the addon's namespace, class names, or return values (custom widgets, overrides, tests, any instanceof/type-hint usage).
3. Compare the published config file between v1.11.0 and v2.0.0; republish or diff-merge if the shape changed.
4. Upgrade in a branch: composer require jonassiewertsen/statamic-oh-dear:^2.0, then clear Statamic and application caches (php artisan cache:clear, statamic:stache:clear, view:clear).
5. Validate each CP widget against live Oh Dear data — confirm values populate rather than silently rendering empty.
6. Smoke-test in staging for at least one cache-refresh cycle to catch stale-cache behaviour.

Compatibility

• v2.0.0 is a hard major bump: no in-place drop-in for anything pinned to ^1.11. Plan the constraint change explicitly rather than letting a floating constraint pull it in unexpectedly.
• Rollback is cheap: pin back to ^1.11.0 and restore config. Keep the previous lockfile entry available until validation completes.

Sequencing

• Treat this as a scheduled maintenance item, not an incident. Bundle it into the next routine dependency cycle.
• However, track the Oh Dear API v3 sunset date as a hard deadline. If v3 is withdrawn within our normal dependency cadence, promote this to a planned ticket with an explicit due date rather than waiting for the next sweep.
• Do the audit and composer.json review before committing to the sprint — if the support matrix has narrowed (e.g. dropped a PHP version we run), the ticket scope changes materially.

Operational Impact

Maintenance

• Minimal ongoing cost: no migrations, no schema, no background jobs owned by us. The maintenance burden is periodic version alignment with Oh Dear's API, which is exactly what this release represents.
• The ^2.0 constraint should be set deliberately; given a single-maintainer project with infrequent releases, allow patch/minor updates but review majors.

Support

• User-facing support load is low — the widgets are read-only and either show data or don't. The realistic support ticket is "the Oh Dear panel is blank," which resolves to one of: expired/rotated API token, insufficient token scope, rate limiting, or an API v4 response-shape mismatch.
• Document the token rotation procedure and where the token is configured, so this is a five-minute fix rather than an escalation.

Scaling

• Negligible scaling concern. Each CP page view triggers a small number of outbound API calls to Oh Dear; volume scales with editor count and dashboard views, not with site traffic.
• Two watch items: Oh Dear API rate limits (worth confirming the v4 quota, since a team of editors refreshing dashboards can accumulate calls) and CP render latency if widgets fetch synchronously without caching. If caching was part of the return-type reshaping, verify it still works.

Failure modes

• Silent degradation — the most likely failure. An API v4 shape change or auth rejection renders empty widgets rather than throwing. Ensure widget emptiness is visible enough to be noticed; consider a lightweight uptime check on the CP page in staging only.
• Hard dependency on upstream — if Oh Dear changes v4 responses or the maintainer stops shipping fixes, we are exposed with no fork plan. Acceptable for a dashboard nicety; unacceptable if anyone has grown to depend on it operationally.
• Delayed-upgrade cliff — staying on v1.11.0 past the v3 sunset produces a sudden total failure rather than a gradual one. This is the failure mode worth actively scheduling against.
• Visual regression — styling changes may clash with CP customisations; cosmetic and immediately visible.

Ramp-up

• Developer: roughly half a day to audit, upgrade, configure, and validate in staging — dominated by the parity check, not the install.
• Editor/end user: effectively zero. The CP widgets look and behave as before; only the underlying data source version changes. No training, no documentation updates beyond an internal note that the addon is now on API v4.
• Recommend a short internal note recording the upgrade, the Oh Dear API v3 sunset date, and the token-rotation steps, so the next person doesn't have to rediscover them.