Client Laravel Package

Technical Evaluation

Release Delta (v0.11.0) — Why This Assessment Changed

• Breaking: PHP 8.2+ required. PHP 7.4 and PHP 8.0–8.1 are dropped. This invalidates the prior "Laravel 8+/PHP 7.4+" compatibility claim.
• Breaking: native parameter and property types across client and schema APIs, enforced at runtime. Existing loosely-typed call sites (ints passed as strings, nulls into non-nullable params, arrays vs. typed collections) can now throw TypeError where they previously coerced.
• Breaking: rybakit/msgpack >= 0.11.2. Encoding edge cases (large unsigned ints, binary payloads, map/array distinction) may shift; pins must be reconciled.
• Non-breaking: tooling modernization (PHPUnit 10, PHP-CS-Fixer 3, Psalm 5/6, CI on PHP 8.2–8.5). Signals active maintenance and forward compatibility through PHP 8.5, but only affects teams extending the package's own test suite.

Architecture Fit

• Pros:
  • Pure PHP implementation still aligns well with Laravel's ecosystem, avoiding extension dependencies (except optional decimal/uuid PECL extensions).
  • Middleware-based design enables integration with Laravel's middleware stack (logging, retries, auth) via withMiddleware().
  • DSN/URI support mirrors Laravel's service provider/environment variable patterns.
  • SQL and binary protocol support covers Tarantool's use cases, with SQL useful for hybrid PHP/Lua apps.
  • Space/Index abstraction ($client->getSpace()) maps cleanly to Laravel's repository/Query Builder conventions.
  • (v0.11.0) Native parameter and property types make the client's contract self-documenting and static-analysis-friendly — a genuine win for Psalm/PHPStan in CI and for IDE autocomplete in large Laravel codebases.
• Cons:
  • No native Laravel service provider: still requires manual registration in AppServiceProvider.
  • Limited async support: the PHP client is synchronous; Horizon-style async would need custom middleware.
  • No built-in connection pooling: high-load queue workers still need external pooling.
  • No Eloquent/Query Builder bridge, and the strict typing widens the gap — a repository layer is now effectively mandatory rather than merely advisable, since raw client calls no longer tolerate loose scalar passing.

Integration Feasibility

• Laravel Compatibility (revised):
  • PHP 8.2+ floor implies Laravel 10.3+, 11.x, or 12.x. Laravel 8 and 9 are no longer viable; Laravel 10 remains viable only where the runtime is already 8.2+.
  • Laravel 11/12 (which require PHP 8.2) are the natural targets and are the best-supported path.
  • Composer dependency remains trivial; the constraint shift is a platform decision, not a library decision.
• Service Container: unchanged — bind(Tarantool\Client\Client::class, fn() => Client::fromDsn(env('TARANTOOL_DSN'))) still works; the typed API means the binding's return type is now enforced, catching misconfiguration earlier.
• Database Abstraction:
  • Partial: spaces/indexes mirror tables/relationships, but Eloquent won't auto-map without custom repositories.
  • Query Builder Gap: unchanged — raw Criteria/Operations only.

Technical Risk

• Critical (new):
  • Platform upgrade gate: any Laravel app below PHP 8.2 cannot adopt v0.11.0. This is a hard blocker that converts a patch-level dependency bump into a framework upgrade project.
  • Strict-type regression surface: call sites that relied on implicit coercion now fail at runtime. Risk concentrates in dynamic payload construction (space field values, Criteria comparisons, optional filters) and is not caught by static analysis on untyped legacy code.
  • msgpack transitive upgrade: encoding behavior for unsigned 64-bit ints and binary blobs must be re-verified against Tarantool's storage format before rollout.
• Critical (carried over):
  • Connection resilience: middleware order (RetryMiddleware vs. AuthenticationMiddleware) must be explicitly managed to avoid auth leaks on retries.
  • Type handling: Decimal/UUID require PECL extensions for full performance; pure-PHP fallback is slower.
  • Error handling: Laravel exception handling must account for Tarantool\Client\Exception\* — and now \TypeError from the client's own signatures, which is a different catch class than teams may have registered.
• Moderate:
  • Schema migrations: no Laravel Migrator support; Lua scripts or custom tasks.
  • Transactions: explicit Lua calls; no Laravel DB transaction integration.
• Low:
  • Performance: pure PHP remains ~80% of C extensions; the added type declarations have negligible runtime cost (and may help opcache/JIT).

Key Questions

1. Platform currency (new, blocking): Is the target Laravel app already on PHP 8.2+? If not, is a PHP/Laravel upgrade funded, or must we stay pinned to tarantool/client 0.10.x (now unsupported)?
2. Upgrade blast radius (new): How many call sites construct space field values dynamically? Do we have a test suite that exercises them with realistic payload shapes, sufficient to surface TypeError regressions?
3. Use case alignment: Is Tarantool used for real-time processing (caching, queues) or persistent storage? This dictates binary protocol (speed) vs. SQL (familiarity).
4. Team expertise: Does the team have Tarantool/Lua experience? Is PECL support available for decimal/uuid?
5. Scaling assumptions: Multiple Tarantool instances? The client still lacks built-in sharding/routing; connection pools need external solutions.
6. Observability: LoggingMiddleware must be wired into Monolog; typed APIs change what serializes cleanly into log context.
7. Migration path: Greenfield or DB replacement? If replacing, how will legacy queries be translated?
8. Version pinning policy (new): Do we pin tarantool/client exactly, or float within ^0.11? Given two consecutive minors with breaking changes, exact pinning plus a scheduled review is the safer posture.

Integration Approach

Stack Fit

• Laravel Core: register as a singleton 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)
              )
      );
  }
  

  • The typed signatures mean the container binding now fails fast on a malformed DSN or missing credential, which is a net operational improvement.
• Middleware: a Laravel middleware wrapping client calls still works; add \TypeError to the handled exception set alongside Tarantool\Client\Exception\* so strict-type failures surface as actionable API errors rather than 500s.
• Query Layer:
  • Repositories are now load-bearing: use TarantoolUserRepository to hide Criteria/Operations and to own scalar normalization (explicit casts, null handling) at a single boundary rather than scattered across controllers.
  • Eloquent alternative: read-model pattern (sync Tarantool into PostgreSQL/MySQL for Eloquent queries) remains the pragmatic path.
• Async Workflows: dispatch Laravel jobs (TarantoolProcessDataJob) with RetryMiddleware; note that a TypeError is not retryable and should be classified as a permanent failure to avoid poisoning the queue.

Migration Path (revised — platform upgrade comes first)

1. Phase 0: Platform Prerequisite (new, 1–3 weeks)
   • Upgrade the Laravel app to PHP 8.2+ and Laravel 10.3+/11/12 with tarantool/client still pinned at 0.10.x.
   • Confirm rybakit/msgpack and other shared dependencies resolve on the new runtime.
   • Rationale: decouples the runtime upgrade from the client upgrade so failures are attributable.
2. Phase 1: Proof of Concept (1–2 weeks)
   • Single Tarantool instance, CRUD for 1–2 critical spaces via binary protocol.
   • Benchmark against the incumbent store; validate 64-bit int and binary field round-tripping under msgpack 0.11.2.
3. Phase 2: Client Upgrade + Integration (2–4 weeks)
   • Bump to ^0.11.0; enable Psalm/PHPStan at a level that catches argument-type mismatches in new code.
   • Register the service provider, auth/retry/logging middleware, repository layer.
   • Run the existing test suite with strict types as the primary regression detector; backfill tests for dynamically constructed payloads.
4. Phase 3: Scaling (ongoing)
   • External connection pooling for queue workers; scripted Lua schema changes synced with Laravel migrations; Tarantool metrics (box.stat.user) into Prometheus/Grafana.

Compatibility (revised)

• PHP: 8.2, 8.3, 8.4, 8.5 (CI-verified). PHP 7.4 and 8.0–8.1 are unsupported as of v0.11.0.
• Laravel: 10.3+, 11.x, 12.x in practice. Laravel 8/9 are excluded by the PHP floor.
• Tarantool: 1.7.1+ as before; SQL protocol still requires Tarantool 2.1+. CI now exercises newer Tarantool releases, modestly reducing server-version risk.
• Dependencies:
  • Required: php: ^8.2, ext-json, ext-pcntl (async), rybakit/msgpack: ^0.11.2.
  • Optional: ext-decimal, ext-uuid.
  • Conflicts: none introduced; namespace isolation unchanged.
• Upgrade risk classification: breaking for any app on PHP <8.2, and potentially breaking at runtime for apps with loosely-typed client call sites even on supported PHP.

Sequencing (revised)

1. Inventory current PHP/Laravel version and all tarantool/client call sites.
2. Upgrade runtime + framework with the client held at 0.10.x.
3. Pin rybakit/msgpack and verify resolution.
4. Upgrade to client v0.11.0; run the test suite to harvest TypeError failures as a work list.
5. Normalize scalars inside the repository layer; add static analysis to CI.
6. Adopt repository/service-provider/middleware wiring.
7. Add logging middleware and connection/latency monitoring.

Operational Impact

Maintenance

• Pros:
  • Pure PHP: no native extensions to maintain; updates via Composer.
  • Middleware-driven: features added/removed without forking.
  • Active development, modernized toolchain: PHPUnit 10, PHP-CS-Fixer 3, Psalm 5/6, CI on PHP 8.2–8.5 with combined coverage. Demonstrates the maintainers are tracking the PHP release train — a meaningful sustainability signal.
  • New contributor in v0.11.0 indicates growing (not shrinking) contributor base.
• Cons:
  • Breaking-change cadence: two consecutive minor-line breaks puts the burden on the consuming team to pin exactly and schedule upgrade windows.
  • No Laravel-specific docs: still requires reverse-engineering for Laravel integration.
  • Custom type handling: Decimal/UUID need manual PECL management.
  • Schema drift risk: Tarantool schema changes require Lua scripts; no Laravel migration tooling.
  • Support-window cliff: staying on 0.10.x means no security or compatibility fixes going forward — an unowned-risk decision if the PHP upgrade is deferred.

Support

• Laravel ecosystem: limited; community-driven (e.g., tarantool-php/queue). Stack Overflow signal for laravel + tarantool remains thin.
• Tarantool support: community channels (Telegram t.me/tarantool_php, GitHub issues). Maintainers are responsive to PRs, and the tooling modernization suggests they will keep CI green against future PHP releases.
• Practical implication: the internal team is the de facto support tier. Budget an internal owner for the repository layer and the DSN/credential configuration, and document the middleware order contract so it survives staff turnover.

Scaling

• Unchanged: no built-in sharding, routing, or pooling. Horizontal scale requires an external router or application-side sharding, and queue-worker throughput requires external connection pooling.
• New consideration: strict typing makes the client slightly more predictable under concurrency (fewer silent coercions), but a TypeError inside a worker is a hard failure — ensure queue failure classification distinguishes permanent type errors from transient connection errors so retries don't amplify load.

Failure Modes

• TypeError from client APIs (new): most likely on dynamic payloads, optional filters, and numeric fields passed as strings from HTTP request input. Mitigation: cast at the repository boundary; add TypeError to the middleware's handled exceptions.
• msgpack encoding divergence (new): 64-bit unsigned ints and binary payloads may encode differently post-upgrade. Mitigation: round-trip fixture tests against a real Tarantool instance in CI.
• Auth leak on retry: unchanged — order AuthenticationMiddleware before RetryMiddleware and test the failure path explicitly.
• Connection exhaustion: unchanged — no pooling; watch box.stat connection counts under worker fan-out.
• Schema drift: unchanged — Lua-managed schema can desync from application expectations; add a startup schema assertion.
• Silent version drift: floating ^0.11 risks pulling a future breaking minor. Mitigation: exact pins plus a quarterly dependency review.

Ramp-up

• Unchanged baseline: engineers need Tarantool concepts (spaces, indexes, tuples, Criteria) plus Lua for schema work. Estimate 1–2 weeks to first productive contribution for a mid-level Laravel engineer.
• Slightly reduced for pure PHP developers: native types and improved IDE/static-analysis support lower the discovery cost of the client API surface — new team members can lean on autocomplete and Psalm rather than docs.
• Added for the upgrade itself: someone must own the PHP 8.2+/Laravel upgrade and the TypeError remediation sweep. Treat this as a distinct workstream with a named owner, not as incidental maintenance, and communicate the pinning policy (0.10.x intentionally frozen vs. 0.11.x adopted) so future engineers understand the deliberate choice.