Enrichments Bundle Laravel Package

Technical Evaluation

Architecture fit This is a single-commit, pre-1.0 release (v0.1.2) of a Laravel/PHP package. The only change is a visibility narrowing: services are now private because they are "only needed in the dispatcher." Architecturally, this tells us the package is a dispatcher-centric component with supporting services that are implementation detail rather than a public extension surface. That is a reasonable and healthy design signal for a small package — it shrinks the public API to the dispatcher and reduces the surface we can accidentally couple to. It also implies the package exposes (or intends to expose) a single entry point rather than a composable service graph, which fits Laravel's service-container idiom well but limits consumers who want to decorate or replace individual collaborators.

Integration feasibility Low effort to adopt. No new configuration, no schema or contract changes, no dependency churn are indicated. The realistic cost is a small audit: grep our application and any first-party packages for direct container resolution or constructor injection of the affected services (app(...), resolve(...), facades, #[Inject], test doubles that bind those classes). If nothing resolves them outside the dispatcher, the upgrade is a version bump and a composer update.

Important caveat: "private" is ambiguous in PHP/Laravel terms — it could mean (a) container bindings no longer publicly resolvable (Symfony-DI-style public: false, or Laravel's non-shared/internal binding patterns), (b) the service classes' methods/properties were narrowed to private, or (c) the dispatcher now holds them as private properties. Each has a different blast radius. We should confirm which before assuming a no-op.

Technical risk

• Low-to-moderate. On the happy path this is an internal refactor and is safe.
• Breaking for extenders. Anyone who bound, mocked, decorated, or resolved these services directly will break — typically at container-resolution time or via a test that no longer substitutes a fake. Because the package is at 0.1.x, the maintainer may legitimately treat this as a patch; we should not rely on semver to protect us at this stage.
• Test-suite fragility. Private collaborators are harder to isolate; if our tests exercised these services directly, they will need to move up to dispatcher-level (behavioural) assertions. That is arguably better testing, but it is work.
• Refactor-without-release-notes risk. A one-line changelog for a visibility change suggests thin release documentation. We should assume future releases may also be under-documented and plan to read diffs, not just notes.
• Maturity risk dominates everything else. At v0.1.2 the API is not stable; visibility of internals is the least of our concerns.

Key questions

1. Which services changed, and what exactly does "private" mean here — container binding visibility, PHP member visibility, or both?
2. Is the dispatcher the documented, supported entry point? Is there a public contract (interface) we should depend on instead of concrete classes?
3. Is this intended as a patch-level change, and does the maintainer consider direct service resolution a supported use case? (Ask for an explicit statement on backwards-compatibility policy pre-1.0.)
4. Are there extension points — custom dispatchers, middleware, events — or is the package closed for extension by design?
5. What is the intended 1.0 timeline? Should we pin to an exact version rather than a caret range?

Integration Approach

Stack fit Presumes a standard Laravel application with package auto-discovery and a service provider. Fit is good: the change reinforces a provider-registers, dispatcher-executes shape that matches Laravel conventions. No framework-version-specific features are implied by the note, but confirm the illuminate/support constraint against our Laravel version before committing.

Migration path

1. Pin the current version (v0.1.1 or whatever we run today) as a baseline.
2. Search the codebase for direct references to the affected services — container calls, constructor injections, facade access, config keys, and test bindings/mocks.
3. If references exist, refactor them to go through the dispatcher (or add a thin adapter of our own so the dependency stays in one place).
4. Upgrade to v0.1.2, run the full suite, and specifically re-run any tests that used to fake the now-private services.
5. Record the affected services in our internal notes so the next visibility change is cheap.

Compatibility Expect no impact on the dispatcher's public behaviour, so functional compatibility should hold. The exposure is compile-time/DI-time: container resolution and test substitution. Because the package is pre-1.0, we should treat every minor bump as potentially breaking and avoid depending on internals in application code.

Sequencing Do the audit and refactor before the version bump so the upgrade is a clean, isolated change we can revert independently. Keep the version bump in its own commit/PR. If the audit finds no external resolution, take the bump immediately — the longer we sit on a superseded 0.1.x, the more likely we accumulate drift against later releases.

Operational Impact

Maintenance Effectively zero ongoing maintenance on our side; no configuration, no migrations, no new runtime surface. The real maintenance burden is upstream volatility: a 0.1.x package with one-line changelogs requires us to read diffs rather than release notes. Budget a small recurring cost per upgrade, not a one-off.

Support Support is community/maintainer-only, with no commercial backing indicated. Because the change narrows the API, our ability to work around upstream issues by overriding individual services is reduced — that is a deliberate trade of flexibility for simplicity. Keep our integration thin so we can swap the package if it stalls.

Scaling No scaling implications. Visibility modifiers are compile-time only; there is no runtime, throughput, or memory effect. If the dispatcher is on a hot path, that concern predates this release and is unaffected by it.

Failure modes

• Container resolution error in any code path that resolved a now-private service — surfaces immediately and loudly at boot or first use, which is the good case.
• Silent test degradation — a mock that no longer substitutes and instead constructs the real service, producing passing-but-meaningless tests. This is the more dangerous failure and the reason to re-run the suite with attention, not just a green check.
• Upgrade dead-end — if a future release makes a genuinely breaking change to the dispatcher, our only lever is pinning; there is no internal seam to patch around.
• Documentation drift — third-party examples and older blog posts may still instruct direct service resolution, which will now fail for new team members.

Ramp-up Very low. A developer familiar with Laravel needs minutes to understand a dispatcher and its private collaborators; the pattern is idiomatic. The onboarding cost is not the code but the policy: new contributors must be told explicitly not to resolve or mock internals and to depend on the dispatcher (or the public contract) instead. Write that down in the README or an ADR while it is fresh, because the package's own docs may not say it.

Recommendation Adopt v0.1.2. It is a tightening change consistent with a maturing design, and the risk is confined to code that reaches past the intended entry point — which we should not be writing anyway. Pair the upgrade with a short internal note on the public surface and an exact-version pin until 1.0, and revisit the assessment when the next release either adds features or touches the dispatcher itself.