Messenger Tarantool Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexlcdee/messenger-tarantool
   

   Ensure ext-tarantool is installed in your PHP environment.

2. Configuration: Add the service provider and bind the client in config/app.php:

   'providers' => [
       // ...
       Alexlcdee\MessengerTarantool\TarantoolServiceProvider::class,
   ],
   

3. Publish Config (if needed):

   php artisan vendor:publish --provider="Alexlcdee\MessengerTarantool\TarantoolServiceProvider"
   

   Configure config/messenger-tarantool.php with your Tarantool connection details (host, port, user/password if required).

4. First Use Case: Dispatch a message to Tarantool via Laravel's Messenger:

   use Alexlcdee\MessengerTarantool\TarantoolMessage;
   
   // In a controller or command:
   dispatch(new TarantoolMessage('your_space', 'your_box', [
       'key' => 'unique_key',
       'data' => ['message' => 'Hello, Tarantool!']
   ]));
   

Implementation Patterns

Workflows

1. Synchronous vs. Asynchronous:

   • Use TarantoolMessage for async dispatch (via Laravel's queue system).
   • For sync operations, inject the TarantoolClient directly:

     use Alexlcdee\MessengerTarantool\TarantoolClient;
     
     public function __construct(TarantoolClient $client) {
         $this->client = $client;
     }
     
     public function syncOperation() {
         $this->client->call('space', 'function', ['args']);
     }
     

2. Handling Responses:

   • Async messages (via Messenger) don’t return responses. Use callbacks or poll Tarantool for results.
   • Sync calls return raw Tarantool responses (arrays). Parse as needed:

     $response = $this->client->call('space', 'get', [123]);
     $data = $response[1] ?? null; // Tarantool responses are [success, data, error]
     

3. Batch Operations:

   • Use TarantoolClient::call() with batch requests:

     $this->client->call('space', 'insert', [
         {1, {name: 'Alice', age: 30}},
         {2, {name: 'Bob', age: 25}}
     ]);
     

4. Error Handling:

   • Wrap calls in try-catch:

     try {
         $this->client->call('space', 'unsafe', ['risky']);
     } catch (\Tarantool\Exception\TarantoolException $e) {
         Log::error("Tarantool error: " . $e->getMessage());
     }
     

Integration Tips

• Laravel Queues: Configure config/queue.php to use messenger-tarantool as a driver for async operations.
• Retry Logic: Leverage Laravel’s retry-after for transient failures:

  dispatch((new TarantoolMessage(...))->retryAfter(30));
  

• Logging: Enable debug logging in config/messenger-tarantool.php to trace requests/responses.

Gotchas and Tips

Pitfalls

1. Connection Management:

   • The package assumes a persistent connection. If Tarantool restarts, reconnect manually:

     $this->client->connect(); // Re-establish connection
     

   • Tip: Use Laravel’s connection events to handle reconnects globally.

2. Schema Mismatches:

   • Tarantool is schema-less but expects consistent data formats. Validate payloads before sending:

     if (!isset($data['required_field'])) {
         throw new \InvalidArgumentException("Missing field");
     }
     

3. Async Race Conditions:

   • Async TarantoolMessage dispatches don’t wait for Tarantool to process. Use unique keys or callbacks to correlate responses.

4. Deprecated Methods:

   • The package is outdated (last release 2020). Some Tarantool PHP extensions (e.g., ext-tarantool) may have breaking changes. Test thoroughly.

Debugging

• Enable Verbose Logging: Set 'debug' => true in config to log raw requests/responses.
• Check Tarantool Logs: Inspect Tarantool’s console.log for errors if messages aren’t processed.
• Validate Payloads: Use var_dump($response) to inspect Tarantool’s response structure (e.g., [true, data] vs [false, error]).

Extension Points

1. Custom Message Classes: Extend TarantoolMessage to add metadata or validation:

   class CustomTarantoolMessage extends TarantoolMessage {
       public function __construct($space, $box, array $data, public string $customField) {
           parent::__construct($space, $box, $data);
       }
   }
   

2. Middleware: Add middleware to transform messages before dispatch:

   $bus->pipe(function ($message, $next) {
       $message->data['timestamp'] = now()->toDateTimeString();
       return $next($message);
   });
   

3. Fallback Drivers: Implement a fallback to Redis or database if Tarantool is unavailable:

   try {
       $this->client->call(...);
   } catch (\Exception $e) {
       // Fallback logic
   }