Airgram Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the bundle via Composer:

   composer require bbit/airgram-bundle:dev-master
   

   Enable in AppKernel.php:

   new BBIT\AirGramBundle\BranchBitAirGramBundle(),
   

2. Configuration: Add to config.yml:

   branch_bit_air_gram:
       apis:
           default:
               key: your_airgram_api_key
               secret: your_airgram_api_secret
   

3. First Use Case: Inject the service in a controller/service:

   use BBIT\AirGramBundle\Service\AirGramService;
   
   class MyController extends Controller
   {
       public function sendNotification(AirGramService $airgram)
       {
           $airgram->subscribe('user@example.com');
           $airgram->send('user@example.com', 'Hello from AirGram!');
       }
   }
   

Implementation Patterns

Core Workflows

1. Service Integration:

   • Use dependency injection to leverage AirGramService in controllers, commands, or event listeners.
   • Example: Trigger notifications in a UserRegisteredEvent subscriber:

     public function onUserRegistered(UserRegisteredEvent $event)
     {
         $this->airgram->subscribe($event->getUser()->email);
         $this->airgram->send($event->getUser()->email, 'Welcome!');
     }
     

2. API Configuration:

   • Define multiple API configurations (e.g., staging, production) in config.yml:

     branch_bit_air_gram:
         apis:
             staging:
                 key: staging_key
                 secret: staging_secret
             production:
                 key: prod_key
                 secret: prod_secret
     

   • Switch contexts dynamically:

     $this->airgram->setApi('production');
     

3. Batch Operations:

   • Loop through users and send messages (e.g., in a cron job):

     foreach ($users as $user) {
         $this->airgram->send($user->email, 'Your monthly update');
     }
     

Integration Tips

• Event-Driven Notifications: Pair with Symfony’s event system (e.g., KernelEvents::TERMINATE) to send post-request notifications.
• Logging: Wrap calls in try-catch to log failures:

  try {
      $this->airgram->send($email, $message);
  } catch (\Exception $e) {
      $this->logger->error('AirGram failed', ['error' => $e->getMessage()]);
  }
  

• Testing: Mock the service in PHPUnit:

  $mock = $this->createMock(AirGramService::class);
  $mock->method('send')->willReturn(true);
  $this->container->set('bbit_airgam', $mock);
  

Gotchas and Tips

Pitfalls

1. Deprecated Package:

   • Last updated in 2015; verify API compatibility with AirGram’s current endpoints.
   • Risk: Breaking changes if AirGram’s API evolves (e.g., OAuth2, new payload formats).
   • Workaround: Fork the bundle and update the HTTP client logic.

2. No Async Support:

   • Synchronous calls block execution. For high-volume sends, consider:
     • Queueing messages with Symfony Messenger or Laravel Queues.
     • Implementing a retry mechanism for failed requests.

3. Configuration Overrides:

   • Hardcoded default API key in the bundle’s source (see Services/AirGramService.php).
   • Fix: Override the service definition in config/services.yml:

     services:
         bbit_airgam:
             class: BBIT\AirGramBundle\Service\AirGramService
             arguments: ['@branch_bit_air_gram.api.default']
     

Debugging

• HTTP Errors: Enable debug mode and inspect the raw response:

  $response = $this->airgram->getClient()->send($request);
  $this->logger->debug('AirGram response', ['status' => $response->getStatusCode(), 'body' => $response->getBody()]);
  

• Authentication: Validate key/secret in config.yml—invalid credentials return 401 or 403.

Extension Points

1. Custom Payloads: Extend AirGramService to support custom message templates:

   namespace App\Service;
   
   use BBIT\AirGramBundle\Service\AirGramService;
   
   class CustomAirGramService extends AirGramService
   {
       public function sendTemplate($email, $templateName, array $data)
       {
           $payload = ['template' => $templateName, 'data' => $data];
           return $this->send($email, json_encode($payload));
       }
   }
   

   Register as a service in config/services.yml:

   services:
       app.custom_airgram:
           class: App\Service\CustomAirGramService
           parent: bbit_airgam
   

2. Webhook Handling: Add a controller to process AirGram webhooks (if supported):

   class AirGramWebhookController extends Controller
   {
       public function handle(Request $request)
       {
           $payload = json_decode($request->getContent(), true);
           // Process event (e.g., 'message_delivered')
       }
   }
   

   Route in routing.yml:

   airgram_webhook:
       path: /airgram/webhook
       methods: [POST]
       defaults: { _controller: App\Controller\AirGramWebhookController::handle }
   

3. Rate Limiting: Implement a decorator to throttle requests:

   class ThrottledAirGramService
   {
       private $decorated;
       private $limit;
   
       public function __construct(AirGramService $decorated, int $limit)
       {
           $this->decorated = $decorated;
           $this->limit = $limit;
       }
   
       public function send($email, $message)
       {
           if ($this->exceedsLimit()) {
               throw new \RuntimeException('Rate limit exceeded');
           }
           return $this->decorated->send($email, $message);
       }
   }
   

   Configure in config/services.yml:

   services:
       app.throttled_airgram:
           class: App\Service\ThrottledAirGramService
           arguments: ['@bbit_airgam', 100] # Max 100 requests/hour