Logger Console Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require phrity/logger-console
   

2. Basic Usage:

   use Phrity\Logger\Console\ConsoleLogger;
   $logger = new ConsoleLogger();
   $logger->info('Application started');
   

3. First Use Case: Replace echo or Log::info() in an Artisan command:

   use Phrity\Logger\Console\ConsoleLogger;
   protected $logger;
   
   public function __construct() {
       $this->logger = new ConsoleLogger(cliOptions: true);
   }
   
   public function handle() {
       $this->logger->info('Command executing', ['user_id' => 1]);
   }
   

   Run with:

   php artisan my:command --verbose
   

Where to Look First

• Verbosity Levels: Check Verbosity::class for available levels (Quiet, Normal, Verbose, etc.).
• Format Customization: Modify the default format in the constructor:

  $logger = new ConsoleLogger(format: '{datetime} [{level}] {message} - {context}');
  

• CLI Options: Enable with cliOptions: true to support --verbose flags.

Implementation Patterns

Core Workflows

1. Artisan Command Integration:

   use Phrity\Logger\Console\ConsoleLogger;
   
   class MyCommand extends Command {
       protected $logger;
   
       public function __construct() {
           parent::__construct();
           $this->logger = new ConsoleLogger(cliOptions: true);
       }
   
       public function handle() {
           $this->logger->debug('Debug details', ['data' => $this->getData()]);
           $this->logger->info('User processed', ['user_id' => 123]);
       }
   }
   

   Run with:

   php artisan my:command -vvv  # Debug level
   

2. Test Logging: Replace var_dump() or echo in tests:

   use Phrity\Logger\Console\ConsoleLogger;
   $logger = new ConsoleLogger(verbosity: Verbosity::Verbose);
   $logger->debug('Test data:', ['response' => $response]);
   

3. Queue Job Logging: Log job progress in handle():

   use Phrity\Logger\Console\ConsoleLogger;
   $logger = new ConsoleLogger();
   $logger->info('Processing job', ['job_id' => $job->id]);
   

Integration Tips

• Laravel Service Provider: Bind ConsoleLogger to the container for dependency injection:

  $this->app->bind(ConsoleLogger::class, function ($app) {
      return new ConsoleLogger(
          verbosity: $app['config']['logging.verbosity'],
          cliOptions: true
      );
  });
  

  Use in commands:

  use Phrity\Logger\Console\ConsoleLogger;
  protected $logger;
  
  public function __construct(ConsoleLogger $logger) {
      $this->logger = $logger;
  }
  

• Dynamic Verbosity: Set verbosity via .env:

  LOG_VERBOSITY=verbose
  

  Load in ConsoleLogger:

  $logger = new ConsoleLogger(verbosity: env('LOG_VERBOSITY', 'normal'));
  

• Contextual Logging: Pass arrays for structured context:

  $logger->info('User action', [
      'user_id' => 1,
      'action' => 'login',
      'ip' => request()->ip(),
  ]);
  

• Format Reusability: Define formats in config/logging.php:

  'console_formats' => [
      'default' => '{datetime} [{level}] {message}',
      'verbose' => '{datetime} [{level}] {message} - {context}',
  ],
  

  Use dynamically:

  $format = config('logging.console_formats.verbose');
  $logger = new ConsoleLogger(format: $format);
  

Gotchas and Tips

Pitfalls

1. CLI Option Conflicts:

   • If cliOptions: true is enabled, ensure your CLI tool’s arguments don’t conflict with the package’s flags (e.g., --verbose). Use -- to delimit:

     php artisan my:command -- --verbose
     

2. Format Parsing Errors:

   • Invalid replacers (e.g., {invalid}) will throw exceptions. Validate formats:

     $format = '{datetime} [{level}] {message}'; // Valid
     $logger = new ConsoleLogger(format: $format);
     

3. Verbosity Overhead:

   • Debug level logs can flood output. Use sparingly in production-like environments.

4. Context Serialization:

   • Complex objects in context may not serialize cleanly. Use arrays or JSON-serializable data:

     $logger->info('Data', ['user' => (array) $user]); // Cast to array
     

5. Dependency Conflicts:

   • The package depends on phrity/util-*. Check for version conflicts with Laravel’s dependencies:

     composer why phrity/util-
     

Debugging Tips

1. Log Level Toggling:

   • Quickly adjust verbosity via CLI:

     php artisan my:command --verbose  # Verbose
     php artisan my:command -vvv       # Debug
     

2. Format Testing:

   • Test formats in isolation:

     $logger = new ConsoleLogger(format: '{level}: {message}');
     $logger->info('Test', ['key' => 'value']); // Output: INFO: Test - array:1 [▶]
     

3. Fallback to Monolog:

   • If ConsoleLogger fails, fall back to Monolog:

     try {
         $logger = new ConsoleLogger();
     } catch (\Exception $e) {
         $logger = \Log::channel('stack'); // Fallback
     }
     

4. Context Inspection:

   • Use json_encode() to debug context serialization:

     $context = ['data' => new stdClass()];
     $logger->info('Check context', ['context' => json_encode($context)]);
     

Extension Points

1. Custom Verbosity Levels: Extend Verbosity enum (PHP 8.1+):

   enum Verbosity {
       case Trace;
       // ...
   }
   

2. Additional Replacers: Add custom replacers by extending the logger:

   class ExtendedLogger extends ConsoleLogger {
       protected function replaceContext(string $message, array $context): string {
           $message = parent::replaceContext($message, $context);
           return str_replace('{custom}', $context['custom'] ?? '', $message);
       }
   }
   

3. Symfony Console Integration: Use Symfony’s Output interface for advanced formatting:

   use Symfony\Component\Console\Output\ConsoleOutput;
   $output = new ConsoleOutput();
   $logger = new ConsoleLogger(output: $output);
   

4. Log Routing: Route logs to multiple outputs (e.g., console + file):

   use Symfony\Component\Console\Output\BufferedOutput;
   $bufferedOutput = new BufferedOutput();
   $logger = new ConsoleLogger(output: $bufferedOutput);
   // Later: $bufferedOutput->fetch();
   

Configuration Quirks

1. Default Verbosity: The default is Verbosity::Normal. Override via constructor or .env:

   $logger = new ConsoleLogger(verbosity: Verbosity::Verbose);
   

2. Format Escaping: Escape curly braces in messages by doubling them:

   $logger->info('Message with {{curly braces}}'); // Output: Message with {curly braces}
   

3. Context Order: Context keys are inserted in order. Sort if order matters:

   ksort($context);
   $logger->info('Data', $context);
   

4. Performance: High verbosity levels (e.g., Debug) can impact performance. Benchmark in critical paths:

   php artisan my:command --verbose  # Test performance