Skip to content
Imam Ali Mustofa edited this page Nov 11, 2026 · 3 revisions

Turso HTTP Client for PHP — User Manual & Tutorial

This is the user documentation for darkterminal/turso-client-http, a pure-PHP client (Hrana over HTTP) for libSQL — an SQLite-compatible, open-contribution fork of SQLite — against Turso Cloud or a self-hosted libsql-server (sqld). No native PHP extension is required.

Every feature documented here is verified against this repository; nothing on these pages is aspirational. Where something is not verified, it is marked Not verified explicitly.

Compatibility (verified by CI)

Component Requirement
PHP 8.3 / 8.4 / 8.5 (GitHub Actions matrix, all green)
ext-curl, ext-json, ext-mbstring required
Turso Cloud libsql:// endpoint or self-hosted sqld HTTP endpoint + token
Native libSQL PHP extension not required
Laravel 12 (auto-discovered provider + facade, publishable config)

Verified by: Pest suite (60 tests / 103 assertions) on every push to main, a live Turso Cloud run (2 tests / 11 assertions — set TURSO_CLOUD_DB_URL / TURSO_CLOUD_DB_TOKEN), and docker/laravel-proof (5/5 assertions, Laravel 12, PHP 8.3/8.4/8.5).

Pages

  1. Installation
  2. Configuration
  3. Basic Usage
  4. Laravel Integration
  5. Query Builder
  6. Verification & Proof Harnesses
  7. Known Limitations
  8. Troubleshooting

What this package is

darkterminal/turso-client-http is a pure-PHP client that speaks the Hrana pipeline protocol over HTTP — the same protocol family as Turso Cloud's Database API. It mirrors the API of the native libSQL PHP extension (LibSQL::query / execute, LibSQLResult::fetchArray, prepare()), so code written against the native client is mostly a drop-in.

It is not:

  • the native .so driver (link turso-client-php for that),
  • an ORM / query-builder replacement (it has a convenience Query Builder — see Query Builder — but it is not Eloquent/Doctrine),
  • a client for offline / journaled-write modes (those need native sync).

Current status

  • v3.0.1 is the latest release (minimum PHP 8.3; Hrana v2 and v3 responses handled uniformly — v3 typed cells are decoded once at result-construction time; HTTP errors surface as catchable LibSQLError exceptions).
  • CI is green on PHP 8.3 / 8.4 / 8.5 on every push to main.
  • Live Turso Cloud verification runs when cloud credentials are set (TURSO_CLOUD_DB_URL / TURSO_CLOUD_DB_TOKEN — env-gated, skipped otherwise): connectivity, typed-value round trip, transactions.
  • The Laravel proof harness is green on all three PHP versions.
  • Official releases and notes: see the Releases page.

Clone this wiki locally