Log Implementations Laravel Package

Technical Evaluation

Architecture Fit

• PSR-3 Alignment: Perfectly complements Laravel’s PSR-3 logging stack (e.g., Monolog, Laravel’s Log facade). Enables dynamic logger resolution without hardcoding dependencies, aligning with Laravel’s modular design.
• Decoupled Logging: Ideal for Laravel plugins, SDKs, or microservices where logging is optional but should leverage the host application’s configuration. Reduces vendor lock-in and simplifies dependency management.
• Lazy Loading: Avoids runtime overhead by deferring logger instantiation until discovery is triggered, improving performance for applications where logging is not critical.
• Facade Integration: Can extend Laravel’s Log facade to delegate to Discover::log(), enabling transparent logger switching without breaking existing code.

Integration Feasibility

• Service Provider Integration:
  • Register a fallback logger in Laravel’s service container if Discover::log() returns null.
  • Example:

    $this->app->bind(\Psr\Log\LoggerInterface::class, function () {
        return Discover::log() ?: new \Monolog\Logger('fallback');
    });
    

• Dynamic Driver Resolution:
  • Extend Laravel’s Log::driver() to support dynamic discovery:

    Log::extend('discovered', function () {
        return Discover::log() ?: throw new \RuntimeException('No logger discovered');
    });
    

• Event Listeners:
  • Use Discover::logs() to inspect available implementations for runtime decisions (e.g., enabling/disabling features based on logging capabilities).
• Middleware:
  • Inject discovered loggers into middleware for request-specific logging (e.g., audit trails).

Technical Risk

• Version Conflicts:
  • Risk of incompatible logger versions (e.g., Monolog 2.x vs. 3.x) in multi-package applications.
  • Mitigation:
    • Enforce strict version constraints in composer.json (e.g., monolog/monolog:^3.0).
    • Use Laravel’s composer.json conflict rules to block incompatible versions.
• Mock Leakage:
  • Mock implementations (e.g., psr-mock/log-implementation) may inadvertently ship to production if not scoped to dev dependencies.
  • Mitigation:
    • Explicitly exclude mocks via Logs::use('monolog/monolog') in production.
    • Add a composer.json replace rule to block mocks in non-dev environments.
• Singleton Conflicts:
  • Laravel’s service container manages singleton loggers by default. The package’s singleton: true mode may cause conflicts if not aligned.
  • Mitigation:
    • Bind the discovered logger to Laravel’s container with singleton: true:

      $this->app->singleton(\Psr\Log\LoggerInterface::class, function () {
          return Discover::log(singleton: true);
      });
      

• Fallback Logic:
  • Discovery failures may break logging entirely if not handled gracefully.
  • Mitigation:
    • Implement a multi-layer fallback:

      $logger = Discover::log() ?: new \Monolog\Logger('fallback') ?: new class implements \Psr\Log\LoggerInterface { /* Minimal implementation */ };
      

Key Questions

1. Logger Ownership:
   • Should this package replace Laravel’s default logger entirely, or act as a supplementary mechanism for optional features (e.g., third-party plugins)?
2. Performance Impact:
   • Will the discovery mechanism introduce measurable overhead during application startup? Benchmark against hardcoded logger instantiation.
3. Testing Strategy:
   • How will mock implementations be integrated into Laravel’s testing stack (e.g., PestPHP, PHPUnit)? Should mocks be forced in testing environments?
4. Configuration Overrides:
   • Should users be able to override discovered loggers via Laravel’s config/logging.php or environment variables?
5. Cloud/Enterprise Loggers:
   • Are there specific loggers (e.g., google/cloud-logging, aws/aws-sdk-php) that should be prioritized for enterprise use cases?
6. Deprecation Path:
   • How will this package be deprecated if Laravel introduces native dynamic logger resolution (e.g., via Log::discover())?
7. Security:
   • Are there security implications of auto-discovering loggers (e.g., logging sensitive data to an unexpected implementation)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Monolog: Native support via monolog/monolog in the discovered implementations list.
  • Laravel’s Log Facade: Seamless integration via driver extension or service provider binding.
  • Horizon/Queues: Can leverage discovered loggers for job failure logging or queue monitoring.
  • Lumen: Lightweight alternative to Laravel with similar integration patterns.
• PHP Extensions:
  • Works alongside existing PSR-3 loggers (e.g., yiisoft/log, laminas/laminas-log) without requiring changes to the host application.
• Tooling:
  • Compatible with Laravel Forge, Envoyer, and Homestead for deployment scenarios where logging is managed externally.

Migration Path

1. Phase 1: Discovery-Only Mode
   • Integrate psr-discovery/log-implementations as a dependency in composer.json.
   • Use Discover::log() in non-critical paths (e.g., plugins, SDKs) to test auto-discovery.
   • Example:

     // In a plugin's service provider
     $this->app->when(\Your\Plugin::class)
                ->needs(\Psr\Log\LoggerInterface::class)
                ->give(fn () => Discover::log());
     

2. Phase 2: Facade Extension
   • Extend Laravel’s Log facade to support dynamic discovery:

     // app/Providers/AppServiceProvider.php
     Log::extend('discovered', function () {
         return Discover::log() ?: throw new \RuntimeException('No logger discovered');
     });
     

   • Update configuration to use the new driver:

     'default' => env('LOG_CHANNEL', 'discovered'),
     

3. Phase 3: Full Replacement (Optional)
   • Replace Laravel’s default logger binding with the discovered instance:

     $this->app->bind(\Psr\Log\LoggerInterface::class, function () {
         return Discover::log() ?: new \Monolog\Logger('fallback');
     });
     

   • Update config/logging.php to reflect the change.

Compatibility

• Laravel Versions:
  • Compatible with Laravel 10+ (PHP 8.2+) due to the package’s PHP 8.2+ requirement.
  • For Laravel 9.x, use a legacy fork or polyfill (e.g., php-compat).
• Logger Implementations:
  • Supports all major PSR-3 loggers (Monolog, Laminas, Yii, etc.) out of the box.
  • Manual instantiation required for loggers with configuration (e.g., google/cloud-logging).
• Environment Awareness:
  • Mock implementations are prioritized in dev environments by default. Explicitly disable mocks in production:

    if (app()->environment('production')) {
        Logs::use('monolog/monolog');
    }
    

Sequencing

1. Dependency Installation:
   • Add to composer.json:

     "require": {
         "psr-discovery/log-implementations": "^1.1"
     },
     "require-dev": {
         "psr-mock/log-implementation": "^1.0" // For testing
     }
     

2. Service Provider Registration:
   • Register a provider to bind the discovered logger to Laravel’s container (see Integration Approach above).
3. Configuration:
   • Update config/logging.php to include the discovered driver (if extending the facade).
4. Testing:
   • Verify mock implementations are used in tests:

     $this->expectsJobs(Job::class)->toBeDispatched();
     // Mock logger will capture logs for assertions
     

5. Deployment:
   • Ensure production environments exclude mocks and prioritize enterprise loggers (e.g., google/cloud-logging).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor psr-discovery/log-implementations for updates (e.g., new supported loggers, PHP version changes).
  • Update composer.json constraints for discovered loggers (e.g., monolog/monolog:^3.0) to avoid conflicts.
• Logger Compatibility:
  • Test with new Laravel releases to ensure discovered loggers remain compatible (e.g., Monolog 3.x with Laravel 11).
• Deprecation:
  • Plan for Laravel’s potential native dynamic logger resolution (e.g., Log::discover()). Deprecate the package if replaced by Laravel core.

Support

• User Onboarding:
  • Document how users can influence logger discovery (e.g., Logs::prefer(),