Ratchetio Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require colemando/ratchetio-bundle in your Laravel project (note: this bundle is Symfony2-focused, but can be adapted for Laravel via bridge packages like symfony/bundle or manual integration).

2. Service Provider & Config

   • Publish the bundle’s config (if available) or manually add the config to config/services.php:

     'ratchetio' => [
         'access_token' => env('RATCHETIO_ACCESS_TOKEN'),
     ],
     

   • Register a service provider in config/app.php:

     'providers' => [
         // ...
         Ratchetio\ServiceProvider::class,
     ],
     

3. First Use Case: Logging Exceptions Wrap your application’s exception handler (e.g., app/Exceptions/Handler.php) to forward errors to Ratchet.io:

   use Ratchetio\Ratchetio;
   
   public function report(Throwable $exception)
   {
       Ratchetio::send($exception);
       parent::report($exception);
   }
   

Implementation Patterns

Core Workflows

1. Exception Reporting

   • Automatic Capture: Use Laravel’s App\Exceptions\Handler to auto-send exceptions to Ratchet.io.
   • Manual Triggers: Send custom events or errors:

     Ratchetio::send(new \RuntimeException("Custom error message"));
     

2. Configuration Management

   • Dynamic Tokens: Fetch tokens from .env or cache them:

     config(['ratchetio.access_token' => env('RATCHETIO_TOKEN')]);
     

   • Environment-Specific Tokens: Override tokens per environment (e.g., config/ratchetio.php).

3. Integration with Monolog

   • Extend Laravel’s logging to include Ratchet.io:

     use Ratchetio\Handler\RatchetioHandler;
     
     $logger->pushHandler(new RatchetioHandler(config('ratchetio.access_token')));
     

Advanced Patterns

• Middleware for API Errors: Log API-specific errors in middleware:

  public function handle($request, Closure $next)
  {
      try {
          return $next($request);
      } catch (\Symfony\Component\HttpKernel\Exception\HttpException $e) {
          Ratchetio::send($e);
          throw $e;
      }
  }
  

• Batch Processing: Use queues to defer error reporting:

  Ratchetio::queue(new \RuntimeException("Deferred error"));
  

Gotchas and Tips

Common Pitfalls

1. Token Security

   • Never hardcode tokens in config files. Use .env or Laravel’s env() helper.
   • Validate tokens: Add a fallback handler if the token is missing:

     if (!config('ratchetio.access_token')) {
         throw new \RuntimeException("Ratchet.io token not configured");
     }
     

2. Performance Overhead

   • Avoid blocking requests: Use queues or async processing for non-critical errors.
   • Rate limiting: Ratchet.io may throttle requests; implement retries with exponential backoff.

3. Symfony2 Legacy

   • Laravel-Specific Quirks: The bundle assumes Symfony’s HttpFoundation; wrap exceptions in Laravel’s HttpException for compatibility:

     Ratchetio::send(new \Symfony\Component\HttpKernel\Exception\HttpException(500, "Error"));
     

Debugging Tips

• Log Locally First: Test locally by logging to a file before sending to Ratchet.io:

  Ratchetio::setLogger(new \Monolog\Logger('test', [new \Monolog\Handler\StreamHandler(storage_path('logs/ratchetio.log'))]));
  

• Check HTTP Status: Ensure Ratchet.io’s API is reachable (status 200 for successful submissions).
• Payload Validation: Verify the payload structure matches Ratchet.io’s API expectations (e.g., error_class, message).

Extension Points

1. Custom Payloads Override the default payload structure:

   Ratchetio::setPayloadTransformer(function ($exception) {
       return [
           'error_class' => get_class($exception),
           'message' => $exception->getMessage(),
           'extra' => ['user_id' => auth()->id()],
       ];
   });
   

2. Webhook Integration Extend the bundle to trigger webhooks on critical errors:

   Ratchetio::onSend(function ($payload) {
       Http::post('https://your-webhook.com', $payload);
   });
   

3. Testing Mock Ratchet.io in tests:

   Ratchetio::setClient(new class {
       public function send($payload) {
           // Assert payload or store for testing
       }
   });