Client Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Pure PHP implementation aligns well with Laravel’s ecosystem, avoiding extension dependencies (except for optional decimal/uuid PECL extensions).
  • Middleware-based design enables seamless integration with Laravel’s middleware stack (e.g., logging, retries, auth) via withMiddleware().
  • DSN/URI support simplifies configuration, mirroring Laravel’s service provider/environment variable patterns.
  • SQL and binary protocol support covers Tarantool’s use cases, with SQL useful for hybrid apps leveraging both PHP and Lua.
  • Space/Index abstraction ($client->getSpace()) maps cleanly to Laravel’s Eloquent/Query Builder patterns.

• Cons:

  • No native Laravel service provider: Requires manual registration (e.g., in AppServiceProvider).
  • Limited async support: While Tarantool supports async, the PHP client is synchronous; Laravel’s async queues (e.g., Horizon) would need custom middleware.
  • No built-in connection pooling: Laravel’s queue workers or high-load apps may need external pooling (e.g., PcntlProcess).

Integration Feasibility

• Laravel Compatibility:
  • High: Works with Laravel 8+ (PHP 7.4+). Composer dependency is trivial.
  • Middleware Integration: Can wrap the client in Laravel’s middleware pipeline (e.g., App\Http\Middleware\TarantoolAuth).
  • Service Container: Bind the client to Laravel’s IoC via bind(Tarantool\Client\Client::class, fn() => Client::fromDsn(env('TARANTOOL_DSN'))).
• Database Abstraction:
  • Partial: While spaces/indexes mirror tables/relationships, Laravel’s Eloquent won’t auto-map without custom repositories.
  • Query Builder Gap: No Laravel Query Builder integration; raw Criteria/Operations must be used.

Technical Risk

• Critical:
  • Connection Resilience: Middleware order (e.g., RetryMiddleware vs. AuthenticationMiddleware) must be explicitly managed to avoid auth leaks on retries.
  • Type Handling: Custom types (e.g., Decimal, UUID) require PECL extensions for full performance; fallback to pure PHP may impact speed.
  • Error Handling: Laravel’s exception handling (e.g., try/catch) must account for Tarantool\Client\Exception\* classes.
• Moderate:
  • Schema Migrations: No Laravel Migrator support; schema changes must be managed via Lua scripts or custom tasks.
  • Transactions: Tarantool’s transactions require explicit Lua calls; no Laravel DB transaction integration.
• Low:
  • Performance: Benchmarks show pure PHP is ~80% of C extensions; acceptable for most use cases.

Key Questions

1. Use Case Alignment:
   • Is Tarantool used for real-time processing (e.g., caching, queues) or persistent storage? This dictates whether to prioritize binary protocol (speed) or SQL (familiarity).
   • Will the app need hybrid reads/writes (e.g., PHP writes via Laravel, Lua reads via Tarantool)?
2. Team Expertise:
   • Does the team have Tarantool/Lua experience? If not, SQL protocol may reduce friction.
   • Is there PECL extension support for decimal/uuid types?
3. Scaling Assumptions:
   • Will the app use multiple Tarantool instances? The client lacks built-in sharding/routing.
   • Are connection pools needed? External solutions (e.g., PcntlProcess) may be required.
4. Observability:
   • How will requests/responses be logged? The LoggingMiddleware must be configured to integrate with Laravel’s logging (e.g., Monolog).
5. Migration Path:
   • Is this a greenfield project or replacing an existing DB? If replacing, how will legacy queries be translated?

Integration Approach

Stack Fit

• Laravel Core:
  • Service Container: Register the client as a singleton/bound instance in AppServiceProvider:

    public function register()
    {
        $this->app->singleton(Tarantool\Client\Client::class, fn() =>
            Client::fromDsn(env('TARANTOOL_DSN'))
                ->withMiddleware(
                    new AuthenticationMiddleware(env('TARANTOOL_USER'), env('TARANTOOL_PASS')),
                    RetryMiddleware::exponential(3)
                )
        );
    }
    

  • Middleware: Create a Laravel middleware to wrap client calls (e.g., for auth/retries):

    public function handle($request, Closure $next)
    {
        $client = app(Tarantool\Client\Client::class);
        // Custom logic (e.g., validate request before passing to Tarantool)
        return $next($request);
    }
    

• Query Layer:
  • Repositories: Abstract Tarantool operations into Laravel repositories (e.g., TarantoolUserRepository) to hide Criteria/Operations complexity.
  • Eloquent Alternative: Use a read model pattern (e.g., sync Tarantool data to PostgreSQL/MySQL for Eloquent queries).
• Async Workflows:
  • Queues: Dispatch Laravel jobs to interact with Tarantool (e.g., TarantoolProcessDataJob). Use RetryMiddleware for resilience.
  • Events: Emit Laravel events (e.g., TarantoolDataSynced) for reactive updates.

Migration Path

1. Phase 1: Proof of Concept (1–2 weeks)
   • Set up a single Tarantool instance with the PHP client.
   • Implement CRUD operations for 1–2 critical spaces using binary protocol.
   • Benchmark against existing DB (e.g., MySQL) for latency/throughput.
2. Phase 2: Integration (2–4 weeks)
   • Service Provider: Register the client in Laravel’s container.
   • Middleware: Add auth/retries/logging middleware.
   • Repositories: Create a thin layer over raw client calls.
   • Testing: Write Pest/PHPUnit tests for client interactions.
3. Phase 3: Scaling (Ongoing)
   • Connection Pooling: Implement external pooling if needed (e.g., for queue workers).
   • Schema Management: Script Tarantool schema changes (Lua) and sync with Laravel migrations.
   • Monitoring: Integrate Tarantool metrics (e.g., box.stat.user) into Laravel Prometheus/Grafana.

Compatibility

• Laravel Versions: Tested on PHP 7.4+; compatible with Laravel 8/9/10.
• Tarantool Versions: Supports 1.7.1+; ensure server version matches client capabilities (e.g., SQL protocol requires Tarantool 2.1+).
• Dependencies:
  • Required: php: ^7.4|^8.0, ext-json, ext-pcntl (for async).
  • Optional: ext-decimal, ext-uuid (for performance).
  • Conflicts: None; isolated to tarantool/client namespace.

Sequencing

1. Prerequisites:
   • Install Tarantool server and configure spaces/indexes.
   • Set up Laravel project with PHP 8.0+.
2. Client Setup:
   • Composer install: composer require tarantool/client.
   • Configure DSN/credentials in .env.
3. Core Integration:
   • Register service provider.
   • Implement middleware for auth/retries.
4. Application Layer:
   • Build repositories for business logic.
   • Integrate with Laravel routes/controllers or queues.
5. Observability:
   • Add logging middleware.
   • Set up monitoring for connection/latency metrics.

Operational Impact

Maintenance

• Pros:
  • Pure PHP: No native extensions to maintain; updates via Composer.
  • Middleware-Driven: Easy to add/remove features (e.g., logging, rate limiting).
  • Active Development: Regular releases (last: 2024-06-20) and CI/CD (Scrutinizer, GitHub Actions).
• Cons:
  • No Laravel-Specific Docs: Requires reverse-engineering for Laravel integrations.
  • Custom Type Handling: Decimal/UUID types need manual PECL management.
  • Schema Drift Risk: Tarantool schema changes require Lua scripts; no Laravel migration tooling.

Support

• Laravel Ecosystem:
  • Limited: No official Laravel packages; community-driven (e.g., tarantool-php/queue).
  • Stack Overflow: Tags laravel + tarantool yield few results; expect low signal-to-noise.
• Tarantool Support:
  • Community: Telegram channel ([t.me/tarantool_php](https://t.me/tarantool_