Web Snapshot Profiler Event Subscriber Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Doctrine Focus: The package is designed for Symfony applications, which share core components (e.g., EventDispatcher, HttpKernel) with Laravel but diverge in others (e.g., dependency injection, routing). Laravel’s event system is compatible but may require abstraction layers (e.g., symfony/event-dispatcher bridge) for seamless integration.
• Profiling Use Case: Fits Laravel’s need for production performance insights, especially for HTTP request profiling (e.g., middleware execution, query optimization). Complements tools like Laravel Debugbar or Blackfire but lacks native Laravel integration (e.g., no ServiceProvider or Bootstrap hooks).
• Event-Driven Design: Laravel’s event system (Illuminate\Events) is similar to Symfony’s, but event names (e.g., kernel.request vs. Illuminate\Http\Events\RequestHandled) may require mapping.

Integration Feasibility

• High-Level Feasibility: Possible with minimal refactoring (e.g., aliasing Symfony events to Laravel equivalents). Requires:
  • Event Dispatcher Bridge: Use symfony/event-dispatcher or laravel-symfony-event-dispatcher to unify event systems.
  • Middleware Hooks: Leverage Laravel’s middleware pipeline (app/Http/Kernel.php) to trigger profiling at key stages (e.g., booted, finished).
  • Storage Layer: Symfony’s profiler typically stores data in a session or database. Laravel’s storage/framework/sessions or a custom database table would need adaptation.
• Profiling Data Format: Output may need serialization/deserialization for Laravel’s logging or monitoring systems (e.g., Laravel Horizon, Sentry).

Technical Risk

• Event Name Mismatches: Risk of missed events if Laravel’s event system isn’t fully bridged (e.g., Symfony’s kernel.exception vs. Laravel’s Illuminate\Foundation\Bootstrap\HandleExceptions).
• Performance Overhead: Profiling in production adds latency. Must validate impact on critical paths (e.g., API endpoints).
• Dependency Bloat: Introduces Symfony components, increasing bundle size. Evaluate trade-offs vs. native Laravel tools (e.g., laravel-debugbar).
• Storage Conflicts: Session/database storage may conflict with Laravel’s existing systems (e.g., cache drivers, session handlers).

Key Questions

1. Event Coverage: Which Laravel events map to Symfony’s kernel.* events? Are critical events (e.g., Illuminate\Auth\Events\Attempting) supported?
2. Storage Backend: How will profiling data persist? Can it integrate with Laravel’s filesystem or database configurations?
3. Middleware Integration: How to trigger profiling without duplicating Laravel’s middleware pipeline?
4. Data Access: How to expose profiler data to Laravel’s existing monitoring (e.g., telescope, laravel-monitor)?
5. Testing: Are there unit/integration tests for Laravel compatibility? If not, how will edge cases (e.g., queue jobs, scheduled tasks) be handled?

Integration Approach

Stack Fit

• Core Stack: Compatible with Laravel 8+ (uses PHP 8+ features like named arguments). Requires:
  • Symfony EventDispatcher: Install via Composer (symfony/event-dispatcher:^6.0).
  • Laravel Event Bridge: Use spatie/laravel-symfony-event-dispatcher or custom service provider to alias events.
• Alternatives: If Symfony integration is too heavy, consider lighter-weight Laravel-native profilers (e.g., spatie/laravel-profiling).
• Database/Storage: Prefer Laravel’s database or filesystem configurations for storage (e.g., JSON files in storage/app/profiler).

Migration Path

1. Phase 1: Proof of Concept
   • Install symfony/event-dispatcher and aeatech/web-snapshot-profiler-event-subscriber.
   • Create a custom EventServiceProvider to map Symfony events to Laravel equivalents (e.g., kernel.request → Illuminate\Http\Events\RequestStarted).
   • Test with a single route to validate event firing and data collection.
2. Phase 2: Full Integration
   • Extend Laravel’s AppServiceProvider to initialize the profiler on booted.
   • Add middleware to trigger profiling at start/finish of requests.
   • Configure storage (e.g., database table or JSON files).
3. Phase 3: Monitoring Integration
   • Expose profiler data via Laravel’s telescope or a custom API endpoint.
   • Add alerts (e.g., Slack/PagerDuty) for slow requests using Laravel’s notifications.

Compatibility

• Laravel-Specific Quirks:
  • Service Container: Symfony’s ContainerInterface may need adaptation for Laravel’s Illuminate\Container\Container.
  • Routing: Symfony’s Request object differs from Laravel’s Illuminate\Http\Request. Use a wrapper or normalize data.
  • Exceptions: Laravel’s exception handling (e.g., render()) may bypass Symfony’s kernel.exception.
• Dependencies: Avoid conflicts with existing packages (e.g., laravel-debugbar, blackfire/agent).

Sequencing

1. Pre-requisite: Ensure Laravel’s event system is stable (no breaking changes in Illuminate\Events).
2. Order of Operations:
   • Register the profiler subscriber after Laravel’s core events are bound.
   • Initialize storage before profiling begins (e.g., in register() of a service provider).
   • Attach middleware last in the pipeline to avoid premature profiling.
3. Rollout Strategy:
   • Start in staging with a subset of routes.
   • Gradually enable in production with feature flags (e.g., config/profiler.php).
   • Monitor storage/database impact before full deployment.

Operational Impact

Maintenance

• Dependency Updates: Monitor symfony/event-dispatcher and Laravel version compatibility. Symfony’s BC breaks may require patches.
• Storage Management: Implement cleanup for profiler data (e.g., TTL for JSON files or database records).
• Configuration Drift: Centralize profiler settings (e.g., config/profiler.php) to avoid hardcoded values.

Support

• Debugging: Profiling data may reveal issues in third-party packages. Requires cross-team coordination (e.g., backend, frontend).
• User Education: Document how to:
  • Read profiler output (e.g., SQL queries, middleware execution times).
  • Filter/noise out irrelevant data (e.g., health check endpoints).
• Support Channels: Direct users to Laravel forums or create a profiler tag in GitHub issues.

Scaling

• Performance: Profiling adds ~5–20ms per request. Test under load (e.g., 10K RPS) to validate impact.
• Storage Scaling:
  • Database: Use Laravel’s database connection with indexing on created_at.
  • Filesystem: Shard JSON files by date (e.g., storage/app/profiler/2023-10-01.json).
• Distributed Systems: In multi-server setups, aggregate data via Laravel’s queue or a separate service (e.g., Elasticsearch).

Failure Modes

Ramp-Up

• Onboarding Time: 2–4 weeks for full integration (including testing).
  • Week 1: POC and event mapping.
  • Week 2: Storage and middleware setup.
  • Week 3: Monitoring integration and load testing.
• Training:
  • Developers: 1-hour session on interpreting profiler data.
  • Ops: 30-minute session on storage management and alerts.
• Documentation:
  • README: Add to Laravel app’s docs with setup steps.
  • Internal Wiki: Include troubleshooting (e.g., "Profiling not working for API routes").
• Feedback Loop: Gather input from first 10 users to refine configuration defaults.