Laravel Modules Laravel Package

Technical Evaluation

Architecture fit. sinemacula/laravel-modules is a modularisation layer for Laravel applications, giving each module its own namespace, service providers, routes, migrations, resources, and now model factories. v1.4.0 continues a maturation trend rather than a feature-expansion trend: three of the seven fixes are about failing gracefully and reporting accurately (cache write failures no longer crash, unusable manifests are ignored, empty resource paths are reported), and one is about path canonicalisation. For a TPM, this signals the package is moving from "works in the happy path" to "survives messy enterprise filesystems and CI environments" — a good signal for adoption in multi-team codebases where modules are authored by different squads.

Integration feasibility. Low friction. No new required dependencies, no configuration schema changes called out, and the changes are additive or defensive. The two features most likely to touch our code are:

• Factory-by-convention resolution (#66) — modules can now resolve Database\Factories without explicit registration. This is opt-in in practice (you only benefit if you use conventional naming), but it can silently change which factory a test picks up if a module has a factory whose name collides with a conventionally-resolved one.
• Discardable module base path (#78) — relevant if we serve modules from a path that should not appear in generated URLs, asset paths, or resource resolution. Needs a config review, not a code change.

Technical risk. Assessed as low-to-moderate. There are no BREAKING CHANGE footers and the release is a minor bump, consistent with SemVer. The residual risk is behavioural rather than API-level:

1. Manifest handling change (#77) — "use the module manifest only while it is usable" implies previously the package might have consumed a stale or partially-written manifest. Behaviour under concurrent deploys or cache-clearing races may differ. Worth a targeted test of our deploy pipeline.
2. Base path canonicalisation (#70) — path normalisation fixes can change resolved paths on Windows agents or symlinked release directories (e.g. Capistrano/Deployer current symlinks). This is the single highest-value thing to verify in our environment.
3. Cache write failure handling (#69) — now reports instead of throwing. Error-swallowing can mask misconfigured cache permissions; we should ensure the reporting channel actually surfaces to our logs/alerting.

Key questions for the maintainer / our own spike.

• Does #77 alter behaviour when the manifest exists but is mid-write — is it skipped, regenerated, or does it fall back to filesystem scanning (with the associated performance cost)?
• Is the factory convention resolution (#66) opt-in via config, or automatic on namespace match? What is the precedence order versus an explicitly declared $model on the factory?
• What is the exact semantics of "discard the module base path" (#78) — URL generation only, or also filesystem resolution?
• Does the standards-compliant stub change (#67) alter generated file contents in a way that would produce large diffs against our existing modules if we re-run generators?
• Is there a supported upgrade note for the php-cs-fixer pin (#82) that affects our own linting pipeline if we share the config?

Integration Approach

Stack fit. Targets Laravel's service-provider and package-discovery model, so it drops into a standard Laravel app with no bootstrap surgery. It is a convention package — the cost of adoption is agreeing on module boundaries and naming, not wiring. v1.4.0's factory convention and stub standardisation both reduce the amount of per-module boilerplate our teams write, which is the main long-term maintenance win here.

Migration path. Adopt incrementally, not big-bang:

1. Upgrade in a feature branch; run the full test suite with --parallel disabled first (to expose any factory-resolution ordering effects from #66).
2. Diff generated output from the module generator against an existing module to size the stub change (#67).
3. Exercise the deploy pipeline end-to-end in a staging environment that mirrors production path layout, including symlinked release directories, to validate #70 and #77.
4. Only then enable base-path discarding (#78) per module, starting with one non-critical module.

Compatibility. No PHP or Laravel version constraints are signalled as changed by this release. The php-cs-fixer pin (#82) is dev-tooling only and should not affect runtime consumers, but it may cause a CI diff if we vendor a shared style config. Confirm the package's supported Laravel range against our current major before scheduling — this is the one item the release notes do not answer and it gates everything else.

Sequencing. Treat v1.4.0 as a stability upgrade, not a feature upgrade. Slot it into the next routine dependency-bump window rather than a dedicated project. The only candidate for pulling forward is #69/#77 if we have observed flaky behaviour around module caching or manifest reads — in that case, prioritise it, because those are the two fixes that convert a crash into a diagnosable event.

Operational Impact

Maintenance. Net reduction in toil. Standardised stubs (#67) mean fewer one-off module skeletons drifting apart; convention-based factories (#66) remove a class of "why can't my test find the factory" tickets. The php-cs-fixer pin and git-hook reliability work (#64, #82) point at a maintainer who is investing in reproducible CI — a positive leading indicator for the package's longevity.

Support. Diagnostics improve materially in this release: rewritten module names are reported (#79), resource paths pointing at empty modules are reported (#72), and cache write failures are reported rather than thrown (#69). Each of these converts a previously opaque failure into an actionable message. The open question is where those reports land — we must confirm they route into our existing log aggregation and are not silently swallowed at a verbosity level we don't run in production.

Scaling. Module count is the scaling axis, and two changes matter: manifest usability handling (#77) affects cold-start and cache-warm behaviour as module count grows, and base-path discarding (#78) matters for any module served from a shared or deep directory tree. Neither introduces new scaling cost; #77 plausibly removes one (repeated manifest reads). Recommend a light benchmark at our current module count and at roughly 2x, comparing cold request latency before and after the upgrade.

Failure modes to watch.

• Silent cache degradation — #69 reports instead of crashing; if reporting is quiet, cache writes could fail continuously and we'd fall back to slower resolution with no alarm. Add an explicit assertion or health check.
• Stale manifest acceptance — #77 should prevent this, but verify the boundary: what happens when the manifest is valid but out of date relative to the filesystem?
• Factory misresolution in tests — convention-based lookup can pick an unexpected factory in a module with ambiguous naming. Low blast radius (tests only), but it can produce confusing false passes.
• Path divergence across environments — #70's canonicalisation is the classic source of "works locally, fails in CI" bugs. Pin the verification to a CI run on the same OS/agent image we use in production deploys.

Ramp-up. Minimal. A developer familiar with Laravel package conventions can be productive in under a day; the module layout is the only new mental model. Plan roughly 1–2 engineer-days for the upgrade, dominated by the staging validation of #70/#77 rather than by code changes, plus a short internal note documenting the factory convention and the base-path option so teams don't independently discover and configure them inconsistently.