Getting Started

Minimal Setup

Installation:
```
composer require tarantool/queue
```
Ensure your composer.json includes "minimum-stability": "dev" if using pre-release versions.

Configuration: Add to .env:

QUEUE_CONNECTION=tarantool
TARANTOOL_QUEUE_HOST=127.0.0.1
TARANTOOL_QUEUE_PORT=3301
TARANTOOL_QUEUE_USER=guest
TARANTOOL_QUEUE_PASSWORD=
TARANTOOL_QUEUE_DB=test

First Job: Define a job class:

namespace App\Jobs;

use Tarantool\Queue\Job;
use Tarantool\Queue\ShouldQueue;

class ProcessPayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue;

    public $paymentId;

    public function __construct($paymentId)
    {
        $this->paymentId = $paymentId;
    }

    public function handle()
    {
        // Logic here
    }
}

Dispatch a Job:
```
ProcessPayment::dispatch($paymentId);
```

Run the Queue Worker:

php artisan queue:work tarantool --sleep=3 --tries=3

Where to Look First

Documentation: GitHub README (if available) or Laravel Queue Documentation for general patterns.
Config: config/queue.php for connection settings.
Job Classes: app/Jobs/ for reusable job logic.

Implementation Patterns

Core Workflows

Job Dispatching:

Use dispatch() or dispatchNow() for synchronous/asynchronous execution.

Batching:

ProcessPayment::dispatch($paymentId)->onQueue('high_priority');

Delayed Jobs:

ProcessPayment::dispatch($paymentId)->delay(now()->addMinutes(10));

Queue Workers:

Single Worker:

php artisan queue:work tarantool --queue=high_priority

Multiple Workers (for parallel processing):

php artisan queue:work tarantool --daemon --sleep=3 --tries=3 &
php artisan queue:work tarantool --daemon --sleep=3 --tries=3 &

Supervisor Setup: Use supervisord to manage persistent workers.

Job Monitoring:
- Failed Jobs: Check failed_jobs table (if using database) or Tarantool’s admin interface.
- Logging: Enable queue logging in config/queue.php:
```
'log' => env('QUEUE_LOG', true),
'log_level' => env('QUEUE_LOG_LEVEL', 'info'),
```

Retry Logic:

Configure retries in app/Exceptions/Handler.php:

public function register()
{
    $this->reportable(function (JobFailedException $e) {
        if ($e->attempts() >= 3) {
            // Log or notify
        }
    });
}

Integration Tips

Laravel Events: Convert events to jobs for async processing:

event(new PaymentProcessed($paymentId));
// In listener:
ProcessPayment::dispatch($paymentId);

Tarantool-Specific Features:
- Lua Scripts: Offload heavy processing to Tarantool using Tarantool\Queue\Job::call().
- Custom Serialization: Override serialize()/unserialize() in jobs for complex data.

Testing:

Use Queue::fake() for unit tests:

public function test_job_dispatch()
{
    Queue::fake();
    ProcessPayment::dispatch(123);
    Queue::assertPushed(ProcessPayment::class);
}

Tarantool Docker: Spin up a local Tarantool instance for integration tests:
```
docker run -p 3301:3301 tarantool/tarantool
```

Gotchas and Tips

Pitfalls

Connection Issues:
- Symptom: Jobs stuck in waiting state or worker crashes.
- Fix: Verify TARANTOOL_QUEUE_HOST/PORT in .env. Use --verbose in worker:
```
php artisan queue:work tarantool --verbose
```
- Timeouts: Increase TARANTOOL_CONNECT_TIMEOUT in config if network latency is high.

Job Serialization:

Issue: Complex objects (e.g., Eloquent models) may fail to serialize.

Solution: Use ShouldQueue trait and implement serialize()/unserialize():

public function serialize()
{
    return [
        'payment_id' => $this->paymentId,
        'user_id' => $this->user->id, // Ensure user is loaded
    ];
}

Failed Jobs:
- Problem: Failed jobs pile up in Tarantool’s queue.
- Solution:
  - Run php artisan queue:retry to retry failed jobs.
  - Delete stale failed jobs:
```
php artisan queue:flush
```
  - For Tarantool-specific cleanup, use its admin box:
```
-- In Tarantool console:
box.space._queue:drop()
```
Worker Stalling:
- Cause: Long-running jobs or deadlocks.
- Fix:
  - Set --timeout in worker (default: 60s):
```
php artisan queue:work tarantool --timeout=120
```
  - Use --memory to limit memory usage:
```
php artisan queue:work tarantool --memory=128M
```

Debugging Tips

Enable Debug Mode:
```
QUEUE_DEBUG=true
```
Logs will show job lifecycle events.
Inspect Queue:
- Use Tarantool’s admin box to check queue status:
```
box.space._queue:select()
```
- List active jobs:
```
php artisan queue:list
```

Custom Middleware:

Add middleware to jobs for pre/post-processing:

namespace App\Jobs\Middleware;

class LogJobExecution
{
    public function handle($job, $next)
    {
        \Log::info("Job started: {$job->job}");
        $next($job);
        \Log::info("Job completed: {$job->job}");
    }
}

protected $middleware = [
    \App\Jobs\Middleware\LogJobExecution::class,
];

Extension Points

Custom Queue Connection: Extend TarantoolQueue for custom logic:

namespace App\Queues;

use Tarantool\Queue\TarantoolQueue as BaseQueue;

class CustomTarantoolQueue extends BaseQueue
{
    public function pushRaw($job, $data, $queue = null)
    {
        // Custom logic (e.g., add metadata)
        return parent::pushRaw($job, $data, $queue);
    }
}

'connections' => [
    'tarantool' => [
        'driver' => 'custom-tarantool',
        // ...
    ],
],

Job Events: Listen for job events globally:

use Tarantool\Queue\Events\JobProcessed;
use Tarantool\Queue\Events\JobFailed;

Event::listen(JobProcessed::class, function ($event) {
    // Log success
});

Event::listen(JobFailed::class, function ($event) {
    // Notify Slack/email
});

Tarantool Lua Extensions: Write Lua scripts for Tarantool to process jobs natively:

-- Save as /path/to/process_payment.lua
local function process_payment(payment_id)
    -- Tarantool logic here
end

Call from PHP:

$result = \DB::connection('tarantool')->selectOne('process_payment', [$paymentId]);

Queue Laravel Package