Modular Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Modularity: The package aligns seamlessly with Laravel’s existing conventions (packages, service providers, auto-discovery), reducing cognitive overhead for developers familiar with Laravel. This avoids the "anti-pattern" of forcing a non-standard structure (e.g., nwidart/laravel-modules’s rigid module hierarchy).
• Composer Path Repositories: Leverages Laravel’s package discovery via Composer, ensuring modules are treated as first-class citizens in the dependency graph. This simplifies IDE support (PhpStorm, VSCode) and tooling integration.
• Lightweight Abstraction: Unlike monolithic monorepos or heavy frameworks, this package adds minimal overhead—modules are just Laravel packages with a standardized directory (app-modules/). Ideal for medium-to-large Laravel apps where organization is critical but extraction flexibility is desired.
• Extraction-Friendly: Modules can be converted to standalone packages with minimal refactoring (e.g., changing Modules\ namespace to a vendor prefix). The MIT license and lack of dependents suggest low vendor lock-in.

Integration Feasibility

• Zero-Config Setup: Auto-discovery via Laravel’s package system means no manual bootstrapping (e.g., no need to register modules in config/app.php). The composer update step after module creation is the only explicit action required.
• Tooling Compatibility:
  • Artisan: Extends all make: commands with --module= flags, preserving existing workflows (e.g., make:controller --module=users).
  • Migrations/Seeders: Integrates with Laravel’s migrator and seeder systems natively (no custom CLI needed).
  • Blade/Views: Supports component namespaces (<x-module::component>) and anonymous components, matching Laravel’s Blade ecosystem.
  • Testing: Syncs with phpunit.xml and PhpStorm configs to avoid IDE misconfigurations.
• Database Layer: Migrations, factories, and seeders are auto-discovered, but no built-in module-specific database isolation (e.g., schema prefixes). This is intentional—modules are for organization, not isolation.

Technical Risk

• Laravel Version Lock: Requires Laravel 11+ (as of v2.2.0). If migrating from older versions, this may necessitate a full Laravel upgrade.
• Composer Path Repository Quirks:
  • Windows Path Handling: Historical fixes (e.g., v1.10.0) suggest edge cases may exist for Windows users.
  • Performance: Scanning app-modules/ for auto-discovery could slow large projects. The modules:cache command mitigates this but adds operational complexity.
• IDE Dependencies: PhpStorm sync relies on the Laravel plugin. VSCode users may need manual settings.json adjustments for path resolution.
• No Dynamic Module Loading: Unlike nwidart/laravel-modules, modules cannot be enabled/disabled at runtime. This is a design choice (focus on organization, not CMS-like extensibility), but could limit use cases requiring runtime flexibility.
• Testing Gaps: While modules support factory() and make:test, no built-in module-specific test isolation (e.g., parallel test execution). Tests run in the global app context.

Key Questions for Adoption

1. Project Scale:
   • Is the app large enough to justify modularity (e.g., >50K LoC, >3 teams)? For small projects, the overhead may not be worth it.
   • Are modules needed for organization (current use case) or runtime isolation (would require nwidart/laravel-modules)?
2. Laravel Version:
   • Can the team upgrade to Laravel 11+? If not, v1.x of this package (supporting Laravel 7–10) may be viable but lacks recent updates.
3. Extraction Plans:
   • Will modules need to be converted to standalone packages later? The namespace config (InterNACHI\ example) hints at this, but the process isn’t documented.
4. CI/CD Impact:
   • How will composer update modules/* affect CI pipelines? Caching strategies (e.g., modules:cache) may be needed.
5. Third-Party Modules:
   • Are any modules expected to be shared across projects? This package doesn’t support Composer package distribution out-of-the-box (unlike nwidart/laravel-modules).
6. Database Strategy:
   • How will shared vs. module-specific databases be handled? No built-in support for schema prefixes or multi-tenancy.
7. Legacy Code:
   • How will existing non-modular code (e.g., in app/) interact with modules? No forced migration path—teams must opt in per feature.

Integration Approach

Stack Fit

• Laravel 11+: Native support for Laravel’s package discovery and Composer 2.x. Avoids polyfills or compatibility layers.
• PHP 8.1+: Aligns with Laravel’s minimum requirements (v2.0.0 dropped PHP 7 support).
• Tooling:
  • IDE: PhpStorm/VSCode integration via modules:sync (auto-updates IDE configs).
  • Testing: Works with Pest/PHPUnit via auto-discovered test namespaces.
  • Frontend: Blade components and Livewire support (if installed) integrate seamlessly.
• Database: PostgreSQL/MySQL/SQLite—no vendor-specific features. Migrations use Laravel’s standard system.

Migration Path

1. Assessment Phase:
   • Audit existing codebase for monolithic app/ directory usage. Identify candidates for modularization (e.g., Users, Payments, Reports).
   • Decide on namespace strategy (e.g., App\Modules\ vs. InterNACHI\).
2. Setup:
   • Install the package: composer require internachi/modular.
   • Publish config: php artisan vendor:publish --tag=modular-config (customize namespace).
   • Run sync: php artisan modules:sync (updates phpunit.xml, PhpStorm configs).
3. Incremental Migration:
   • Option A (Big Bang): Create all modules upfront (risky for large apps).
   • Option B (Phased):
     • Start with one module (e.g., Users).
     • Move files incrementally (e.g., app/Http/Controllers/UserController.php → app-modules/users/src/Http/Controllers/UserController.php).
     • Update imports and references (use IDE refactoring tools).
     • Test thoroughly before moving to the next module.
   • Option C (Greenfield): New projects can adopt this from day one.
4. Post-Migration:
   • Cache modules: php artisan modules:cache (improves performance).
   • Document the module structure and naming conventions for the team.

Compatibility

Sequencing

1. Core Infrastructure:
   • Install package, publish config, run modules:sync.
   • Set up CI/CD to handle composer update modules/*.
2. Module Creation:
   • Start with **high-cohesion, low-cou