L5 Modular Laravel Package

Technical Evaluation

What it actually is. L5Modular is a dev-time Artisan generator, not a runtime framework. php artisan make:module scaffolds a module directory (Controllers, Models, Views, Routes, Migrations, ServiceProviders) and wires a convention for module registration. Nothing in the package sits on the request path in production.

Architecture fit. Strong fit for a modular monolith: vertical slices per domain, clear ownership boundaries, fewer cross-team merge conflicts in a shared app/ tree. Weak fit for microservices (irrelevant), for API-only services (only partially relevant — routing works, but the value is mostly in view/controller grouping), and for teams unwilling to enforce a non-default directory convention. This is an all-in architectural decision, not a per-feature one.

Integration feasibility. High on Laravel 8.x, which the package targets. Uncertain from 9 onward, and effectively unverified on 10/11/12 given the July 2021 last release — the Laravel 11 skeleton removed app/Http/Kernel.php, changed provider registration, and moved to bootstrap/app.php, which generator stubs and the package service provider may not account for. Composer install is trivial; the risk is entirely in whether the commands register and whether the stub output matches current idioms.

Technical risk.

• Staleness (primary): 3+ years without a release; no evidence of Laravel 10/11/12 testing.
• No dependents (secondary): zero downstream packages means no field validation — you're the first serious integrator.
• Stub inheritance (tertiary): generated code becomes your code. Any outdated idiom in the stubs (e.g., $namespace handling, old controller signatures, no attribute support) is copied into every new module.
• Low blast radius: as a require-dev dependency with no runtime surface, worst case is "commands don't run" — not an outage.
• MIT license: allows forking and stub surgery if needed.

Key questions.

1. What is the target Laravel version today, and what is the upgrade cadence over the next 18 months?
2. Do we need runtime module loading (dynamic providers, per-module config), or only code organization? L5Modular does the latter; if we need the former, we're in the wrong package.
3. Who owns the fork if we need one, and is that person on the team for the next two major Laravel upgrades?
4. Does the generator touch composer.json autoload/PSR-4 entries, or does it assume a pre-configured modules/ namespace?
5. How do module-scoped migrations, seeders, factories, policies, and tests get discovered — and does that survive route:cache, config:cache, and parallel test execution?
6. Is nwidart/laravel-modules (actively maintained, larger ecosystem) a viable substitute, and if so why are we not choosing it?
7. Do we have an existing modular convention that this would either codify or contradict?

Integration Approach

Stack fit. Laravel monolith or modular monolith, PHP 8.x, team of 3+ engineers who will work in parallel across domains. Poor fit for a single-team CRUD app — the convention overhead exceeds the benefit. Poor fit for a Laravel version above 9 without a compatibility spike.

Migration path (recommended: conditional pilot, not blanket adoption).

1. Compatibility spike (1–2 days). Fresh branch on the target Laravel version: composer require --dev artem-schander/l5-modular, run make:module, inspect every generated file, run route:cache, config:cache, php artisan test. Hard gate: if the command doesn't register or the stubs are broken, stop and go to option B.
2. Option B if the spike fails: fork the repo, update the service provider and stubs to current Laravel conventions, pin the fork by commit SHA. Budget 2–4 days. This is cheap relative to building a generator from scratch, but it makes the fork a permanent asset with an owner.
3. Option C: evaluate nwidart/laravel-modules first — it has active maintenance, Laravel 11/12 support, and a larger community. If it meets requirements, L5Modular is redundant.
4. Pilot one bounded context (e.g., Billing or Notifications), not a core domain. Run it for one sprint alongside existing structure.
5. Codify conventions in an ADR: module namespace, registration, migration ordering, cross-module communication rules (events over direct model access), and where shared code lives.
6. Roll out per domain, one module per PR, with a reviewer checklist.
7. Schedule a re-evaluation at the next Laravel major upgrade.

Compatibility checklist before adopting.

• Artisan auto-discovery registers the provider.
• composer dump-autoload picks up the modules/ PSR-4 namespace after generation.
• Generated migrations are discovered and ordered correctly.
• Module routes survive route:cache and don't collide on names.
• Tests in modules are discovered by PHPUnit/Pest.
• No conflict with Laravel 11's bootstrap/app.php structure.

Sequencing. Spike → decide (adopt / fork / substitute / decline) → ADR → pilot → conventions doc → rollout. Do not sequence this behind a feature deadline; the fork decision needs calendar space before the team depends on it.

Operational Impact

Maintenance. Low code volume but non-zero ownership. The package is a dev dependency, so upgrades are only triggered by Laravel majors or PHP version bumps — realistically 1–2 days per major upgrade to validate commands and refresh stubs. If forked, that ownership is permanent and must be assigned to a named engineer, not "the team."

Support. No vendor, no SLA. Community support is a GitHub issue tracker with a 2021-era backlog and 216 stars — expect self-service. Zero dependents means negligible Stack Overflow or blog coverage; debugging is reading the source, which is small and tractable. Documentation is thin; onboarding relies on internal docs and pairing.

Scaling. Technically trivial — modules are directories, and the generator doesn't run in production. Organizationally, this is the actual value: parallel teams working in isolated namespaces reduce merge conflicts and clarify ownership. The scaling risk is social, not technical — too many modules without a cross-module contract produces a distributed monolith with hidden coupling inside one repo, which is worse than a plain Laravel app because boundaries look enforced but aren't.

Failure modes.

• Command not registered after a Laravel upgrade (provider signature or discovery change) — silent, discovered when someone tries to scaffold.
• Stale stub output — generates controllers/routes that don't match current idioms; spreads quietly across every new module.
• PSR-4 / autoload gaps — generated classes not found until composer dump-autoload, or namespace mismatch between stub and composer.json.
• Class name collisions across modules (two UserService classes) — surfaces as confusing resolution bugs.
• Migration ordering issues across modules if filenames share timestamps.
• Route name collisions when multiple modules register similarly named routes.
• Boundary erosion — developers reaching across module namespaces directly instead of via events/contracts, undetected until refactor time.
• Fork drift — the fork silently diverges from upstream, and nobody notices until an upgrade.

Ramp-up. Roughly half a day for a Laravel-fluent engineer to be productive: run a generator, read the output, follow the ADR. The learning cost is not the tool — it's the conventions: what belongs in a module, how modules talk to each other, where shared utilities live. Budget a pairing session on the first real module and a short internal README, because upstream docs won't cover your specific structure.