Nats Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require basis-company/nats
   

   Ensure libsodium or sodium_compat is installed for NKeys functionality.

2. Basic Connection Initialize a client with default or custom configuration:

   use Basis\Nats\Client;
   use Basis\Nats\Configuration;
   
   $client = new Client(new Configuration(host: 'nats-service'));
   $client->ping(); // Verify connection
   

3. First Use Case: Pub/Sub Publish a message and subscribe to it:

   $client->publish('test.subject', 'Hello NATS!');
   $queue = $client->subscribe('test.subject');
   $message = $queue->next();
   echo $message->payload; // Output: "Hello NATS!"
   

Where to Look First

• README.md: Covers installation, connection, and basic usage.
• src/: Core classes like Client, Configuration, and Message.
• tests/: Real-world examples and edge cases.

Implementation Patterns

Core Workflows

1. Pub/Sub with Queues

• Pattern: Use queues for reliable message consumption.
• Example:

  $queue = $client->subscribe('orders.created');
  while ($message = $queue->next()) {
      processOrder($message->payload);
      $message->ack(); // Acknowledge receipt
  }
  

2. Request-Response

• Pattern: Sync/async request handling.
• Example:

  // Sync (blocking)
  $response = $client->dispatch('rpc.user', 'fetch:123');
  
  // Async (non-blocking)
  $client->request('rpc.user', 'fetch:123', function ($resp) {
      logResponse($resp);
  });
  $client->process(); // Process callbacks
  

3. JetStream Integration

• Pattern: Use streams/consumers for persistence and workflows.
• Example:

  $stream = $client->getApi()->getStream('orders');
  $stream->create(); // Auto-configure with defaults
  $stream->put('orders.new', json_encode(['id': 123]));
  
  $consumer = $stream->getConsumer('processor');
  $consumer->handle(function ($msg) {
      // Process message
      $msg->ack();
  });
  

4. Microservices

• Pattern: Define endpoints under a service group.
• Example:

  $service = $client->service('UserService', 'Handles user operations', '1.0');
  $v1 = $service->addGroup('v1');
  $v1->addEndpoint('create', CreateUserHandler::class);
  $service->run();
  

5. Key-Value Storage

• Pattern: Store/retrieve small data chunks.
• Example:

  $bucket = $client->getApi()->getBucket('config');
  $bucket->put('theme', 'dark');
  echo $bucket->get('theme'); // "dark"
  

Integration Tips

• Error Handling: Wrap NATS operations in try-catch blocks:

  try {
      $client->publish('critical', 'alert');
  } catch (\Basis\Nats\Exception\NatsException $e) {
      logError($e);
  }
  

• Connection Management: Reuse Client instances; avoid recreating for every request.
• Async Processing: Use process() to handle callbacks in loops or long-running scripts.

Gotchas and Tips

Pitfalls

1. Connection Timeouts

   • Issue: Long-running scripts may drop connections.
   • Fix: Use ping() periodically or implement heartbeat logic:

     if (!$client->ping()) reconnect();
     

2. Message Ordering

   • Issue: JetStream streams with WORK_QUEUE retention may reorder messages.
   • Fix: Use LAST_MESSAGE or SAMPLES retention for strict ordering.

3. Consumer Leaks

   • Issue: Ephemeral consumers aren’t auto-cleaned immediately.
   • Fix: Explicitly delete or let NATS handle cleanup (delayed by seconds).

4. Payload Size Limits

   • Issue: Large payloads (>64KB) may fail silently.
   • Fix: Compress payloads or use JetStream for large data.

5. NKey/JWT Expiry

   • Issue: JWT tokens expire; reconnection may fail.
   • Fix: Rotate credentials or implement token refresh logic.

Debugging Tips

• Enable Verbose Logging:

  $config = new Configuration(verbose: true);
  

• Check NATS Server Logs: Use nats-server -DV for debug output.
• Use fetch() vs next():
  • fetch(): Non-blocking (returns null if empty).
  • next(): Blocks until a message arrives (use with timeout).

Extension Points

1. Custom Middleware

   • Override Client::publish() or Client::subscribe() to add logic:

     $client->subscribe('audit.*', function ($msg) {
         auditLog($msg->subject, $msg->payload);
     });
     

2. JetStream Hooks

   • Extend Stream or Consumer classes to add pre/post-processing:

     class CustomStream extends \Basis\Nats\Stream\Stream {
         public function put($subject, $data) {
             $this->logPut($subject, $data); // Custom logic
             parent::put($subject, $data);
         }
     }
     

3. Performance Tuning

   • Adjust batching for consumers:

     $consumer->setBatching(100)->setIterations(5);
     

   • Disable verbose mode in production:

     $config = new Configuration(verbose: false);
     

4. TLS Quirks

   • Self-Signed Certs: Ensure tlsCaFile points to the CA bundle.
   • Mutual TLS: Verify tlsCertFile and tlsKeyFile paths are correct.

Configuration Quirks

• Default Delays: Retry delays default to 0.001 (1ms) in CONSTANT mode.
• JetStream API: Some methods (e.g., getStream()) return null if the stream doesn’t exist.
• Service Endpoints: Wildcards (*) in subject filters match literally (not regex).

Pro Tips

• Use Payload for Headers:

  $payload = new \Basis\Nats\Message\Payload('data', [
      'X-Custom-Header' => 'value'
  ]);
  $client->publish('subject', $payload);
  

• Leverage Ephemeral Consumers for short-lived workers (auto-cleanup).
• Monitor Streams: Use stream->info() to track message counts and lag.
• Combine with Laravel:

  // In a Laravel service provider
  $this->app->singleton(Client::class, function () {
      return new Client(new Configuration(host: config('nats.host')));
  });