Yii2 Debug Laravel Package

Product Decisions This Supports

• Developer Productivity & Debugging Workflow:

  • Enable rapid iteration by providing real-time insights into application performance, database queries, and request/response cycles.
  • Reduce time-to-resolution for bugs by surfacing detailed stack traces, memory usage, and execution logs directly in the browser.
  • Roadmap: Integrate with CI/CD pipelines to auto-generate debug reports for failed builds or performance regressions.

• Build vs. Buy:

  • Buy: Avoid reinventing a debugging tool for Yii2 applications. This package is battle-tested, modular, and extensible (e.g., custom panels for business logic).
  • Build: Only if needing highly specialized debugging (e.g., domain-specific metrics) that this package’s architecture cannot accommodate via plugins.

• Use Cases:

  • Local Development: Real-time toolbar feedback for developers.
  • Staging/Pre-Prod: IP-restricted debug panels to audit performance without exposing sensitive data.
  • Incident Response: Post-mortem analysis via saved debug data (e.g., runtime/debug logs).
  • Onboarding: Custom panels to highlight key metrics (e.g., "Views rendered," "API latency") for new team members.

• Extensibility as a Feature:

  • Leverage the panel system to build domain-specific debug tools (e.g., tracking custom business events, third-party API call logs).
  • Example: Add a PaymentsPanel to log Stripe/Webhook failures with transaction IDs.

• Performance Profiling:

  • Identify bottlenecks via query profiling, memory usage, and execution time breakdowns.
  • Roadmap: Use debug data to auto-generate optimization reports (e.g., "Top 5 slowest queries").

When to Consider This Package

• Adopt if:

  • Your team uses Yii2 and needs a unified debugging interface (toolbar + detailed panels).
  • You require customizable debug panels (e.g., for business logic, third-party services).
  • Your workflow involves frequent local/staging debugging with minimal setup.
  • You want IDE integration (e.g., PhpStorm/Sublime links in stack traces).

• Look Elsewhere if:

  • You’re not using Yii2: This is framework-specific. Consider generic PHP debuggers like Xdebug + KCacheGrind or Tideways.
  • You need production-grade APM: Tools like New Relic or Blackfire offer deeper insights but are overkill for local/dev debugging.
  • Your app is highly secure: Debug panels expose sensitive data (e.g., SQL queries, routes). Use allowedIPs to restrict access.
  • You require distributed tracing: For microservices, pair with OpenTelemetry or Jaeger instead.

• Alternatives to Evaluate:

  • Xdebug: Lower-level, requires config tuning, but works across frameworks.
  • Laravel Telescope: If migrating to Laravel, offers similar features.
  • Ray for PHP: Simpler, but less customizable than Yii’s panel system.

How to Pitch It (Stakeholders)

For Executives:

"This package gives our Yii2 dev team a Swiss Army knife for debugging—like a built-in ‘black box recorder’ for our application. It slashes time spent hunting bugs by surfacing real-time data (queries, performance, logs) in a toolbar, while keeping sensitive info locked down to trusted IPs. For example, during our last feature sprint, it helped us catch a N+1 query issue in 10 minutes that would’ve taken hours with manual logging. It’s also extensible, so we can add custom panels for business-critical metrics (e.g., payment failures) without reinventing the wheel. The cost? Zero—it’s open-source and maintained by the Yii team. ROI? Faster releases, fewer production fires."

For Engineering:

*"This is Yii2’s answer to Laravel Telescope—a debug toolbar + detailed panels for queries, requests, memory, and more. Key perks:

• Zero config for basics: Just add 'debug' to bootstrap and get a toolbar.
• Custom panels: Need to debug a specific workflow? Extend the Panel class (e.g., track ViewsPanel or PaymentsPanel).
• IDE-friendly: Click stack traces to open files in PhpStorm/Sublime.
• Staging-safe: Restrict access via allowedIPs to avoid exposing debug data in prod.
• Performance insights: Identify slow queries or memory leaks without digging through logs.

Tradeoff: It’s Yii2-only, but if we’re stuck with Yii2, this is the most powerful debugging tool we can get without building it ourselves. Let’s prototype it in staging this sprint."*

For Developers:

*"Imagine Chrome DevTools for your backend:

• Toolbar: See request time, memory, queries at a glance.
• Panels: Deep-dive into logs, DB queries, configs—all in one place.
• Customize: Add your own panels (e.g., track User::find() calls or API latency).
• IDE Links: Click stack traces to jump to the file in your editor.

How to start:

1. composer require yiisoft/yii2-debug
2. Add to config/web.php:

   'bootstrap' => ['debug'],
   'modules' => ['debug' => ['class' => 'yii\debug\Module']],
   

3. Profit: Debug toolbar appears on every page.

Pro Tip: Use tracePathMappings for Dockerized apps to fix file paths in stack traces."*