Modular Laravel Package

Product Decisions This Supports

• Monolith decomposition without service extraction: This package lets a large Laravel app adopt module boundaries incrementally inside one deployable unit. As a PM, this is your lever for slowing the “rewrite into microservices” pressure while still giving teams ownership boundaries — a much cheaper path than a distributed-system migration when the real problem is code organization, not scaling.
• Team topology and ownership mapping: Because modules live in app-modules/ and are autoloaded as Composer path repositories, you can map module directories to squad ownership. This supports decisions about how many teams you can run in parallel, where handoffs happen, and how to onboard new engineers (a module is a bounded, readable slice of the product).
• Build vs. buy on modularity tooling: The package is deliberately thin and rides on Composer path repositories plus Laravel package discovery rather than inventing a parallel architecture. That makes the build-vs-buy call easy: adopt the package, and avoid spending engineering quarters building an internal module framework with its own conventions and maintenance burden.
• Feature isolation for roadmap planning: Domain features (billing, notifications, catalog, reporting) can be scoped as modules with their own routes, migrations, factories, policies, Blade components, translations, and tests. This gives you a planning unit that maps to a shippable slice of roadmap, and makes “can we ship X without destabilizing Y” a more tractable question.
• Future option value on package extraction: The README explicitly recommends configuring an organization namespace instead of the default Modules\ so a module can later be extracted into a standalone Composer package. That is a real strategic option to preserve — it keeps open the possibility of publishing internal capabilities, sharing code across apps, or spinning out a component later without a rewrite.
• Tooling-adoption decisions for DX: The package extends most make: commands with a --module= flag and adds modules:sync for phpunit.xml and PhpStorm configuration. That means you can standardize developer workflows on existing Laravel habits and custom stubs rather than retraining teams on a bespoke CLI — relevant when evaluating whether a productivity initiative will actually land.
• Test and CI investment decisions: Modules get their own test suite registered into phpunit.xml by modules:sync. This supports decisions about per-module CI gates and test ownership, which is often the difference between module boundaries that hold and boundaries that rot.
• Ecosystem maturity / risk posture: MIT licensed, actively released (latest release dated 2026-03-23), 1.2k GitHub stars, readme + changelog + releases present, but zero dependents and a comparatively modest opportunity score. That combination supports a “tactical adoption with an exit ramp” decision rather than a strategic platform bet.

When to Consider This Package

Consider it when:

• You have a large Laravel monolith where app/ has become a shared dumping ground, cross-team merge conflicts are frequent, and ownership is unclear.
• You want modules for organization, not for runtime plugin semantics. The README is explicit that this is the sweet spot.
• Your team is already fluent in Laravel conventions and values staying close to them — the package deliberately avoids its own directory structure.
• You want minimal framework surface area: Composer path repositories and Laravel package discovery do most of the work, with light tooling filling gaps.
• You are willing to run composer update modules/<name> as part of module creation, and you are comfortable treating modules as Composer dependencies.
• You want modules that can later become standalone packages, and you are willing to set an organization namespace up front.
• You need auto-discovery to just work for commands, migrations, factories, policies, Blade components, event listeners, and translations without custom wiring.

Look elsewhere when:

• You are building a CMS or platform that requires third-party modules to be dynamically enabled/disabled at runtime. The README itself points to nwidart/laravel-modules for this; Modular is not a plugin system.
• You need per-module activation, marketplaces, or module lifecycle management as product features.
• You need heavyweight isolation — separate databases per module, independent deployability, or hard runtime boundaries. That is a service extraction or multi-repo decision, not this package.
• You require a large dependents base as a risk signal. Zero dependents and modest community adoption mean you should assume you may be largely on your own for edge cases, and budget for that.
• Your team is not on a modern Laravel version or cannot adopt Composer path repositories in the build pipeline (for example, constrained deployment tooling that dislikes path repos).
• Your primary pain is deployment coupling or scaling, not code organization. Modules in one app do not solve those.

A reasonable adoption stance: pilot on a single non-critical domain module, measure merge-conflict reduction and onboarding time, and keep the organization-namespace discipline so the exit ramp stays open.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, low-risk organizational change for our Laravel application. Instead of a multi-quarter microservices rewrite, we can carve our monolith into named, owned modules inside the existing app. It is MIT licensed, actively maintained, and deliberately small — it leans on standard Composer and Laravel mechanisms rather than inventing a new architecture we would have to maintain. The main caveat is limited third-party adoption, which we mitigate by piloting on one domain and preserving an extraction path.

For engineering leadership: We get module boundaries that map to teams, with each module containing its own routes, migrations, tests, factories, policies, Blade components, and translations. Auto-discovery covers the common Laravel extension points, and existing make: commands gain a --module= flag, so developers keep their current workflow and custom stubs. modules:sync wires up phpunit.xml and IDE configuration, and modules:cache exists if discovery overhead becomes measurable. We should publish the config and set an organization namespace so modules can be lifted into standalone packages later.

For engineering teams: Think of a module as a Laravel package that lives in app-modules/ and is registered as a Composer path repository. You scaffold with make:module, run composer update modules/<name>, and then work exactly as you do today — just with a --module= flag on the generators you already use. Boundaries are conventions plus Composer, not a new runtime, so there is very little to learn and very little magic to debug.

Known trade-offs to state up front: no runtime enable/disable of modules (use nwidart/laravel-modules if that becomes a product requirement), zero recorded dependents so we should expect to handle edge cases ourselves, and module creation touches composer.json, which means the build pipeline must tolerate path repositories.