Modular Laravel Package

Product Decisions This Supports

• Modular Architecture for Large-Scale Laravel Apps: Enables teams to decompose monolithic applications into self-contained modules (e.g., auth, payments, analytics), improving maintainability, scalability, and team autonomy. Aligns with Laravel’s native conventions (e.g., packages, service providers) rather than forcing custom patterns.

• Build vs. Buy: Buy: Adopt this package to avoid reinventing module systems (e.g., custom Composer path repositories, auto-discovery logic). Reduces technical debt compared to rolling out a bespoke solution. Build: Consider building a custom solution only if you need dynamic module loading/unloading (e.g., plugin systems for CMS platforms) or non-Laravel-specific features (e.g., cross-framework compatibility).

• Roadmap Priorities:

  • Phase 1: Adopt for organizational clarity in medium/large Laravel apps (50K+ LoC) with distinct feature domains.
  • Phase 2: Extend to microservices decomposition (e.g., splitting modules into standalone packages with shared auth/DB).
  • Phase 3: Integrate with CI/CD pipelines for module-specific testing/deployment (e.g., GitHub Actions workflows per module).

• Use Cases:

  • Team Isolation: Assign teams to own modules (e.g., frontend, backend, integrations) with independent release cycles.
  • Feature Flags: Enable/disable modules via Composer (e.g., experimental features) without code branching.
  • Legacy Refactoring: Gradually migrate monolithic apps by extracting modules incrementally.
  • Third-Party Extensions: Package modules as Composer dependencies for reuse across projects (e.g., shared invoice module).

When to Consider This Package

Adopt This Package If:

• Your Laravel app exceeds 30K–50K lines of code and suffers from:
  • Slow developer onboarding due to monolithic structure.
  • Merge conflicts in shared app/ directory.
  • Difficulty isolating features for testing/deployment.
• You prioritize Laravel-native conventions over custom module systems (e.g., no need for dynamic module enabling/disabling).
• Your team uses Composer and Laravel’s package ecosystem (e.g., auto-discovery, service providers).
• You need IDE support (e.g., PhpStorm integration for Blade components, translations).
• You’re using Laravel 9+ and want minimal boilerplate (e.g., no XML configs, no custom directory structures).

Look Elsewhere If:

• You require dynamic module loading/unloading (e.g., plugin systems where modules can be toggled at runtime). Use nwidart/laravel-modules instead.
• Your app uses non-Laravel frameworks or needs cross-language modules (e.g., Python/Node.js integrations).
• You’re on Laravel <9 or PHP <8.1 (this package drops legacy support).
• You need fine-grained dependency management between modules (e.g., circular dependencies). Consider a monorepo tool (e.g., Laravel Sail + custom scripts) or microservices.
• Your team lacks Composer familiarity or prefers file-based routing (e.g., routes/modules/*.php).

How to Pitch It (Stakeholders)

For Executives/Stakeholders:

"This package lets us build Laravel apps like LEGO blocks—each module is a self-contained feature (e.g., ‘Payments,’ ‘User Profiles’) that teams can develop, test, and deploy independently. Here’s why it’s a game-changer for [Project Name]:

1. Faster Development:

   • Teams work in isolation on modules (e.g., frontend team owns dashboard, backend owns api). No more merge hell in app/Http/Controllers/.
   • Example: Our auth module can be updated without touching the inventory module.

2. Scalability:

   • Add new features as modules without bloating the core app. Example: A marketing module for promotions can be added in hours, not weeks.
   • Modules can later become standalone services (e.g., payments module → separate microservice).

3. Risk Reduction:

   • Break features into small, testable units. Example: The subscription module can be A/B tested independently.
   • Rollback: Disable a faulty module via Composer without redeploying the entire app.

4. Cost Savings:

   • No custom engineering: Avoid 3–6 months of building a module system from scratch. This package is battle-tested by [InterNACHI] (used in production for years).
   • Tooling included: Works with PhpStorm, Laravel Forge, and CI/CD pipelines out of the box.

5. Future-Proof:

   • Aligns with Laravel’s roadmap (supports Laravel 11+). Modules can evolve into composable packages for reuse across products.
   • Example: Our notifications module could be sold as a standalone package to other clients.

Ask: Should we pilot this with our next major feature (e.g., analytics module) to prove the benefits before full adoption?"

For Engineers/Architects:

"This is a lightweight, Laravel-first module system that solves our biggest pain points: organization and scalability. Here’s how it works and why it’s better than alternatives:

Key Features:

• Zero Custom Conventions: Uses Laravel’s existing systems (Composer path repos, package auto-discovery). No XML configs or magic directories.
• IDE-Friendly: PhpStorm integration for Blade components, translations, and route auto-completion.
• Developer Experience:
  • php artisan make:module payments → scaffolds a app-modules/payments/ directory with src/, routes/, database/, etc.
  • Extends Laravel’s make: commands with --module flag (e.g., make:controller UserController --module=auth).
  • Auto-discovers: migrations, factories, policies, Blade components, events, and more.
• Performance: Minimal overhead (caching via modules:cache command).

Why Not nwidart/laravel-modules?

• That package is heavier (custom directory structures, dynamic enabling/disabling).
• This package is lighter and closer to Laravel’s core, reducing friction for teams.

Migration Path:

1. Start by extracting one feature (e.g., auth) into a module.
2. Use modules:sync to update IDE configs and phpunit.xml.
3. Gradually move other features (e.g., reports, api) into modules.
4. Optionally, publish modules as Composer packages for reuse.

Risks/Mitigations:

• Risk: Modules might introduce circular dependencies. Mitigation: Enforce strict module boundaries (e.g., no direct use App\Models\User in modules; use interfaces/DTOs).
• Risk: IDE setup complexity. Mitigation: Run modules:sync once; PhpStorm will auto-detect modules.

Next Steps:

• Spike: Try creating a module for a non-critical feature (e.g., logs) to validate the workflow.
• Tooling: Add modules:list to our deployment scripts to audit enabled modules.
• Documentation: Create a runbook for module creation/deployment.

Ask: Should we allocate a sprint to prototype this with the auth module?"