Firephp Core Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require firephp/firephp-core
   

   Add the service provider to config/app.php under providers:

   FirePHP\FirePHP::class,
   

2. Basic Usage Inject the FirePHP facade in your controller or service:

   use FirePHP\FirePHP;
   
   public function index(FirePHP $firephp)
   {
       $firephp->log('Hello, FirePHP!');
       return view('welcome');
   }
   

3. First Use Case Debug a variable in a route or controller:

   $firephp->group('User Data')
           ->info($user)
           ->trace('User retrieval', ['source' => 'database']);
   

Where to Look First

• Documentation: FirePHP GitHub Wiki (if available) or FirePHP Official Docs (legacy).
• Facade Methods: Focus on log(), info(), warn(), error(), group(), and trace().
• Browser Extension: Install the FirePHP extension for Chrome/Firefox to visualize logs.

Implementation Patterns

Common Workflows

1. Debugging API Responses Log structured data before returning JSON:

   $firephp->group('API Response')
           ->info($userData)
           ->trace('Query executed', ['sql' => $query]);
   return response()->json($userData);
   

2. Middleware Integration Attach FirePHP to middleware for request/response logging:

   public function handle($request, Closure $next)
   {
       $firephp = app(FirePHP::class);
       $firephp->info('Request received', $request->all());
   
       $response = $next($request);
       $firephp->info('Response sent', $response->getData());
   
       return $response;
   }
   

3. Service Layer Logging Decorate services with logging:

   public function fetchUser($id)
   {
       $firephp->trace('Fetching user', ['id' => $id]);
       $user = User::find($id);
       $firephp->info('User found', $user);
       return $user;
   }
   

4. Exception Handling Log exceptions in App\Exceptions\Handler:

   public function report(Throwable $exception)
   {
       $firephp = app(FirePHP::class);
       $firephp->error('Uncaught exception', [
           'message' => $exception->getMessage(),
           'trace' => $exception->getTraceAsString(),
       ]);
   }
   

Integration Tips

• Laravel Debugbar: Combine with barryvdh/laravel-debugbar for richer debugging:

  $firephp->info('Debug data', $data);
  Debugbar::info('Additional data', $data);
  

• Conditional Logging: Use environment checks to avoid clutter in production:

  if (app()->environment('local')) {
      $firephp->log('Development-only message');
  }
  

• Structured Data: Prefer arrays over raw variables for better readability:

  $firephp->info('User', [
      'id' => $user->id,
      'name' => $user->name,
      'email' => $user->email,
  ]);
  

Gotchas and Tips

Pitfalls

1. Browser Extension Required

   • FirePHP logs are invisible without the browser extension. Always remind teammates to install it.
   • Workaround: Use dd() or dump() for critical checks if the extension isn’t available.

2. Performance Overhead

   • Logging large objects (e.g., Eloquent collections) can bloat memory usage.
   • Tip: Log only essential data or use ->trace() for verbose details.

3. Group Nesting Limits

   • Excessive nesting (e.g., >5 levels) may cause rendering issues in the extension.
   • Tip: Flatten complex groups or use separate logs.

4. CSRF/Session Conflicts

   • FirePHP injects data into the HTTP response, which may interfere with CSRF tokens or session handling.
   • Fix: Exclude FirePHP from production or use middleware to disable it in non-debug environments:

     if (!app()->environment('local')) {
         $firephp->disable();
     }
     

5. Legacy Package

   • The package is no longer actively maintained (last update: 2016). Expect no new features.
   • Alternative: Consider barryvdh/laravel-debugbar or spatie/laravel-log-viewer for modern debugging.

Debugging Tips

• Log Not Appearing?

  • Verify the browser extension is enabled and the FirePHP icon is visible in the console.
  • Check if the response headers include X-FirePHP-Version (FirePHP adds this header).

• Malformed Output

  • If logs appear corrupted, ensure no other middleware is modifying the response after FirePHP injects its data.

• Clear Logs

  • Use $firephp->clear() to reset logs between requests (useful in tests or loops).

Extension Points

1. Custom Log Levels Extend the facade to add domain-specific methods:

   $firephp->audit('User action', ['action' => 'update', 'user_id' => 1]);
   

   Implementation: Override the FirePHP facade or create a decorator.

2. Log to File + FirePHP Forward FirePHP logs to Laravel’s log channel:

   $firephp->setHandler(function ($log) {
       Log::channel('single')->info($log['message'], $log['data']);
   });
   

3. Remote Debugging Use FirePHP to log data for remote servers where direct access is limited:

   // Logs will appear in the browser of any user accessing the page.
   $firephp->warn('Server misconfiguration', ['file' => $file, 'line' => $line]);