Sentry Symfony Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Specific: The package is tightly coupled with Symfony’s ecosystem (e.g., dependency injection, event listeners, HTTP client integration), making it ideal for Symfony-based applications (Lumen, Symfony Flex, or full-stack Symfony). For Laravel projects, this package is not directly applicable unless abstracted via a facade or middleware layer.
• Observability Layer: Acts as a complementary tool to Laravel’s native error handling (e.g., App\Exceptions\Handler) rather than a replacement. Best suited for enterprise-grade apps requiring structured error tracking, performance monitoring, or distributed tracing.
• Extensibility: Supports custom event listeners, breadcrumbs, and context enrichment, aligning with Laravel’s event system (via EventServiceProvider) but requiring manual mapping.

Integration Feasibility

• Laravel Compatibility: Requires Symfony components (e.g., symfony/http-client, symfony/event-dispatcher) as dependencies, adding ~5MB+ to the vendor size. Feasible but not native—would need:
  • A Symfony bridge (e.g., spatie/symfony-support) or custom middleware to translate Laravel exceptions to Symfony’s Throwable format.
  • Service provider bootstrapping to initialize Sentry’s client in Laravel’s container.
• DSL Differences: Laravel’s report()/render() exception handling differs from Symfony’s ErrorListener. Would need adapters to bridge:
  • Laravel’s App\Exceptions\Handler → Sentry’s ErrorHandler.
  • Laravel’s Log facade → Sentry’s Logger.
• Async Support: Sentry’s Symfony SDK supports async event dispatching (via Symfony Messenger), which could be replicated in Laravel using queues (e.g., sentry/sentry-laravel as a reference).

Technical Risk

Key Questions

1. Why Symfony? If the goal is Laravel-native error tracking, evaluate sentry/sentry-laravel (official) or spatie/laravel-sentry first. Justify the Symfony dependency overhead.
2. Event Mapping: How will Laravel’s illuminate/events (e.g., Illuminate\Auth\Events\Registered) be translated to Sentry’s Event objects?
3. DSL Alignment: Will the team maintain dual exception handlers (Laravel’s Handler + Symfony’s ErrorListener)? If so, document the priority order.
4. Testing Strategy: How will integration tests cover:
   • Symfony-specific features (e.g., HttpException handling)?
   • Laravel’s try/catch blocks with Sentry reporting?
5. Cost vs. Value: Sentry’s free tier has issue limits. Model usage patterns (e.g., "We’ll only track 5xx errors") to avoid throttling.
6. Migration Path: If adopting later, how will existing Laravel error logs (Monolog) be backfilled into Sentry?

Integration Approach

Stack Fit

• Core Stack: Works with Laravel 7.0+ (Symfony 4.4+ compatibility) but requires:
  • Symfony Components: symfony/http-client, symfony/event-dispatcher, symfony/psr-http-message.
  • PSR-15 Middleware: Sentry’s ErrorListener can be adapted as Laravel middleware (via Illuminate\Pipeline).
• Alternatives:
  • For Minimalism: Use sentry/sentry-laravel (official) instead.
  • For Full Symfony: Migrate to Symfony if the team is open to it (long-term tech debt).
• Tooling Synergy:
  • Sentry CLI: Works with Laravel’s mix/vite for source maps.
  • Laravel Forge/Vapor: Sentry’s DSN can be injected via environment variables (e.g., SENTRY_DSN).

Migration Path

1. Phase 1: Proof of Concept (2–3 days)
   • Install sentry/sentry-symfony + required Symfony components.
   • Create a custom service provider (SentryServiceProvider) to:
     • Initialize the Sentry client in Laravel’s container.
     • Register a global exception handler to report Laravel exceptions to Sentry.
   • Test with a single route (e.g., /debug-sentry) to verify error capture.
2. Phase 2: Core Integration (1–2 weeks)
   • Exception Mapping: Build a translator to convert Laravel-specific exceptions (e.g., ValidationException, HttpResponseException) to Sentry’s format.
   • Event Integration: Subscribe to Laravel events (e.g., Illuminate\Auth\Events\Failed) and dispatch Sentry events.
   • Middleware: Wrap Sentry’s ErrorListener in Laravel middleware for per-route error tracking.
   • Configuration: Mirror Symfony’s config/packages/sentry.yaml in Laravel’s config/sentry.php.
3. Phase 3: Advanced Features (Ongoing)
   • Performance Monitoring: Instrument Laravel’s HttpKernel to track request timing (via Sentry’s Transaction).
   • Breadcrumbs: Add Sentry breadcrumbs for:
     • Laravel’s Log entries.
     • Auth events (e.g., user.logged_in).
   • Source Maps: Configure sentry-cli for Laravel’s Blade/PHP files.

Compatibility

Sequencing

1. Prerequisite: Ensure the Laravel app uses PSR-11 Container (Symfony’s DI) or adapt to Laravel’s Illuminate\Contracts\Container\Container.
2. Order of Operations:
   • Install dependencies (composer require sentry/sentry-symfony symfony/http-client).
   • Register the Sentry client before Laravel’s exception handler.
   • Configure DSN and environment-specific settings (e.g., SENTRY_DSN in .env).
   • Implement exception translation last (highest risk).
3. Rollout Strategy:
   • Canary Release: Enable Sentry only for admin users first.
   • Feature Flags: Use Laravel’s config('sentry.enabled') to toggle Sentry reporting.

Operational Impact

Maintenance

• Dependency Updates:
  • Symfony components may require manual version pinning to avoid breaking changes.
  • Sentry’s SDK updates may introduce BC breaks (monitor sentry/sentry-symfony changelog).
• Configuration Drift:
  • Maintain dual configs (Symfony-style YAML + Laravel’s PHP array) or migrate to a single format.
  • Document environment-specific DSNs (dev/staging/prod).
• Logging Overhead:
  • Sentry’s auto-instrumentation may log noisy events (e.g., 404s). Configure ignore_errors in config/sentry.php.

Support

• Debugging Workflow:
  • Sentry’s issue groups may not align with Laravel’s App\Exceptions\Handler groups. Define a naming convention (e.g., {ExceptionClass}: {Message}).
  • Use Sentry\Tracing\span() for Laravel’s Illuminate\Http\Request lifecycle tracking.
• Support Channels:
  • Symfony-Specific Issues: Redirect to Sentry’s Symfony SDK docs or GitHub issues.
  • **Laravel-S