Spot Hit Notifier Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require symfony/spot-hit-notifier
   

   Verify the package is autoloaded in composer.json under autoload.psr-4.

2. Configuration Add the bundle to config/bundles.php (Symfony) or register the service provider in config/app.php (Laravel via Symfony bridge):

   // Laravel (via Symfony bridge)
   $provider = new \Symfony\Component\HttpKernel\KernelEvents::class;
   $this->app->register(\Symfony\SpotHitNotifier\SpotHitNotifierBundle::class);
   

3. First Use Case Trigger a notification in a controller or service:

   use Symfony\Component\SpotHitNotifier\SpotHitNotifier;
   
   public function sendNotification()
   {
       $notifier = app(SpotHitNotifier::class);
       $notifier->send('user@example.com', 'Welcome!', 'Your account is ready.');
       return response()->json(['success' => true]);
   }
   

Implementation Patterns

Core Workflows

1. Event-Driven Notifications Hook into Laravel events (e.g., Illuminate\Auth\Events\Registered) to send automated alerts:

   use Illuminate\Support\Facades\Event;
   use Symfony\Component\SpotHitNotifier\SpotHitNotifier;
   
   Event::listen('Illuminate\Auth\Events\Registered', function ($user) {
       $notifier = app(SpotHitNotifier::class);
       $notifier->send($user->email, 'Registration Confirmation', 'Verify your email...');
   });
   

2. Template-Based Emails Use Twig templates (if integrated) for dynamic content:

   $notifier->sendTwig('user@example.com', 'Welcome', 'emails/welcome.twig', [
       'name' => 'John Doe',
   ]);
   

3. Batch Processing Queue notifications for async delivery (Laravel Queue integration):

   $notifier->queueSend('user@example.com', 'Digest', 'Your weekly update...');
   

Integration Tips

• Laravel Mail Integration: Extend the notifier to use Laravel’s Mail facade for unified email handling.
• Logging: Wrap calls in try-catch to log failures:

  try {
      $notifier->send($email, $subject, $body);
  } catch (\Exception $e) {
      \Log::error("Notification failed: " . $e->getMessage());
  }
  

• Configuration: Override defaults in config/services.php:

  'spot_hit_notifier' => [
      'api_key' => env('SPOT_HIT_API_KEY'),
      'default_from' => 'noreply@example.com',
  ],
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Hardcoding keys in code violates security. Use Laravel’s .env:

     SPOT_HIT_API_KEY=your_key_here
     

   • Never commit .env to version control.

2. Rate Limits

   • Spot-Hit may throttle requests. Implement exponential backoff in retries:

     $attempts = 0;
     while ($attempts < 3) {
         try {
             $notifier->send(...);
             break;
         } catch (\Symfony\Component\SpotHitNotifier\Exception\RateLimitExceeded $e) {
             sleep(2 ** $attempts);
             $attempts++;
         }
     }
     

3. Template Caching

   • Twig templates may not auto-reload. Clear cache after updates:

     php artisan view:clear
     

Debugging

• Enable Verbose Logging: Set SPOT_HIT_DEBUG=true in .env to log API responses.
• Mocking for Tests: Use Laravel’s Mockery to stub the notifier:

  $mock = Mockery::mock(SpotHitNotifier::class);
  $mock->shouldReceive('send')->once();
  $this->app->instance(SpotHitNotifier::class, $mock);
  

Extension Points

1. Custom Transport Extend Symfony\Component\SpotHitNotifier\Transport\TransportInterface to support additional channels (e.g., SMS):

   class CustomTransport implements TransportInterface {
       public function send(Notification $notification) {
           // Custom logic (e.g., Twilio API)
       }
   }
   

2. Event Listeners Subscribe to SpotHitNotifierEvents for pre/post-send hooks:

   use Symfony\Component\SpotHitNotifier\Event\NotificationSentEvent;
   
   Event::listen(NotificationSentEvent::class, function ($event) {
       \Log::info("Sent to {$event->getRecipient()}");
   });
   

3. Laravel Notifications Bridge with Laravel’s Notifiable trait for unified notifications:

   use Illuminate\Notifications\Notifiable;
   use Symfony\Component\SpotHitNotifier\SpotHitChannel;
   
   class User extends Model implements Notifiable {
       public function routeNotificationForSpotHit() {
           return $this->email;
       }
   }