Modular Laravel Package

Technical Evaluation

Architecture Fit

• Modularity Alignment: The package aligns well with Laravel’s native conventions (e.g., package discovery, Composer autoloading) while introducing a lightweight modular structure (app-modules/). This avoids reinventing Laravel’s ecosystem (e.g., service providers, facades) and leverages existing tooling (e.g., make:, migrations, Blade components).
• Convention Over Configuration: The package enforces minimal conventions (e.g., Modules\ namespace, app-modules/ directory) but allows customization via config publishing. This reduces boilerplate while maintaining flexibility.
• Laravel Ecosystem Integration: Deep integration with Laravel’s core features (e.g., Artisan commands, Blade components, translations, event listeners) ensures seamless adoption without breaking existing workflows.

Integration Feasibility

• Low Friction Adoption: Auto-discovery and zero-config setup (via composer require) minimize initial integration effort. The modules:sync command further reduces manual configuration (e.g., PhpStorm, PHPUnit).
• Backward Compatibility: Supports Laravel 11+ and PHP 8.1+, with clear deprecation paths for older versions. No breaking changes to Laravel’s core or third-party packages (e.g., Livewire, Breadcrumbs).
• Isolation: Modules are treated as Composer path repositories, enabling independent versioning and updates without affecting the monolith. This aligns with microservices-like isolation but within a single codebase.

Technical Risk

• Namespace Collisions: Customizing the default Modules\ namespace (via config) mitigates risks, but poorly named modules could still cause conflicts. Mitigation: Enforce organization-specific prefixes (e.g., App\Modules\).
• Tooling Dependencies: Relies on Laravel’s package discovery and Composer path repositories. Potential issues if these systems evolve (e.g., Composer 2.x quirks). Mitigation: Monitor Laravel/Composer updates and test against pre-release versions.
• Performance Overhead: Module auto-discovery adds minor runtime overhead (e.g., scanning app-modules/). The modules:cache command optimizes this, but large projects may need profiling. Mitigation: Benchmark in staging before production.
• IDE Support: While modules:sync improves PhpStorm integration, other IDEs (e.g., VSCode) may require manual configuration. Mitigation: Document IDE-specific setups in the team’s onboarding.

Key Questions

1. Migration Strategy:

   • How will existing monolithic codebases migrate to modules? Should we adopt a big-bang (all-at-once) or incremental (module-by-module) approach?
   • Will we need to refactor legacy code to fit module conventions (e.g., namespaces, directory structure)?

2. Dependency Management:

   • How will we handle module-specific dependencies (e.g., composer.json per module)? Will we use Composer’s replace or provide to avoid duplication?
   • How will we manage shared dependencies between modules (e.g., shared libraries, configs)?

3. Testing and CI/CD:

   • How will we structure tests for modules? Will we use module-specific test suites (e.g., phpunit.xml per module) or a monolithic suite with namespaced tests?
   • How will CI/CD pipelines handle module updates? Will we use Git submodules or Composer’s path repositories for version control?

4. Performance and Scaling:

   • How will module auto-discovery scale with 50+ modules? Will the modules:cache command be sufficient, or do we need a custom solution (e.g., caching in Redis)?
   • How will we handle module initialization order dependencies (e.g., Module A requires Module B’s service provider)?

5. Team Adoption:

   • How will we train developers on module-specific workflows (e.g., --module flags, namespace conventions)? Will we create internal docs or a sandbox environment?
   • How will we enforce module ownership and code reviews? Will we use GitHub/GitLab branch protection rules or custom scripts?

6. Long-Term Maintenance:

   • How will we handle module deprecation or removal? Will we use Composer’s remove or archive modules in a separate branch?
   • How will we manage module-specific configurations (e.g., .env files)? Will we use Laravel’s config caching or a custom solution?

Integration Approach

Stack Fit

• Laravel Core: Fully compatible with Laravel 11+ (tested up to 11.x). Leverages Laravel’s package discovery, service providers, and Artisan commands.
• PHP Version: Requires PHP 8.1+, aligning with Laravel’s current support window.
• Composer: Uses Composer path repositories and package discovery, which are stable but may require Composer 2.x awareness (e.g., replace syntax).
• IDE Support: Primarily optimized for PhpStorm, but VSCode/WebStorm can be configured manually.
• Testing: Integrates with PHPUnit via modules:sync (adds Modules test suite). Supports PestPHP and other test frameworks if they follow Laravel conventions.
• CI/CD: No native CI/CD integrations, but works with any pipeline that supports Composer and Laravel (e.g., GitHub Actions, GitLab CI).

Migration Path

1. Assessment Phase:

   • Audit the existing codebase for Laravel conventions (e.g., namespaces, service providers).
   • Identify high-cohesion, low-coupling components to prioritize for modularization.
   • Document dependencies between components to plan extraction order.

2. Pilot Phase:

   • Install internachi/modular in a staging environment.
   • Create 1–2 non-critical modules (e.g., a reporting module, a legacy feature) to test workflows.
   • Validate:
     • Module scaffolding (make:module).
     • Artisan command integration (--module flags).
     • Blade component/translation auto-discovery.
     • CI/CD pipeline updates (e.g., Composer install, testing).

3. Incremental Rollout:

   • Phase 1: Extract non-core features (e.g., admin panels, third-party integrations).
   • Phase 2: Refactor domain-specific logic (e.g., Users, Payments) into modules.
   • Phase 3: Migrate shared utilities (e.g., helpers, middleware) into core or shared modules.
   • Use feature flags or module toggles to enable/disable modules gradually.

4. Finalization:

   • Update documentation to reflect module structure.
   • Train the team on module-specific workflows (e.g., modules:list, modules:cache).
   • Deprecate legacy monolithic code paths and redirect to modules.

Compatibility

• Laravel Packages: Most third-party packages (e.g., Spatie, Laravel Nova) will work out-of-the-box if they follow Laravel conventions. Packages with custom directory structures may require adjustments.
• Custom Code: Legacy code using non-standard paths (e.g., app/Modules/) may need refactoring to fit app-modules/ conventions.
• Database: Migrations, seeders, and factories are auto-discovered but must follow module namespaces (e.g., Modules\Users\Database\Seeders\UsersTableSeeder).
• Frontend: Blade components and views are auto-discovered but require proper namespace registration (e.g., <x-users::profile />).

Sequencing

1. Pre-Migration:

   • Publish the config (php artisan vendor:publish --tag=modular-config) and customize the module namespace (e.g., App\Modules\).
   • Run php artisan modules:sync to update PHPUnit/PhpStorm configs.

2. Module Creation:

   • Scaffold modules using php artisan make:module [name].
   • For existing code, manually move files to app-modules/[name]/ and update composer.json.

3. Dependency Management:

   • Add module-specific dependencies to each module’s composer.json (e.g., require: "spatie/laravel-permission": "^5.0").
   • Use Composer’s replace to avoid duplication (e.g., shared libraries).

4. Testing:

   • Write module-specific tests and update phpunit.xml to include module paths.
   • Test module isolation (e.g., disable one module to ensure others work).

5. Deployment:

   • Update CI/CD pipelines to run composer update modules/[name] for module-specific updates.
   • Use modules:cache in production to optimize auto-discovery.

Operational Impact

Maintenance

• Module Updates:
  • Use Composer to update modules independently (e.g., composer update modules/users).
  • Monitor for breaking changes in module dependencies (e.g., Laravel, PHP).
• Configuration:
  • Centralize module-specific configs in config/modules.php (if using custom stubs).
  • Use Laravel’s config caching (php artisan config:cache) for performance.
• Deprecation:
  • Archive deprecated modules in a modules/archive/ directory or a separate Git branch.
  • Use Composer’s remove to uninstall modules (e.g., composer remove modules/legacy-module).

Support

• Debugging:
  • Use