Product Decisions This Supports
- Convention-over-configuration routing for action classes. v0.0.2 adds directory route loading, meaning a folder of single-purpose action classes can map to routes without hand-writing entries in
routes/web.php. This directly supports decisions about how much routing boilerplate we tolerate as the endpoint surface grows.
- Build vs. buy for internal routing glue. Teams frequently write bespoke route-scanning/registration code for admin panels, webhook endpoints, form handlers, and dashboard widgets. This package is a candidate to replace that homegrown glue — worth evaluating before we commission another internal helper.
- Architecture roadmap: standardising on invokable actions. Adoption is really a decision about whether "one action class = one endpoint" becomes a house convention. That choice affects onboarding docs, code review checklists, testing patterns, and how new hires navigate the codebase.
- Scaffolding velocity for CRUD-heavy surfaces. Directory-based loading makes adding an endpoint a "drop a file in the folder" operation, which is a measurable win for teams shipping many small, low-complexity endpoints (internal tools, back-office, prototypes).
- Risk posture for dependency selection. At v0.0.2 the package is pre-1.0 with no semver guarantees. That makes this a pilot/spike decision, not a platform commitment — it should be scoped to a bounded module, pinned to an exact version, and wrapped behind an internal convention so it can be swapped out.
- Release planning input. The delta here (one feature, additive) is small and non-breaking, but the 0.0.x version line itself is the signal: budget for churn and re-review on every bump rather than treating this as a stable foundation.
When to Consider This Package
Consider it when:
- You already write (or want to write) single-action/invokable controllers and dislike maintaining large, merge-conflict-prone route files.
- You have a high volume of simple, similarly-shaped endpoints — CRUD resources, webhook receivers, dashboard widgets, small JSON APIs — where file-to-URL mapping is predictable and low-ambiguity.
- You want to codify a convention (folder structure implies route) so that adding an endpoint requires no routing decision-making.
- You can absorb pre-1.0 instability: you're willing to pin exact versions, run a timeboxed spike in one non-critical module, and keep the integration behind a thin internal abstraction.
- Your team is comfortable with implicit behaviour and has the tooling to make it observable (
php artisan route:list, coverage on route registration, clear naming rules for the directory scan).
Look elsewhere when:
- You need API stability, a security policy, or long-term support — a 0.0.x package with a single maintainer and two releases is not that.
- Your routing needs are non-trivial: heavy per-route middleware, route model binding with custom keys, domain/subdomain routing, versioned APIs, localisation prefixes, or nuanced route-cache behaviour. Convention-based loading tends to get in the way exactly where routing gets interesting.
- You already have substantial investment in explicit route files and route-review practices; converting is a migration cost with unclear payback.
- Debuggability is paramount — implicit route registration can make "where does this URL come from?" harder to answer, which is a real cost in incident response and audits.
- You need performance guarantees under route caching; verify that directory scanning is compile-time/cached rather than per-request before committing.
Minimum due diligence before adoption: confirm the scanning is route-cache safe, confirm how conflicts (two actions resolving to the same URI) are surfaced, confirm middleware can be attached per directory or per action, and check the maintainer's release cadence and issue responsiveness.
How to Pitch It (Stakeholders)
For executives: This is a small, cheap experiment in reducing boilerplate, not a platform bet. A Laravel package at v0.0.2 now supports mapping a directory of small handler classes directly to routes, which is the kind of work our engineers currently hand-write and maintain. The upside is developer throughput on the many small endpoints that make up internal tools and back-office features. The downside is maturity: at version 0.0.2 there are no compatibility guarantees, so it belongs in a timeboxed pilot on one low-risk module with a defined exit criterion — not on a critical path. Cost of trying is low; cost of standardising prematurely is a rewrite plus the migration of everything built on top of it.
For engineering: The package pairs an invokable-action pattern with convention-based route registration — drop an action class into a directory and it becomes an endpoint. That removes route-file churn and merge conflicts, and makes endpoint addition a mechanical, reviewable operation. Two things to validate in the spike: (1) that route discovery is cached and doesn't add per-request filesystem work, and (2) that route conflicts and middleware attribution are explicit enough to debug at 2am. Mitigations are straightforward — pin the exact version, keep the integration behind our own registration helper so the dependency is replaceable, require route:list snapshots in review, and document the naming rules. If the spike holds, we get a convention we control; if it doesn't, we've spent a few days and learned what our internal helper should look like.