Monitor Bundle Laravel Package

Technical Evaluation

Architecture fit

• Monitor-bundle is an OpenConext Symfony bundle, not a Laravel package. It ships a Bundle subclass, a DI extension, service tags for checks, and an HTTP controller that returns symfony/http-foundation responses. It fits a Symfony application cleanly and fits a Laravel application only through adaptation.
• The genuinely reusable core is the check abstraction (CheckInterface, the built-in checks, and the status/health aggregation). That layer is plain PHP and is portable; the bundle wiring around it is not.
• Treat this as two distinct adoption decisions: (a) "install as a bundle" — Symfony only; (b) "reuse the check library behind our own route" — portable to Laravel. Do not let the team conflate them in planning.

Integration feasibility

• Symfony path: composer require openconext/monitor-bundle, register the bundle, expose /health, /info, /status, tag custom checks. Low effort, well-trodden, likely under a day including config.
• Laravel path: requires a service provider or config-driven registry that instantiates checks directly, a controller that serialises the aggregate result, and a route group. The check classes themselves are the only real dependency. Expect one to two sprints of small, low-complexity work — mostly deciding which built-in checks are meaningful outside an OpenConext deployment.
• The third option — run the bundle in a thin Symfony sidecar and scrape it from Laravel — is the lowest-coupling path and worth evaluating if health data needs to be uniform across heterogeneous services.

Technical risk

• This release (4.3.1) is low risk. A typo fix and a try/catch around check instantiation. No API changes, no deprecations, no configuration schema changes. It is a drop-in replacement for 4.3.0.
• The behavioural change is the one that matters, and it is not the typo: a check that fails to instantiate is now caught rather than propagating. The upside is that one misconfigured or broken check can no longer take down the entire health endpoint — a real availability improvement for a monitoring surface.
• The downside is the classic monitoring anti-pattern: fail-open health reporting. If a caught instantiation error results in the check being omitted, or reported as passing/unknown while an upstream or aggregator treats "no failure" as "healthy," we have manufactured a blind spot exactly where we most need signal. This must be verified against the implementation, not inferred from the changelog.
• Secondary risk: silent swallowing of misconfiguration. Teams rotate check classes, rename services, or drop constructor dependencies and discover it months later because the endpoint stayed green.

Key questions

1. When a check fails to instantiate, does the aggregate endpoint report unhealthy/error, or does it silently skip the check? Confirm the fail-closed behaviour explicitly.
2. Is the caught exception logged, and at what level? Do we get an alertable log line, or is it discarded?
3. What are the declared PHP and Symfony version constraints, and do they match our runtime? Any conflict with our existing symfony/* pins?
4. What is the maintenance posture — release cadence, maintainer count, open-issue backlog, and whether 4.3.x has a support horizon?
5. License terms and any restrictions relevant to redistribution or modification of the check classes.
6. Do the /info and /status endpoints leak version strings, environment names, or dependency details? What authentication or network restriction is expected in front of them?
7. For the Laravel use case: which built-in checks are actually portable, and which assume OpenConext infrastructure (SAML metadata endpoints, specific service topologies)?

Integration Approach

Stack fit

• Symfony services: near-perfect fit. This is the intended deployment target; adopt directly.
• Laravel services: partial fit. The aggregation logic and check contracts fit; the bundle, DI extension, and routing do not. Plan for a thin adapter rather than a package install.
• Polyglot estate: the sidecar pattern gives uniform health semantics across Symfony, Laravel, and non-PHP services with one implementation to reason about.
• Avoid vendoring the whole bundle into a Laravel app just to reach one or two check classes; the transitive Symfony surface will create upgrade friction we do not want to own.

Migration path

• On Symfony 4.3.0: bump to 4.3.1 as a routine patch. No config edits, no schema changes. Verify the fail-open behaviour before promoting.
• On Symfony ≤4.2.x: treat as a minor upgrade, which means reading the 4.3.0 changelog rather than just this release. This release note alone is not sufficient diligence for a minor-version jump.
• On no monitoring bundle today: start with a single endpoint and two or three high-value checks (database reachability, cache reachability, critical upstream dependency) before expanding. Resist wiring twenty checks in the first pass.
• Greenfield Laravel: implement a HealthController plus a small check registry, port only the checks that map to real dependencies, and standardise the response shape so a future sidecar swap is transparent to consumers.

Compatibility

• Composer constraints are the gating item. Run composer why-not openconext/monitor-bundle 4.3.1 in each candidate application before committing; this surfaces PHP or Symfony version conflicts in one step.
• Because the release touches exception handling inside check instantiation, any custom check that throws from its constructor will now behave differently. Enumerate custom checks and confirm the new path is the desired one for each.
• Confirm our alerting/aggregator treats a missing check as unhealthy. If it does not, fix the aggregator or add an explicit assertion that the expected check set is present, rather than relying on the bundle's default.

Sequencing

1. Verify fail-closed behaviour and logging in a non-production environment.
2. Bump Symfony services to 4.3.1; run the health endpoint contract tests against the expected JSON shape.
3. Add a synthetic "known-broken check" to staging and confirm the endpoint degrades loudly, not quietly.
4. Build the Laravel adapter or sidecar decision on its own track — it does not block the patch upgrade.
5. Standardise the response schema across all services before onboarding a second or third team, otherwise every team will invent its own.

Operational Impact

Maintenance

• Low ongoing cost for Symfony consumers: routine patch bumps, no local patches expected.
• The Laravel adapter, if built, becomes our code to maintain, not the upstream project's. Budget for that explicitly — it is the hidden cost of adopting a bundle outside its intended framework.
• Pin to ^4.3 and let patch releases flow through automated dependency updates, gated by contract tests on the endpoint payload.

Support

• Upstream is a single-vendor open-source project tied to OpenConext. Support is community-driven, and response times on issues should be assumed to be best-effort.
• Identify an internal owner for the health endpoint before rollout. Health checks are the surface everyone trusts and nobody owns, which is how they silently rot.
• Keep a record of every check we add and why. Undocumented checks are indistinguishable from stale checks a year from now.

Scaling

• Health endpoints are cheap; the checks are not always. A check that performs a network round trip on every request will amplify under frequent polling from load balancers and orchestrators. Cache expensive checks with a short TTL.
• Decide the polling contract up front: who calls the endpoint, at what interval, and from how many sources. Under Kubernetes with three probes per pod, request volume is not negligible.
• Keep the check set proportionate. An endpoint that takes several seconds to answer becomes a liveness failure under a tight timeout, which converts a monitoring tool into an availability risk.

Failure modes

• Fail-open reporting (new in this release). A check that cannot be instantiated may be absent from the response, and a consumer reading "no failures" as "healthy" will report green while the dependency is unmonitored. Highest-priority item to verify and mitigate with an expected-check-count assertion.
• Silent misconfiguration. Renamed classes, changed constructor signatures, or removed services now surface as a quietly missing check rather than a loud error. Add a startup or CI assertion that the configured check set resolves.
• Endpoint as a dependency. If the probe timeout is shorter than the check runtime, the orchestrator kills healthy pods. Keep per-check timeouts and an overall budget.
• Information disclosure. /info and /status commonly enumerate versions and dependencies. Ensure network-level restriction or authentication in front of them.
• Aggregator misreads. A consumer expecting a specific JSON shape may treat a changed or empty payload as success. Contract-test the payload, not just the HTTP status code.

Ramp-up

• A developer unfamiliar with the package can add a Symfony check in well under a day; the contract is small and the docs adequate.
• The Laravel adapter is the learning curve — roughly one to two weeks for someone to build and document, then near-zero for subsequent checks.
• Onboarding guidance should cover: how to add a check, how to confirm the check is actually executing, what a degraded response looks like, and who to call when the endpoint goes red. Without the second and third items, teams add checks that never run and never notice.
• Recommended first milestone: 4.3.1 on one Symfony service with fail-closed verification and an expected-check assertion, then expand.