Modular Laravel Package

Product Decisions This Supports

• Feature Development:

  • Modular Monolith Architecture: Adopt a modular approach to decompose a large Laravel application into smaller, maintainable units (e.g., auth, payments, reports). This aligns with the package’s design philosophy of leveraging Laravel conventions while enabling granular organization.
  • Microservices Prep: Use modules as a stepping stone toward extracting services into standalone packages. The package’s composer.json path repository integration simplifies this transition by treating modules as dependencies.
  • Team-Specific Ownership: Assign modules to cross-functional teams (e.g., frontend, analytics) to parallelize development and reduce merge conflicts. The --module flag in make: commands ensures team-specific assets (e.g., controllers, migrations) are scoped correctly.

• Roadmap Prioritization:

  • Tech Debt Reduction: Prioritize refactoring monolithic features (e.g., user management, billing) into modules to improve testability and scalability. The package’s auto-discovery for migrations, factories, and policies accelerates this effort.
  • Plugin/Extension System: Build a marketplace for internal or third-party modules (e.g., slack-notifications, sms-gateway). The package’s alignment with Laravel’s package system makes this feasible without reinventing discovery mechanisms.
  • CI/CD Optimization: Isolate module builds/deployments to reduce pipeline complexity. The modules:cache and modules:clear commands enable targeted caching strategies.

• Build vs. Buy:

  • Buy: Choose this package over alternatives like nwidart/laravel-modules if:
    • Your team prefers Laravel-native conventions (e.g., no custom directory structures).
    • You prioritize lightweight tooling with minimal overhead.
    • You need Laravel 11+ support and modern features (e.g., Blade component namespaces, event discovery).
  • Build: Consider custom development if you require:
    • Dynamic module enabling/disabling (e.g., CMS plugins).
    • Advanced dependency management between modules (e.g., circular dependencies).
    • Non-Laravel integrations (e.g., Symfony, Lumen).

• Use Cases:

  • Large-Scale Applications: Applications with >50K LoC or >3 teams, where monolithic codebases hinder velocity.
  • Legacy Modernization: Refactoring spaghetti code into modular components without rewriting the entire app.
  • Multi-Tenant SaaS: Isolating tenant-specific logic (e.g., tenant-a/features, tenant-b/features) while sharing core modules.
  • Rapid Prototyping: Quickly scaffold feature modules (e.g., php artisan make:module marketing-campaign) during sprints.

When to Consider This Package

Adopt this package if:

• Your Laravel application is growing in complexity (e.g., >10K LoC, frequent merge conflicts, or slow test suites).
• You want to organize code by feature/domain without sacrificing Laravel’s ecosystem (e.g., Eloquent, Blade, Artisan).
• Your team uses Laravel 9+ and needs modern tooling (e.g., Blade component namespaces, event discovery).
• You plan to extract modules into standalone packages in the future (the composer.json path repository setup facilitates this).
• You prioritize developer experience with minimal learning curve (e.g., familiar make: commands with --module flags).

Look elsewhere if:

• You need dynamic module loading (e.g., enabling/disabling modules at runtime like a CMS). Use nwidart/laravel-modules instead.
• Your stack includes non-Laravel components (e.g., Symfony, Lumen) that require custom integration.
• You require advanced dependency injection between modules (e.g., circular references). This package assumes loose coupling.
• Your team lacks Composer familiarity or struggles with path repositories. The setup adds minor complexity.
• You’re using Laravel <9.x and need legacy support. This package drops support for older versions.

Alternatives to Evaluate:

• nwidart/laravel-modules: Better for dynamic modules but heavier and less Laravel-native.
• Custom Solution: If you need bespoke module isolation (e.g., database schemas per module), build a solution using Laravel’s service providers and package discovery.
• Monorepo Tools: For polyglot projects, consider tools like Bazel or Nx alongside Laravel.

How to Pitch It (Stakeholders)

For Executives:

*"We’re adopting internachi/modular to transform our monolithic Laravel application into a scalable, team-friendly architecture—without rewriting the codebase. Here’s why it’s a no-brainer:

• Faster Development: Teams can work in parallel on isolated modules (e.g., payments, analytics) using familiar Laravel tools like make:controller --module=payments.
• Lower Risk: Modules follow Laravel conventions, so we avoid vendor lock-in or custom tooling. We can even extract modules into standalone services later.
• Cost-Effective: No need to build a custom module system. This MIT-licensed package is battle-tested (1.2K stars) and maintained by InterNACHI, a leader in Laravel tooling.
• Future-Proof: Supports Laravel 11+ and modern features like Blade component namespaces, so we’re not stuck maintaining legacy code. Investment: ~2 weeks to refactor core features into modules. ROI: Reduced merge conflicts, faster onboarding, and the ability to scale the team without slowing down."*

For Engineering Leaders:

*"internachi/modular lets us modularize the app without sacrificing Laravel’s ecosystem. Here’s the ask:

1. Adoption: Refactor 3–5 high-impact modules (e.g., auth, billing) as a proof of concept. Target modules with clear boundaries and minimal cross-dependencies.
2. Tooling: Leverage the --module flag in make: commands to enforce scoping (e.g., make:controller --module=reports). This reduces merge conflicts and makes ownership explicit.
3. CI/CD: Update pipelines to cache modules (php artisan modules:cache) and test them in isolation. The package’s auto-discovery for migrations/factories cuts boilerplate.
4. Migration Path: Use the composer.json path repository setup to eventually extract modules into standalone packages if needed. Why this over alternatives:

• Lighter than nwidart/laravel-modules: No custom directory structures or heavyweight tooling.
• Laravel-native: Works seamlessly with Eloquent, Blade, and Artisan.
• Modern: Supports Laravel 11+, Blade components, and event discovery. Blockers to address:
• Ensure the team is comfortable with Composer path repositories (minimal learning curve).
• Document module boundaries early to avoid circular dependencies."*

For Developers:

*"internachi/modular makes it trivial to organize Laravel apps by feature. Here’s how it works:

• Create a module: php artisan make:module payments → scaffolds a app-modules/payments/ directory with src/, routes/, database/, etc.
• Work in isolation: Use --module=payments with any make: command (e.g., make:controller --module=payments). All assets go in the right place automatically.
• Auto-discovery: Migrations, factories, policies, Blade components, and translations are auto-loaded with namespaced access (e.g., <x-payments::component />).
• Zero config: Just run composer require internachi/modular and start modularizing. Publish the config later if you need custom namespaces. Win for you:
• No more fighting with monolithic app/ directories.
• IDE support (PhpStorm) out of the box via php artisan modules:sync.
• Future-proof: Modules can become standalone packages with minimal effort. Try it:

1. Create a module: php artisan make:module demo.
2. Add a controller: php artisan make:controller UserController --module=demo.
3. Access it via Route::module('demo')->get(...) (or use standard Laravel routing). Docs: GitHub | Walkthrough."*