Raygun Bundle Laravel Package

Getting Started

First, the reality check. This is a Symfony2 bundle (it's a *Bundle class registered in AppKernel), not a Laravel package. There is no service provider, no facade, no config/raygun.php. With 1 star, 0 dependents, and a last-touched date in the Symfony2 era, treat it as a reference implementation rather than a dependency you install with composer require and forget. The actual value you'll get day-to-day comes from mindscape/raygun4php, which the bundle merely wires into Symfony's container.

Minimal steps to evaluate it (in a Symfony2 app, e.g., a legacy service you maintain):

1. composer require nietonfir/raygun-bundle:dev-master mindscape/raygun4php
2. Register the bundle in app/AppKernel.php:

   $bundles = [
       // ...
       new Nietonfir\RaygunBundle\NietonfirRaygunBundle(),
   ];
   

3. Read the three files that define the contract before touching YAML:
   • DependencyInjection/Configuration.php — the exact config tree and defaults
   • Resources/config/services.xml — service IDs and constructor arguments
   • EventListener/* (or EventListener/ExceptionListener.php) — what actually gets reported
4. Configure an API key in app/config/config.yml (namespace is likely nietonfir_raygun):

   nietonfir_raygun:
       api_key: "%raygun_api_key%"
       # check Configuration.php for async/version/environment keys
   

5. Trigger a deliberate exception in a controller that routes to the bundle's listener and confirm it lands in the Raygun dashboard before wiring it into staging or production.

If you're in a Laravel app — which is the realistic scenario given the framing — you will not be using this bundle. Install mindscape/raygun4php directly and spend 20 minutes porting the bundle's exception listener into a App\Exceptions\Handler::report() call or a queued job. That's less work than fighting Symfony2 conventions inside Laravel.

Implementation Patterns

Port the listener, don't depend on the bundle. The bundle's core behavior is: register a kernel event listener on kernel.exception, build a RaygunClient with the configured key, and call SendException($exception). That's ~15 lines. Copy it into a framework-native hook:

// Laravel app/Exceptions/Handler.php
use Raygun4php\RaygunClient;

public function report(Throwable $e): void
{
    if (app()->bound(RaygunClient::class) && $this->shouldReport($e)) {
        app(RaygunClient::class)
            ->setVersion(config('app.version'))
            ->setUser(auth()->id() ? ['identifier' => (string) auth()->id()] : null)
            ->SendException($e);
    }
    parent::report($e);
}

Bind the client as a singleton so tags and user context persist across a request, and so tests can swap it with a mock:

$this->app->singleton(RaygunClient::class, fn () => new RaygunClient(
    config('services.raygun.key'),
    async: true, // curl-based, keeps the error path fast
));

Environment gating is non-negotiable. Reporting from local/testing floods the dashboard with noise and burns quota. Gate on app()->environment('production', 'staging') and !app()->runningUnitTests().

Async by default, sync only for critical paths. raygun4php supports non-blocking sends via curl. For an exception handler, latency matters — the user is already having a bad time; don't add 300ms of HTTP round-trip to their response.

Enrich the payload at the call site, not globally. Where a request has meaningful business context (tenant ID, order ID, feature flag state), attach it:

app(RaygunClient::class)->setUser([
    'identifier' => (string) $user->id,
    'isAnonymous' => false,
    'email'      => $user->email,
]);

Pair with, don't duplicate, your log handler. raygun4php ships a Monolog handler. If you already pipe critical to Slack and want everything above error in Raygun, use the Monolog handler for the log stream and keep exception reporting separate — otherwise every Log::error() inside a caught exception doubles your Raygun ingestion.

Extension points in the original bundle worth mirroring: the service alias for the client (so you can decorate it), and a config flag to toggle the listener off without unregistering the bundle. In a port, that's a config key + a conditional bind.

Gotchas and Tips

• The package is effectively unmaintained for any modern framework. Symfony2 only; it predates Symfony 3's service autoconfiguration and PHP 7's error hierarchy handling in places. Installing it in a Symfony 4+/Laravel app will either fail dependency resolution or silently do nothing. Vendor the listener pattern instead.
• Verify the config key namespace before writing YAML. Symfony bundle conventions mean the root key is derived from getAlias() in the extension class, not from the package name on Packagist. Run bin/console debug:config <alias> (Symfony 3+) or just read Configuration.php — copy-pasting a blog snippet with raygun: vs nietonfir_raygun: is the #1 first-hour time sink.
• Console exceptions won't be caught by a kernel.exception listener in the way you expect. Symfony2 console uses its own error handling; your cron/queue workers will be invisible to Raygun unless you add a separate console listener or a global set_exception_handler. This is the most common "it works in the browser but not in the worker" surprise.
• Filter aggressively. By default you'll capture NotFoundHttpException, validation failures, and auth redirects — all of which are expected behavior. Maintain a skip list (status codes < 500, known ValidationException/AuthenticationException types) or your signal-to-noise ratio collapses within a week.
• Don't double-report. If both the bundle listener and the Monolog handler are active, one exception becomes two Raygun events with different fingerprints. Pick one path per exception type.
• API key handling. In the original bundle the key comes through parameters.yml, which is the right instinct — keep it out of config.yml and out of version control. Rotate it if it's ever been committed; Raygun keys can be used to inject events into your account.
• PII and payload size. User identifiers, emails, and request bodies are captured by default in some configurations. For anything under GDPR, either set the user to an opaque internal ID or scrub before sending. Also check the truncation behavior on stack traces — deeply nested Laravel/Doctrine frames can get clipped.
• Debugging an empty dashboard: check (a) the bundle is in AppKernel, (b) the key is non-empty at runtime (debug:container --parameter=...), (c) your gate condition isn't evaluating false under the current APP_ENV, (d) curl isn't blocked by an outbound firewall. In async mode a failed send is silent by design — temporarily flip to sync while debugging.
• Testability. Because the client is injected via the container, you can swap a fake that records SendException calls and assert in a functional test that a thrown exception produces exactly one report. This is worth doing once — it's the only thing that catches the double-report regression.