Laravel Features Laravel Package

Technical Evaluation

Architecture fit This package adds a feature module layer on top of Laravel's existing service-container and service-provider model: each feature owns its own routes, commands, translations, seeders, migrations, and declared dependencies. v1.1.0 materially strengthened that fit — feature-scoped console commands (#107) and translations (#108) moved it from "routing convention" to "module boundary." v1.2.0 extends the boundary outward with a boot hook extension point (#115): third-party or cross-cutting code can now attach behaviour to a feature's boot phase without editing the feature itself. For a TPM this is the second interesting release in a row — it is the difference between a module system you structure code with and a module system other packages can integrate against. That is the point at which the package starts to look like a platform primitive rather than an internal convention, and it is also the point at which its boot semantics become something we have to reason about and test, not just adopt.

Integration feasibility Still low-to-moderate. Composer install plus a published config and a features directory; no external service, no data store, no queue or scheduler dependency. The 1.2.0 changes are additive: an extension point we can choose to ignore, plus an internal review pass. We do not have to adopt hooks on day one, and the 1.1.0 capabilities we were already buying (per-feature command registration, translation loading, seeder discovery fix) are unchanged in shape.

Two caveats sit on the review pass (#117). It touches registry, discovery, route groups, and disk — four of the five subsystems our spike is meant to validate — one minor release after those subsystems were introduced. That is normal hardening, but it means our staging validation must be run against 1.2.0 specifically, not inherited from a 1.1.0 spike. The mention of disk is also the first indication of a filesystem concern in this package; the previous assessment assumed zero infrastructure footprint, and we should confirm whether that is an internal path-resolution fix or something that expects a configured disk.

Technical risk

• Bus factor (unchanged, now higher-leverage). Both 1.2.0 changes and the prior release's four changes come from a single maintainer. Adding a public extension point raises the cost of that maintainer going quiet: hooks create a contract other code depends on, and contracts are harder to inline or fork away than conventions.
• Boot-time extension surface. Hooks execute during feature boot. Arbitrary code in the boot path is the highest-blast-radius place to put arbitrary code — a throwing hook fails the feature, possibly the app, and reproduces only on cold cache.
• Hook ordering and isolation. Hooks imply an order (per feature? per package? registration order?) and a failure policy (fail-fast vs. isolate). Neither is stated in the notes. Until documented, our assumption should be "undefined and app-fatal."
• Discovery churn. The review pass landing immediately after the discovery features means we should treat 1.1.x and 1.2.0 as behaviourally distinct in registry/discovery/route-group handling until proven otherwise. Regression, not breakage, is the realistic risk.
• Discovery magic (unchanged). Commands and translations are auto-registered; implicit registration makes boot order and collision behaviour non-obvious when debugging. Hooks add a second implicit mechanism on top of the first.
• Minor-version surface change (unchanged). 1.1.0's translation loading still changes runtime behaviour for any feature that registers translations manually. Nothing in 1.2.0 retires that risk.

Key questions

1. Supported Laravel/PHP matrix — does it cover our current major and our next-upgrade target? (Unchanged, still unanswered.)
2. What is the documented feature dependency/ordering model, and does it detect cycles? Hooks make this more urgent: is boot order dependency-derived, registration-derived, or undefined?
3. What is the hook contract — signature, return value, per-feature scoping, ordering guarantees, and whether a hook can cancel or short-circuit feature boot?
4. What is the failure policy for a throwing hook — fail-fast, isolate-and-log, or silent skip? Is there any per-hook error boundary?
5. What did #117 change behaviourally in registry, discovery, route groups, and disk, and is there a changelog or test delta we can diff against 1.1.0?
6. What does "disk" mean here — internal path resolution, or a configurable filesystem/storage dependency we must provision?
7. Collision policy for duplicate command signatures and duplicate translation keys across features — fail loudly or last-wins? (Unchanged.)
8. Is discovery cached (and cache-busted) for production, and what is the boot-time cost at N features — now with hooks in the boot path?
9. Test coverage and CI matrix on the package itself; is there a tagged support window for 1.0.x?

Integration Approach

Stack fit Native Laravel, Composer-only, no frontend footprint. The one thing to re-verify post-#117 is the filesystem assumption — if the package now expects a configured disk or a writable path outside storage/, that is a small but real deployment constraint we should catch in staging rather than in production. It remains complementary to, not a replacement for, package-level modularity; we should still not run two discovery systems over the same directories. Hooks give us a sanctioned way to inject cross-cutting behaviour into features, which is preferable to the alternative we would otherwise reach for (editing each feature or adding a custom loader).

Migration path

• Greenfield: adopt conventions from day one; lowest cost, highest payoff. Hooks stay unused until a concrete need appears.
• Brownfield: lift one existing vertical (billing or notifications) into a feature first. Do not big-bang refactor app/ — feature extraction is incremental and each slice is independently revertible.
• Pinned adoption: floor at 1.1.0 for the seeder fix and translation loading; gate 1.2.x on a regression pass against 1.1.x covering registry/discovery/route-group behaviour. Once that passes, pin ^1.2 so we are not carrying a version we have already validated out of.
• Hooks: adopt on a second wave, and only for behaviour that is genuinely cross-cutting. Do not let hooks become the default integration style for intra-app wiring.

Compatibility Validate against our other discovery-based packages (Livewire/Volt/Folio-style auto-registration) and against config:cache, route:cache, and optimize in staging before production. Confirm command registration does not collide with first-party artisan commands. Confirm translation namespacing matches our i18n tooling and does not break string extraction. New: if we adopt hooks, confirm they run under a fully warmed cache in the same order as on a cold boot, and that a hook registered by a third-party package cannot silently outrank our own.

Sequencing

1. Regression check (small, blocking): run the existing 1.1.x spike branch against 1.2.0; diff route registration, command list, translation resolution, and seeder discovery. This is the gate for pinning forward.
2. Spike: branch-only proof of concept — one feature with a route group, one command, one translation file, one seeder chain, and (optionally) one boot hook to observe ordering and failure behaviour.
3. Deploy-pipeline check: full optimize + route:cache + config:cache in staging; confirm no duplicate-signature boot failures and no disk-path errors.
4. First real slice: migrate a low-blast-radius feature; keep the old code path behind a flag for one release.
5. Convention rollout: document feature layout, dependency declaration, collision rules, and — if adopted — the hook usage policy (what belongs in a hook and what does not) in our own engineering guide.
6. Scale-out: subsequent slices, then reassess whether a second module system is still needed.

Operational Impact

Maintenance Low ongoing cost: small codebase, low release cadence, automated dependency bumps. Cost is in governance, not upkeep — we need an internal owner for the feature conventions, and now also for the hook policy, otherwise hooks become an unowned cross-cutting layer that nobody can safely remove. The #117 review pass is a positive signal on maintainer diligence but also a reminder to read the diff rather than the release notes.

Support Community-supported with a single dominant maintainer. The exit calculus is now slightly worse than at 1.1.0: conventions are easy to inline, but a published hook contract invites third-party usage that we would have to shim if we forked or inlined. That exit cost should be documented before broad adoption and before we allow hooks into shared packages, not after.

Scaling Two scaling axes, plus a new one. Feature count: boot-time and discovery overhead grow with N; production discovery caching is mandatory, not optional. Translation volume: per-feature translation loading increases memory and lookup precedence complexity — measure past a few dozen features. Hook count: unlike the other two, hooks scale with integration surface rather than feature count, and each hook is code in the boot path on every request — this is the axis most likely to produce a latency surprise, and the one with the least visibility today. Command registration also grows the artisan command list, affecting artisan list responsiveness and help output quality.

Failure modes

• Duplicate artisan command signature across features → container boot failure, whole app down. Needs a CI assertion.
• Throwing boot hook → feature (or app) fails to boot; cold-cache-only reproduction. Needs a CI assertion if hooks are adopted, and a documented policy either way.
• Hook ordering nondeterminism → behaviour differs between cold and warm cache. Verify in the deploy-pipeline check.
• Duplicate/overlapping translation keys → silent last-wins override; a user-visible localization bug with no error signal.
• Feature dependency misordering or a cycle → intermittent boot failures that reproduce only on cold cache.
• Registry/discovery/route-group regression from #117 → routes or commands silently not registering. This is the specific reason the 1.1.x → 1.2.0 regression check is a blocking step rather than a nice-to-have.
• Seeder discovery: the ::class case is fixed in 1.1.0, but dependency ordering between seeders remains a sharp edge in non-production environments.
• Route group closures executing at registration time → a thrown exception inside a group callback takes down routing entirely rather than failing one route. Unchanged in kind, but the area was touched in #117.

Ramp-up Modest for anyone fluent in Laravel service providers — the concepts map directly. The real ramp-up is the discovery mental model: engineers must internalize that commands, translations, routes, and seeders are picked up implicitly, and know where to look when something is not registered. If hooks are adopted, add a second mental model — "code that runs because a feature booted, not because a file was found." Budget a short internal write-up plus one exemplar feature and one exemplar hook in the repo; that artifact will carry more weight than the package docs.

TPM recommendation Hold the current ^1.1 pin, run a one-day regression check of the existing spike branch against 1.2.0 (registry, discovery, route groups, disk), then pin forward to ^1.2 if it is clean. Do not introduce boot hooks during the first wave — treat them as a second-wave decision gated on documented ordering and failure semantics. Do not standardize the whole codebase until the first two slices have shipped and the discovery model has survived one on-call rotation.