Cairn Laravel Package

Technical Evaluation

• Architecture fit: Good fit for Laravel applications already using Cairn’s middleware/rollup model. v1.3.0 extends the existing analytics surface rather than introducing a parallel telemetry stack: new dashboard panels, two new rollup dimensions, one new metric, and a global 404 recorder for unmatched GETs. This is a natural analytics expansion for a Laravel package and should be easy to reason about for teams familiar with Cairn’s pageview, rollup, and widget configuration model.
• Integration feasibility: High. The release explicitly states there is no migration. Adoption is mostly composer update, optional widget config changes, optional config:cache, and optional historical rollup backfill. The main integration work is not code-level but coordination: auditing JSON API clients for stricter validation, communicating the dashboard default change from 30 days to Today, and deciding whether to backfill Broken pages / per-route errors from retained raw entries.
• Technical risk: Moderate but contained. The largest risk is behavioral compatibility for API consumers: unknown parameters or unrecognized values now return 422 instead of being silently ignored or answered as a different question. This is a correctness improvement but a potentially breaking change for clients sending cache-busters or stale parameters. Secondary risks include the new global middleware recording eligible 404s, which could increase stored entries and rollup work under scanner traffic, and the dashboard default-range change, which may alter user expectations/bookmarks without a range parameter.
• Key questions: Which Laravel/PHP versions and dependencies are supported by the package’s composer constraints? Do any internal API clients send unknown parameters, nonstandard ranges, or unsupported group_by/metrics combinations? Is raw entry retention long enough to justify a rollup backfill? Has privacy/legal reviewed the not_found recording behavior, especially URL scrubbing and the fact that unmatched URLs are treated as a separate entry type? Are published widget lists in use, requiring explicit addition of SlowestRoutes and BrokenPages? What is the expected 404/scanner volume in production?

Integration Approach

• Stack fit: Strong for Laravel applications using web middleware and Cairn’s existing service provider/config conventions. The new global middleware is intentionally scoped: it records only GET requests answered 404 that are not asking for JSON, and it respects DNT/GPC/opt-out/consent/bots/sampling and Cairn::ignore(). Sanctum remains optional; a disabled API now returns 404 before configured auth middleware runs.
• Migration path: No database migration. Recommended path: update the package, update published config if widgets are explicitly listed, rerun config:cache if used, audit API clients, then optionally run the documented rollup backfill for retained raw entries. The backfill command is optional but useful for giving Broken pages and per-route errors history; unmatched-route not_found records cannot be backfilled because they were never recorded before.
• Compatibility: Mostly backward-compatible at the schema/storage layer, but not fully behavior-compatible at the API and dashboard UX layers. API limit semantics are corrected, dimension filters now actually narrow reports, disabled endpoints are always 404, and malformed/unrecognized parameters are rejected. Dashboard default range changes to Today when no recognized range is present, while explicit ranges/bookmarks continue to work. Slowest routes requires no backfill; Broken pages benefits from backfill.
• Sequencing: 1) Stage the package update and verify dashboard/API behavior. 2) Audit API clients for unknown parameters and expected default behavior. 3) Update published widget config and clear config cache. 4) Decide on rollup backfill window and run cairn:rollup in a controlled job. 5) Notify dashboard users of the Today default. 6) Roll to production and monitor 404/error entry volume, API 422 rates, and rollup duration.

Operational Impact

• Maintenance: Low ongoing maintenance for most teams. The release adds panels and dimensions but no migration. Operational care is mainly config hygiene: published widget lists must include the new panels if used, and cached config must be refreshed. API clients may need updates to avoid new 422s.
• Support: Support burden may rise briefly around two changes: users noticing the dashboard now opens on Today, and API consumers receiving 422s for parameters they previously got away with. Support docs should call out accepted parameter values, the limit cap at 1,000, and the fact that unknown parameters are rejected. The backfill command should be documented with the retained date range and expected runtime.
• Scaling: The new not_found entry type can increase write volume in environments with heavy scanning or broken-link traffic, though it excludes JSON requests and applies privacy gates. Dimension::ErrorPage is capped at the hundred most frequent status/URL/referrer combinations per bucket, which limits rollup growth. SlowestRoutes excludes routes with fewer than five pageviews, reducing noise. Monitor storage, rollup duration, and 404 entry rates after rollout.
• Failure modes: The most visible failure mode is API client breakage from stricter validation, especially cache-busting query parameters like _=…. A stale config cache can hide new widgets. A missed widget-list update makes Slowest routes and Broken pages invisible. A malformed or overly broad backfill command could reprocess more raw data than intended, so run it with explicit dates and period. The global middleware could record unexpected 404 traffic if bots/scanners bypass existing filters, so verify privacy gates and ignore rules. Disabled API behavior is improved: it now returns 404 rather than leaking 401/500 behavior.
• Ramp-up: Low to moderate. Developers familiar with Laravel and Cairn should ramp quickly; the main learning is the new panel/widget configuration and stricter API contract. TPM should coordinate a short enablement note for dashboard users and API consumers, plus a release checklist covering config cache, widget additions, API client audit, and optional backfill.