Eloquent Logger Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rstriquer/eloquent-logger --dev
   

   • The package auto-registers via Laravel's service provider discovery (no manual registration needed).

2. Enable Logging: Add to your .env:

   ELOQUENT_LOGGER_ENABLED=true
   

   • Logs will be written to storage/logs/eloquent.log (created automatically).

3. First Use Case:

   • Trigger a query (e.g., User::all()) and check storage/logs/eloquent.log for the raw SQL.
   • Ideal for debugging slow queries or verifying query structure.

Implementation Patterns

Workflow Integration

1. Conditional Activation:

   • Toggle logging via .env or dynamically in code:

     if (app()->environment('local')) {
         \EloquentLogger::enable();
     }
     

   • Useful for CI/CD pipelines or feature branches.

2. Query Filtering:

   • Log only specific models/classes by extending the logger:

     \EloquentLogger::setFilter(function ($query) {
         return $query->getModel() instanceof \App\Models\User;
     });
     

3. Integration with Debugging Tools:

   • Combine with Laravel Debugbar or Tinker:

     \EloquentLogger::enable();
     \DB::enableQueryLog();
     // Run queries, then inspect both logs.
     

4. Testing:

   • Enable logging in phpunit.xml:

     <env key="ELOQUENT_LOGGER_ENABLED" value="true"/>
     

   • Verify logs in tests for query consistency.

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Logging every query adds I/O latency. Disable after debugging:

     \EloquentLogger::disable();
     

   • Monitor log file size (storage/logs/eloquent.log) to avoid disk issues.

2. File Size Limits:

   • On Windows (FAT32), files >4GB may fail. Use NTFS or rotate logs manually:

     php artisan eloquent-logger:clear
     

   • For Linux/macOS, ensure storage/logs has sufficient inode limits.

3. Environment Leakage:

   • Accidentally commit eloquent.log to version control. Add to .gitignore:

     storage/logs/eloquent.log
     

4. Raw SQL Formatting:

   • Logs include bind values as ?. For readability, use:

     \EloquentLogger::setFormatter(function ($sql, $bindings) {
         return \DB::connection()->prepare($sql)->toSql();
     });
     

Debugging Tips

1. Log Location:

   • Verify logs are written to storage/logs/eloquent.log (check permissions).

2. Query Not Logging?:

   • Ensure ELOQUENT_LOGGER_ENABLED=true and the query uses Eloquent (not raw PDO).

3. Custom Log Path:

   • Override the default path via config:

     config(['eloquent-logger.path' => storage_path('logs/custom_eloquent.log')]);
     

4. Extending Functionality:

   • Add metadata (e.g., timestamps, user IDs) by subclassing the logger:

     use Rstriquer\EloquentLogger\EloquentLogger;
     
     class CustomLogger extends EloquentLogger {
         protected function logQuery($query) {
             $this->writeToLog("[$this->timestamp] " . $query);
         }
     }
     

     Then bind your custom class in config/eloquent-logger.php.

Configuration Quirks

• No Log Rotation: The package lacks built-in rotation. Use Laravel's logrotate or a cron job:

  find /path/to/storage/logs -name "eloquent.log" -type f -exec truncate -s 0 {} \;
  

• Queue Jobs: Logged queries from queued jobs may appear out of order. Use sync queues for debugging.