Doctrine Debug Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Doctrine-Centric: This bundle is not natively compatible with Laravel or Eloquent. It relies on Symfony’s ProfilerBundle and Doctrine ORM event listeners, which have no direct equivalents in Laravel. However, a Laravel TPM could leverage its core concept (stack trace debugging for queries) by:
  • Porting the logic to Laravel’s query logging (e.g., DB::enableQueryLog()) or debugbar (e.g., barryvdh/laravel-debugbar).
  • Using it as a reference implementation for a custom Laravel package (e.g., "LaravelDoctrineDebugBundle").
• Observability Focus: The bundle’s stack trace injection aligns with Laravel’s need for query debugging, especially in:
  • Legacy Laravel apps with opaque query logic.
  • Complex Eloquent relationships where N+1 queries are hard to trace.
  • Debugging service containers (e.g., identifying which repository method triggers a slow query).

Integration Feasibility

• Laravel Stack Compatibility:
  • ❌ Direct Integration: Impossible without rewriting for Laravel’s architecture (e.g., no AppKernel, different profiler systems).
  • ✅ Conceptual Portability: The stack trace + query logging idea can be adapted using:
    • Laravel’s built-in query logging (DB::getQueryLog()).
    • Debugbar (for UI visualization).
    • Monolog (for logging stack traces to files).
• Technical Debt:
  • High effort to replicate the Symfony Profiler’s UI in Laravel.
  • Low effort to log raw stack traces (e.g., via middleware or Eloquent events).

Technical Risk

Key Questions

1. Debugging Needs:
   • Does Laravel’s current query logging (DB::getQueryLog()) or Debugbar meet the team’s needs? If not, what’s missing?
2. Stack Trace Depth:
   • Should stack traces be limited to Eloquent models/repositories (not framework internals)?
3. UI Requirements:
   • Is a Profiler-like UI needed, or are logs/CLI output sufficient?
4. Performance Trade-offs:
   • Can stack trace logging be disabled in production (e.g., via .env)?
5. Alternatives:
   • Are tools like Telescope, Laravel Debugbar, or Blackfire already in use?
6. Eloquent vs. Query Builder:
   • Should this focus on Eloquent models (e.g., User::with('posts')->get()) or raw query builder (DB::select())?
7. CI/CD Impact:
   • Would enabling this in tests slow down the suite? If so, restrict to dev only.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Best for: Teams using Eloquent with complex relationships or legacy query logic.
  • Avoid for: Projects relying solely on raw query builder or already using Telescope/Debugbar.
• Key Gaps Filled:
  • Query origin: Unlike DB::getQueryLog(), this shows which Eloquent method/repo triggered the query.
  • Stack trace context: Helps debug service container interactions (e.g., "Why did UserRepository::findActive() generate 20 queries?").
• Non-Laravel Projects:
  • Not applicable (e.g., Symfony, custom PHP apps).

Migration Path

1. Assess Current Debugging Tools:
   • Audit existing tools (e.g., Debugbar, Telescope, DB::enableQueryLog()).
   • Identify pain points (e.g., "We can’t tell which service triggered a slow query").
2. Phase 1: Proof of Concept (Low Effort)
   • Log stack traces manually for slow queries using middleware:

     // app/Http/Middleware/LogQueryStackTraces.php
     public function handle($request, Closure $next) {
         DB::listen(function ($query) {
             if ($query->time > 100) { // Slow queries only
                 Log::debug(
                     "Slow Query: {$query->sql}\nStack: " . collect(debug_backtrace())->take(5)->implode("\n")
                 );
             }
         });
         return $next($request);
     }
     

   • Register in app/Http/Kernel.php:

     protected $middleware = [
         \App\Http\Middleware\LogQueryStackTraces::class,
     ];
     

3. Phase 2: UI Integration (Medium Effort)
   • Extend Debugbar to show stack traces:

     // app/Providers/DebugbarServiceProvider.php
     use Barryvdh\Debugbar\DataCollector\Messages;
     use Barryvdh\Debugbar\DataCollector\TimeDataCollector;
     
     public function register() {
         $this->app->bind('debugbar.stacktraces', function () {
             return new class extends Messages {
                 public function collect() {
                     $this->addMessage('Query Stack Traces', 'info', collect(DB::getQueryLog())->map(function ($log) {
                         return "SQL: {$log['query']}\nStack: " . collect(debug_backtrace())->take(3)->implode("\n");
                     }));
                 }
             };
         });
     }
     

4. Phase 3: Full Bundle (High Effort)
   • Fork the Symfony bundle and rewrite for Laravel:
     • Replace AppKernel logic with Laravel service providers.
     • Use Eloquent events (Retrieving, Retrieved) instead of Doctrine listeners.
     • Integrate with Laravel’s profiler (if using laravel/profiler package).
   • Publish as a custom package (e.g., laravel-doctrine-debug).

Compatibility

Sequencing

1. Short-Term (1–2 Weeks):
   • Implement manual stack trace logging (Phase 1) for critical queries.
   • Validate with the team (e.g., "Does this solve the N+1 problem in UserController?").
2. Medium-Term (2–4 Weeks):
   • Integrate with Debugbar (Phase 2) for a UI solution.
   • Add environment checks (e.g., only log in APP_DEBUG=true).
3. Long-Term (1–3 Months):
   • Build a reusable package (Phase 3) if the proof of concept succeeds.
   • Explore Telescope integration for enterprise teams.

Operational Impact

Maintenance

• Dependency Management:
  • No external dependencies for Phase 1/2 (uses Laravel core + Debugbar).
  • Phase 3 bundle would need updates for:
    • Laravel major versions (e.g., Eloquent API changes).
    • Debugbar/Telescope breaking changes.
• Configuration:
  • Phase 1: Minimal (middleware registration).
  • Phase 2: Debugbar collector configuration.
  • Phase 3: Package-specific config (e.g., `