Gps Messenger Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require petitpress/gps-messenger-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Petitpress\GpsMessengerBundle\PetitpressGpsMessengerBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console petitpress:gps-messenger:config:init
   

   Update config/packages/petitpress_gps_messenger.yaml with your Google Cloud credentials and project ID:

   petitpress_gps_messenger:
       client:
           project_id: "your-project-id"
           key_file: "%kernel.project_dir%/config/google-credentials.json"
       transports:
           gps_async:
               dsn: "gps://default/async-topic"
               options:
                   subscription: "async-subscription"
   

3. First Use Case Define a message class:

   namespace App\Message;
   
   class SendEmailMessage
   {
       public function __construct(public string $email, public string $subject) {}
   }
   

   Configure the transport in config/packages/messenger.yaml:

   messenger:
       transports:
           gps_async: "%env(MESSENGER_TRANSPORT_DSN)%"
       routing:
           'App\Message\SendEmailMessage': gps_async
   

   Dispatch a message:

   $bus->dispatch(new SendEmailMessage('user@example.com', 'Welcome!'));
   

Implementation Patterns

Workflow: Async Processing

1. Dispatch Messages Use the gps_async transport for background tasks (e.g., emails, reports):

   $bus->dispatch(new GenerateReportMessage($userId));
   

2. Handle Messages Create a worker to process messages:

   php bin/console messenger:consume gps_async -vv
   

   Or use a cron job for scheduled consumption.

3. Retry Logic Leverage Symfony Messenger’s retry mechanism via config:

   messenger:
       transports:
           gps_async:
               dsn: "gps://default/retry-topic"
               options:
                   retry_strategy:
                       max_retries: 3
                       delay: 1000
   

Integration Tips

• Error Handling Subscribe to Petitpress\GpsMessengerBundle\Event\MessageFailedEvent to log failures:

  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class GpsMessengerSubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [
              MessageFailedEvent::class => 'onMessageFailed',
          ];
      }
  
      public function onMessageFailed(MessageFailedEvent $event): void
      {
          // Log or notify (e.g., Slack)
      }
  }
  

• Batching Process messages in batches for efficiency:

  messenger:
      transports:
          gps_async:
              options:
                  batch_size: 50
  

• Environment-Specific Config Use .env for dynamic DSNs:

  transports:
      gps_async: "%env(MESSENGER_GPS_DSN)%"
  

  MESSENGER_GPS_DSN=gps://staging-topic
  

Gotchas and Tips

Pitfalls

1. Credentials Management

   • Never commit key_file paths to version control. Use environment variables or secure vaults.
   • Restrict service account permissions to only what’s needed (e.g., roles/pubsub.publisher and roles/pubsub.subscriber).

2. Subscription Management

   • Subscriptions must exist before consuming messages. Create them manually or via:

     php bin/console petitpress:gps-messenger:subscription:create async-subscription async-topic
     

3. Message Size Limits

   • Google Pub/Sub enforces a 10MB message limit. For larger payloads, use Cloud Storage or compress data.

4. Timeouts

   • Default timeout is 10 seconds. Adjust in config if processing is slow:

     options:
         timeout: 30.0
     

Debugging

1. Check Subscription Backlog Use the GCP Console or CLI to inspect pending messages:

   gcloud pubsub subscriptions pull async-subscription --auto-ack --limit 1
   

2. Enable Debugging Add to config/packages/monolog.yaml:

   handlers:
       gps_messenger:
           type: stream
           path: "%kernel.logs_dir%/gps_messenger.log"
           level: debug
           channels: ["messenger"]
   

3. Common Errors

   • "Subscription not found": Verify the subscription exists in GCP.
   • "Permission denied": Ensure the service account has correct IAM roles.
   • "Message too large": Reduce payload size or use compression.

Extension Points

1. Custom Middleware Add middleware to transform messages before sending:

   use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
   use Symfony\Component\Messenger\Envelope;
   
   class AddMetadataMiddleware implements MiddlewareInterface
   {
       public function handle(Envelope $envelope, callable $next): Envelope
       {
           $envelope = $next($envelope);
           $envelope = $envelope->with(new Metadata(['source' => 'laravel-app']));
           return $envelope;
       }
   }
   

   Register in config/packages/messenger.yaml:

   messenger:
       middleware:
           - App\Middleware\AddMetadataMiddleware
   

2. Dynamic Routing Route messages dynamically based on conditions:

   $bus->dispatch(new MyMessage(), ['transport' => $user->isPremium() ? 'gps_premium' : 'gps_async']);
   

3. Testing Mock the transport in tests:

   use Petitpress\GpsMessengerBundle\Transport\GpsTransport;
   
   $transport = $this->createMock(GpsTransport::class);
   $transport->method('send')->willReturn(new Envelope(new MyMessage()));
   $this->container->set(GpsTransport::class, $transport);