Log Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: Poor native fit due to Laravel’s reliance on PSR-3 (Monolog) and structured logging. pear/log lacks PSR-3 compliance, requiring custom adapters or wrappers to integrate with Laravel’s Log facade.
• Legacy System Integration: Ideal for legacy Laravel applications (pre-Laravel 5.5) or mixed PHP/PEAR environments where PEAR packages are already embedded. Misaligned with modern Laravel’s dependency injection and service container.
• Handler Flexibility: Supports basic backends (file, syslog, email) but lacks Laravel-native integrations (e.g., Slack, PagerDuty, database). Custom handlers would need to bridge the gap.
• Structured Logging: No built-in support for JSON/structured logs, forcing manual serialization of Laravel’s contextual arrays (e.g., ['user_id' => 123]). Incompatible with Laravel’s Log::withContext() or Log::structured().

Integration Feasibility

• Composer vs. PEAR: While Composer-installable, PEAR’s autoloader may conflict with Laravel’s Composer autoloader. Requires explicit classmap or autoload-dev configuration to avoid collisions.
• PHP Version: Requires PHP 7.4+, which aligns with Laravel 8.0+ (minimum PHP 8.0). No issues for modern Laravel but excludes older Laravel versions (e.g., 5.x).
• Laravel-Specific Gaps:
  • No Log Channels: Laravel’s channel system (e.g., single, daily) cannot natively use pear/log handlers.
  • No Stacking: Laravel’s log "stack" (combining multiple handlers) is incompatible without a custom adapter.
  • No Conditional Logging: Features like whenDebugging() or onlyInProduction() require manual implementation.
• Performance Overhead: Minimal for low-volume logging, but lacks Monolog’s optimizations (e.g., async handlers, batch processing).

Technical Risk

• Deprecation Risk: PEAR’s decline in modern PHP ecosystems may lead to stagnation. Last release in 2025 with no active maintenance signals.
• Type Safety: While PHP 7.4+ compliant, some methods lack strict typing (e.g., PEAR_LOG_ALL mask issues on 32-bit systems #41). Potential edge-case bugs in production.
• Dependency Conflicts: pear/pear_exception dependency may conflict with Laravel’s error handling or other PEAR packages.
• Debugging Complexity: Stack traces and error messages from pear/log won’t integrate with Laravel’s exception handlers (e.g., App\Exceptions\Handler).

Key Questions

1. Strategic Alignment:
   • Is this a temporary solution for legacy code, or a long-term replacement for Laravel’s logger?
   • Does the team have capacity to maintain custom adapters (e.g., PSR-3 wrapper)?
2. Feature Requirements:
   • Are structured logs (JSON/ELK) or advanced handlers (database, HTTP) needed? If so, how will they be implemented?
   • Is async logging required (e.g., for high-throughput APIs)?
3. Migration Path:
   • What’s the plan if pear/log stagnates? Will the team migrate to Monolog or another PSR-3 logger?
4. Performance:
   • What are the expected log volumes? Will file/syslog handlers bottleneck under load?
5. Team Skills:
   • Does the team have experience with PEAR packages, or will this introduce a learning curve?
   • Are developers comfortable writing custom adapters to bridge Laravel and pear/log?

Integration Approach

Stack Fit

• Best For:
  • Legacy Laravel projects (pre-5.5) with existing PEAR dependencies.
  • Non-critical logging where simplicity outweighs modern features (e.g., CLI tools, internal scripts).
  • Prototyping or short-term solutions where Monolog is overkill.
• Poor Fit For:
  • Modern Laravel apps (6.0+) relying on Monolog/PSR-3.
  • Production systems requiring structured logging, async handling, or advanced observability.
  • Teams without PEAR experience or custom adapter development capacity.

Migration Path

1. Phase 1: Isolated Pilot (1–2 Weeks)

   • Install pear/log in a non-production Laravel environment.
   • Replace Log::info() with a wrapper class to normalize API differences:

     class PearLoggerAdapter {
         public static function log(string $level, string $message, array $context = []) {
             $pearLevel = match ($level) {
                 'debug' => PEAR_LOG_DEBUG,
                 'info' => PEAR_LOG_INFO,
                 // ... other mappings
                 default => PEAR_LOG_NOTICE,
             };
             $logger = PEAR::log();
             $logger->log($message . (empty($context) ? '' : ' | ' . json_encode($context)), $pearLevel);
         }
     }
     

   • Test with critical paths (e.g., error handling, CLI commands).

2. Phase 2: Limited Integration (2–4 Weeks)

   • Add a Custom Laravel Channel:

     // config/logging.php
     'pear' => [
         'driver' => 'custom',
         'path' => storage_path('logs/pear.log'),
         'level' => 'debug',
         'handler' => new \PEAR\Log\Handler\File(storage_path('logs/pear.log')),
     ],
     

   • Use the channel for legacy code only, avoiding core application logs.
   • Implement a log level mapper to handle Laravel ↔ PEAR discrepancies.

3. Phase 3: Full Integration (4–8 Weeks)

   • Option A: Hybrid Adapter (Recommended for Legacy Systems)
     • Create a PSR-3 wrapper for pear/log to enable Laravel’s Log facade:

       class PearHandler implements \Monolog\Handler\HandlerInterface {
           public function handle(array $record): bool {
               $level = match ($record['level']) {
                   \Monolog\Logger::DEBUG => PEAR_LOG_DEBUG,
                   // ...
               };
               PEAR::log()->log($record['message'], $level);
               return true;
           }
           // Implement other Monolog methods...
       }
       

     • Register the handler in Laravel’s service provider:

       $logger->pushHandler(new PearHandler());
       

   • Option B: Feature-Freeze Migration
     • Freeze new features using pear/log and gradually migrate to Monolog by:
       1. Adding Monolog as a dependency.
       2. Replacing pear/log calls with Monolog in new code.
       3. Using a decorator pattern to route logs between the two systems.

4. Phase 4: Deprecation (Ongoing)

   • Document pear/log as a legacy dependency in composer.json.
   • Set a deprecation timeline (e.g., 12–18 months) to migrate to Monolog.
   • Replace pear/log with Laravel’s native logger in all new code.

Compatibility

• Laravel-Specific Workarounds:
  • Log Levels: Map Laravel’s levels to PEAR’s (e.g., debug → PEAR_LOG_DEBUG).
  • Context Data: Serialize Laravel’s contextual arrays to JSON and append to messages:

    $logger->log("User action | " . json_encode($context), PEAR_LOG_INFO);
    

  • Channels: Use Laravel’s channel system to route logs to pear/log:

    Log::channel('pear')->info('Legacy log message');
    

  • Exceptions: Catch pear_exception and rethrow as Laravel exceptions:

    try {
        PEAR::log()->log($message, $level);
    } catch (\PEAR_Exception $e) {
        throw new \RuntimeException("Logging failed: " . $e->getMessage());
    }
    

• PEAR-Specific:
  • Ensure pear/pear_exception is installed (v1.0.1–1.0.2).
  • Avoid PEAR’s autoloader conflicts by using Composer’s autoload-dev:

    {
        "autoload-dev": {
            "psr-4": {
                "PEAR\\": "vendor/pear/log/src/"
            }
        }
    }
    

Sequencing

1. Step 1: Dependency Audit

   • Verify no existing PEAR packages conflict with pear/log.
   • Check PHP version compatibility (7.4+ required).

2. Step 2: API Alignment

   • Build a minimal adapter to test basic logging (e.g., info(), error()).
   • Validate log level and context handling.

3. Step 3: Handler Expansion

   • Implement custom handlers for unsupported backends (e.g., database, HTTP).
   • Example: Sys