Gps Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require enqueue/gps
   

2. Configure Google Cloud credentials:

   • Set GOOGLE_APPLICATION_CREDENTIALS environment variable to point to your service account JSON key file.
   • Alternatively, configure credentials via Google\Cloud\Core\Grpc\CredentialsPool in your code.

3. Basic usage with Enqueue:

   use Enqueue\Client\Producer;
   use Enqueue\Client\Consumer;
   use Enqueue\Gps\GpsConnectionFactory;
   
   $connectionFactory = new GpsConnectionFactory('your-project-id');
   $connection = $connectionFactory->createConnection(['topic' => 'your-topic-name']);
   
   // Producer
   $producer = new Producer($connection);
   $producer->send(new \Enqueue\Message\Message(['data' => 'Hello Pub/Sub!']));
   
   // Consumer
   $consumer = new Consumer($connection);
   $consumer->consume(function (\Enqueue\Message\Message $message) {
       echo $message->getBody();
       return \Enqueue\Message\Message::ACK;
   });
   

First Use Case

• Send a delayed message:

  $producer->send(new \Enqueue\Message\Message(['data' => 'Delayed!'], [
      'delay' => 60, // 60 seconds delay
  ]));
  

Implementation Patterns

Common Workflows

1. Topic-Based Routing:

   • Use different topics for different message types (e.g., orders, notifications).
   • Configure the connection factory with the appropriate topic per producer/consumer.

2. Batch Processing:

   • Leverage Pub/Sub's batching for high-throughput scenarios:

     $connectionFactory->createConnection(['topic' => 'high-volume-topic', 'batchSettings' => [
         'maxMessages' => 100,
         'maxBytes' => 1024 * 1024, // 1MB
         'maxDelay' => 10, // 10 seconds
     ]]);
     

3. Error Handling:

   • Implement dead-letter queues (DLQ) via subscription settings:

     $connectionFactory->createConnection(['subscription' => 'your-subscription', 'ackDeadline' => 30]);
     

4. Integration with Laravel:

   • Use enqueue/laravel alongside enqueue/gps for seamless Laravel queue integration:

     $connection = new \Enqueue\Gps\GpsConnectionFactory('project-id');
     $queue = new \Enqueue\Laravel\LaravelQueue($connection);
     

Integration Tips

• Environment Configuration: Store project ID, topic/subscription names, and credentials in .env:

  QUEUE_GPS_PROJECT_ID=your-project-id
  QUEUE_GPS_TOPIC=your-topic
  QUEUE_GPS_SUBSCRIPTION=your-subscription
  

• Dependency Injection: Bind the connection factory in Laravel's service provider:

  $this->app->bind(\Enqueue\Gps\GpsConnectionFactory::class, function ($app) {
      return new \Enqueue\Gps\GpsConnectionFactory(
          $app['config']['queue.gps.project_id']
      );
  });
  

• Monitoring: Use Pub/Sub's built-in metrics (e.g., subscription/backlog_bytes) to monitor queue health.

Gotchas and Tips

Pitfalls

1. Credentials Handling:

   • Gotcha: Forgetting to set GOOGLE_APPLICATION_CREDENTIALS or providing invalid credentials will throw Google\Auth\Exception\InvalidCredentialsException.
   • Fix: Use Google\Cloud\Core\Grpc\CredentialsPool for dynamic credential loading or ensure the environment variable is set.

2. Subscription vs. Topic:

   • Gotcha: Confusing topics (publishers) and subscriptions (consumers). Messages are published to topics but consumed from subscriptions.
   • Fix: Always pair a topic with its subscription in your connection configuration.

3. Ack Deadlines:

   • Gotcha: Missing messages if the consumer takes longer than the ackDeadline (default: 10 seconds) to process a message.
   • Fix: Set an appropriate ackDeadline (e.g., 30 seconds for long-running tasks) or use modifyAckDeadline to extend it dynamically.

4. Message Size Limits:

   • Gotcha: Pub/Sub has a 10MB message limit. Large payloads will fail.
   • Fix: Compress payloads or split large messages into chunks.

Debugging

• Enable Debug Logging:

  $connectionFactory = new GpsConnectionFactory('project-id', [
      'logger' => new \Monolog\Logger('gps', [
          new \Monolog\Handler\StreamHandler('php://stderr', \Monolog\Logger::DEBUG),
      ]),
  ]);
  

• Check Pub/Sub Metrics: Use Google Cloud Console to verify message flow:

  • Published messages: Topic metrics (publish_requests, publish_errors).
  • Subscribed messages: Subscription metrics (pull_requests, ack_deadline_exceeded).

Extension Points

1. Custom Message Serialization: Override the default JSON serializer for complex objects:

   $connectionFactory = new GpsConnectionFactory('project-id', [
       'serializer' => new \Enqueue\Gps\Serializer\CustomSerializer(),
   ]);
   

2. Retry Logic: Implement custom retry logic for transient failures:

   $connectionFactory->createConnection(['subscription' => 'your-subscription', 'retrySettings' => [
       'maxRetries' => 3,
       'initialBackoff' => 100, // ms
   ]]);
   

3. Middleware: Use Enqueue's middleware system to add preprocessing/postprocessing:

   $producer = new Producer($connection);
   $producer->withMiddleware(new \Enqueue\Middleware\Middleware\LoggingMiddleware());
   

Config Quirks

• Default Topic/Subscription: If neither topic nor subscription is provided, the connection will default to the project ID as the topic name (not recommended for production).

• Region Selection: Explicitly set the region in the connection factory if not using the default (us-central1):

  $connectionFactory = new GpsConnectionFactory('project-id', ['region' => 'europe-west1']);