Adr Bundle Laravel Package

Technical Evaluation

Scope of this assessment: Based solely on the v0.0.2 release note ("Add support for directory route loading for actions") and the package's implied purpose. No source, test suite, or documentation has been inspected. Confidence in the specifics below is low; confidence in the shape of the risk is moderate.

Inferred architecture fit. The package appears to provide convention-based route registration for single-action (invokable) controller classes — the "action" pattern common in Laravel codebases and popularised by packages such as lorisleiva/laravel-actions. v0.0.2 adds the ability to point at a directory of action classes and have routes registered for all of them, rather than enumerating each class individually. This sits on top of Laravel's RouteRegistrar/Route facade and the service container, which is a well-trodden extension point. Nothing here requires forking framework internals, so architectural fit with a standard Laravel app is likely good — provided the implementation hooks the route registration phase correctly and cooperates with route:cache.

Integration feasibility. Low-to-moderate effort for a greenfield service or a bounded module; higher for an existing application with a hand-curated routes/web.php, because discovered routes must coexist with explicit ones and route precedence in Laravel is registration-order dependent. The feature is opt-in by directory, which is a genuinely good adoption property: we can mount discovery under a prefix and middleware group and leave the rest of the routing untouched. The main integration tax is convention discipline — class namespace and filename now determine the public URL surface.

Technical risk.

• Pre-1.0 API instability. v0.0.2 is the second release of an unversioned library. Semver guarantees are effectively absent. Treat every bump as potentially breaking.
• Route-cache interaction. If discovery performs filesystem scanning at request time rather than at route-cache build time, we either break php artisan route:cache or pay a scan cost per request. This is the single highest-severity unknown.
• Accidental exposure. Automatic registration means adding a class to a directory publishes an endpoint. Authorization is not implied by discovery; a developer adding an internal action class could unintentionally create a public route. This needs a guardrail (prefix + auth middleware at minimum, plus review of the discovery root).
• Implicit coupling, silent failure. Convention-driven routing fails quietly: rename or move a class and the route disappears with no error. Duplicate/colliding routes may resolve arbitrarily.
• Long-lived worker compatibility. Under Octane or similar, verify discovery state is boot-time and idempotent, not accumulated per request.
• Bus factor / maintenance signals. Unknown, but pre-1.0 OSS in this niche is frequently single-maintainer.

Key questions to resolve before adoption.

1. Is route discovery computed at boot/cache-build time, or per request? Does route:cache produce a complete, stable artifact?
2. How is the URI derived from the class (namespace stripping, kebab-casing, explicit overrides)? How is the HTTP verb determined — convention, a handle signature, or attributes?
3. Can individual classes or subdirectories be excluded/ignored?
4. Do discovered routes inherit the enclosing Route::middleware()/prefix()/name() group, and can names be assigned deterministically?
5. What is the collision policy when a discovered route overlaps an explicitly declared one?
6. Supported PHP/Laravel version matrix, CI status, test coverage, license, and maintainer responsiveness.

Integration Approach

Stack fit. Assumes Laravel 10–12 and PHP 8.1+. Best fit for teams already committed to the action/invokable-controller pattern; poor fit for teams using resource controllers and explicit route files, where it would introduce a second, competing routing idiom.

Migration path. Do not migrate existing routes. Adopt additively:

1. Pin the dependency exactly ("vendor/pkg": "0.0.2") — never a caret range on a 0.0.x line.
2. Create a single new discovery root (e.g. app/Domain/Billing/Actions) and register it inside one route group carrying the target prefix, web/api middleware, auth, and rate limiting.
3. Leave routes/web.php authoritative for everything else.
4. Wrap the registration call in a thin internal helper (one file) so the package can be swapped for a hand-rolled Route::get(...) loop or a first-party equivalent if the dependency stalls.

Compatibility checks to gate on. route:list output parity before/after; route:cache then route:clear round-trip in staging; behaviour under Octane if used; behaviour when the discovery directory is absent (should no-op, not throw); coexistence with any existing auto-discovery package.

Sequencing. (1) Timeboxed spike — one afternoon, one small domain, confirm cache behaviour and naming rules. (2) Route-assertion tests in CI (a test that asserts the expected route set for the discovered directory, so silent disappearance is caught). (3) Documentation of the naming convention in the repo's contributor guide. (4) Roll out to one bounded domain. (5) Re-evaluate at v0.1.0 or first breaking change; only then consider broad adoption.

Operational Impact

Maintenance. Expect churn. A 0.0.x package can change its registration API in a patch release; budget a recurring small upgrade task and keep the adapter layer thin so churn is absorbed in one file. Track release notes deliberately rather than relying on Composer to surface them.

Support. No vendor SLA. Ownership should be assigned to a named engineer or team; if the package is load-bearing for routing, an internal fallback (a ~20-line explicit registration loop) should be documented as the exit path. Exit cost is low today precisely because adoption is additive — preserve that property.

Scaling. Two dimensions. Codebase scale: boot-time discovery cost grows linearly with the number of action files; negligible at tens, worth measuring at hundreds, and mitigated entirely by route caching. Traffic scale: no expected per-request impact if caching is correct — this is a routing-table concern, not a hot-path concern.

Failure modes to monitor.

• Route silently missing after a class rename or namespace move → mitigated by the CI route-set assertion.
• Stale route cache after deploy → ensure route:cache runs in the deploy pipeline, not at container start.
• Unintended public endpoint from a class dropped into the discovery root → mitigated by group-level auth middleware and code review of the discovery directory.
• Duplicate/colliding route definitions resolving to an unexpected handler → mitigated by route:list diffing in staging.
• Package abandonment → mitigated by the adapter layer and pinned version.

Ramp-up. Low for anyone fluent in Laravel routing; the learning cost is almost entirely the naming convention, not an API. One short internal write-up plus a worked example should be sufficient for a mid-level engineer. The subtler ramp-up cost is conceptual: developers must internalise that directory placement is a deployment decision, which is a meaningful shift from explicit route files and warrants deliberate framing in onboarding.