Common Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Monolithic Symfony/Laravel Alignment: The bundle is designed for Symfony (via Kernel extension) but can be adapted for Laravel with minimal effort due to shared PHP/Symfony components (e.g., Messenger, Doctrine, Redis). Key features like health checks, logging (MongoDB/Sentry), permissions, and exception handling align well with Laravel’s ecosystem if wrapped in Laravel’s service container.
• Modularity: The bundle provides loosely coupled functionality (e.g., argument resolvers, locks, value objects) that can be adopted incrementally. However, the mandatory AnzuKernel extension forces architectural changes (e.g., replacing Laravel’s Kernel).
• Laravel-Specific Gaps:
  • Laravel lacks Symfony’s EventDispatcher (used for exceptions/logs), requiring a bridge (e.g., symfony/event-dispatcher).
  • Doctrine ORM is optional in Laravel; the bundle assumes it (e.g., health checks, migrations).
  • Messenger (for logs) would need Laravel’s queue system or a custom adapter.

Integration Feasibility

• High for Symfony: Drop-in replacement for core functionality (e.g., Kernel, health checks).
• Medium for Laravel:
  • Core Features: Logging (MongoDB/Sentry), permissions, and exception handling can be adapted with service container bindings.
  • Challenges:
    • Kernel Override: Laravel’s Kernel cannot extend AnzuKernel directly; a facade or decorator pattern would be needed.
    • Event System: Laravel’s Events system differs from Symfony’s EventDispatcher; middleware or listeners would require refactoring.
    • Doctrine Dependency: If not using Doctrine, health checks (e.g., _doctrine_migration_versions) would fail.
• Dependencies:
  • Symfony Components: symfony/messenger, symfony/security, symfony/var-exporter are required but compatible with Laravel.
  • MongoDB: Hard dependency for logs/audit trails; requires mongodb/mongodb or Laravel’s jenssegers/mongodb.

Technical Risk

• Breaking Changes:
  • BC Breaks: Versions 7.0.0+, 8.0.0, and 10.0.0 introduce breaking changes (e.g., ROLE_SUPER_ADMIN, MongoDB collection renames, routing shifts). Risk mitigated by strict version pinning in composer.json.
  • Symfony 8 Deprecations: Fixed in v11.0, but Laravel’s Symfony component versions must align (e.g., symfony/var-exporter:^7.0|^8.0).
• Performance:
  • Health Checks: Adds overhead (e.g., Redis/MongoDB probes). Disable unused modules (modules: []) to reduce latency.
  • Logging: Async Messenger-based logging is efficient but requires queue workers (Laravel’s queue:work).
• Security:
  • Read-Only Mode: The appReadOnlyMode flag enables graceful degradation but requires application-level validation (e.g., middleware to block writes).
  • Permissions: The RBAC system is robust but assumes Laravel’s Auth is integrated with Symfony’s Security (may need spatie/laravel-permission bridge).

Key Questions

1. Do we need all features?
   • Audit logs, health checks, and permissions add complexity. Audit if only subsets (e.g., logging) are required.
2. How will we handle Symfony vs. Laravel differences?
   • Example: Replace EventDispatcher with Laravel’s Events via a service provider.
3. What’s our Doctrine/MongoDB strategy?
   • If not using Doctrine, mock health checks or disable them (health_check.enabled: false).
4. How will we manage environment variables?
   • Laravel uses .env; Symfony uses env(). The bundle expects env() calls (e.g., ANZU_MONGODB_APP_LOG_URI). Use Laravel’s env() helper or a custom wrapper.
5. What’s the upgrade path?
   • Pin to a stable minor version (e.g., 11.x) to avoid BC breaks. Monitor anzusystems/contracts for shared interfaces.

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Dependency Setup

   • Install via Composer:

     composer require anzusystems/common-bundle --no-scripts
     

   • Add Symfony components (if missing):

     composer require symfony/messenger symfony/security-bundle symfony/var-exporter
     

   • Configure composer.json for putenv:

     "extra": { "runtime": { "use_putenv": true } }
     

2. Phase 2: Kernel Adaptation

   • Symfony: Extend AnzuKernel directly.
   • Laravel: Create a decorator for Illuminate\Foundation\Application:

     // app/Providers/AnzuKernelServiceProvider.php
     use AnzuSystems\CommonBundle\Kernel\AnzuKernel;
     
     class AnzuKernelServiceProvider extends ServiceProvider {
         public function register() {
             $this->app->extend('kernel', function ($kernel) {
                 return new AnzuKernelAdapter($kernel, [
                     'appSystem' => env('APP_SYSTEM', 'core'),
                     'appVersion' => env('APP_VERSION', '1.0.0'),
                     'appReadOnlyMode' => env('APP_READ_ONLY_MODE', false),
                 ]);
             });
         }
     }
     

   • Register the provider in config/app.php.

3. Phase 3: Configuration

   • Create config/packages/anzu_common.yaml (Laravel uses config/anzu_common.php):

     return [
         'settings' => [
             'app_redis' => 'redis',
             'user_entity_class' => App\Models\User::class,
             // ... other settings
         ],
         // ... rest of config
     ];
     

   • Load config in a service provider:

     $this->mergeConfigFrom(__DIR__.'/anzu_common.php', 'anzu_common');
     

4. Phase 4: Feature-Specific Adaptations

   • Logging: Bind Messenger to Laravel Queues:

     // config/anzu_common.php
     'logs' => [
         'messenger_transport' => [
             'name' => 'core_log',
             'dsn' => 'laravel-queue://core_log',
         ],
     ],
     

   • Permissions: Bridge to Spatie:

     // app/Providers/AnzuPermissionServiceProvider.php
     use AnzuSystems\CommonBundle\Security\Permission\PermissionManager;
     
     class AnzuPermissionServiceProvider extends ServiceProvider {
         public function register() {
             $this->app->singleton(PermissionManager::class, function () {
                 return new SpatiePermissionAdapter();
             });
         }
     }
     

   • Health Checks: Disable Doctrine checks if not using Doctrine:

     health_check:
         enabled: true
         modules: [AnzuSystems\CommonBundle\HealthCheck\Module\RedisModule]
     

5. Phase 5: Testing

   • Unit Tests: Mock AnzuKernel and test adapters.
   • Integration Tests: Verify logging, permissions, and exception handling in Laravel’s context.
   • Performance: Benchmark health checks and logging overhead.

Compatibility

• Laravel Versions: Tested with Laravel 10.x/11.x (Symfony 6.4/7.0+). Avoid Laravel 9.x due to Symfony 6.x deprec