Search by

darkterminal / turso-client-http

darkterminal

The Turso HTTP Client for PHP (wraps Turso Hrana-over-HTTP)

Package info

github.com/darkterminal/turso-client-http

pkg:composer/darkterminal/turso-client-http

Fund package maintenance!

darkterminal

Other

Statistics

Installs: 521

Dependents: 1

Suggesters: 0

Stars: 49

Open Issues: 0

v3.0.1 2026-11-11 17:19 UTC

README

Important

This package is a pure-PHP HTTP client (Hrana over HTTP) for libSQL — it is not the libSQL PHP extension, and it does not link against any native library. If you want the native extension, use the turso-driver for your framework instead; this one runs anywhere ext-curl works, including shared hosting and CI runners.

Shows a black logo in light color mode and a white one in dark color mode.

Turso + HTTP Client

MIT License Discord Contributors Total downloads Version Tag Testing

SQLite for Production. Powered by libSQL and the libSQL Database API.

libSQL is an open-contribution fork of SQLite. This package provides a pure-PHP HTTP client (Hrana over HTTP) for libSQL — Turso Cloud and self-hosted libsql-server — with a Laravel-compatible service provider and facade. The docker/laravel-proof/ harness and the test suite exercise transactions, the full Hrana pipeline, and the query builder end to end.

Full user manual & tutorial now lives on the Wiki.

Requirements

Component Requirement
PHP 8.3, 8.4 or 8.5 (CI-verified on all three)
ext-curl required
ext-json required
ext-mbstring required
Turso Cloud or self-hosted libsql-server (sqld) HTTP endpoint + token
Native libSQL extension not required

Installation

composer require darkterminal/turso-client-http

Configuration

Plain PHP — pass a DSN (token parameter kept for API symmetry with the native client):

use Darkterminal\TursoHttp\LibSQL;

$db = new LibSQL("dbname=libsql://<db>-<org>.turso.io&authToken=<token>");

Fallbacks when no DSN argument is provided (used by the global helpers): DB_URL/TURSO_URL (default http://127.0.0.1:8081, local sqld) and DB_TOKEN/TURSO_TOKEN.

Laravel — after composer require, the auto-discovered TursoServiceProvider shares one client; publish the config if you want to change it:

php artisan vendor:publish --provider="Darkterminal\TursoHttp\Laravel\TursoServiceProvider" --tag=turso-http-config

.env:

DB_URL=libsql://your-url.turso.io
DB_TOKEN=your-token
use Darkterminal\TursoHttp\Laravel\Turso;

$rows = Turso::query('SELECT * FROM users')->fetchArray(
    \Darkterminal\TursoHttp\LibSQL::LIBSQL_ASSOC
);

Everything else (timezone handling for DATETIME columns, DB_STRICT_QUERY, DB_TIMEZONE) is on the Wiki · Configuration.

Usage

use Darkterminal\TursoHttp\LibSQL;

$db = new LibSQL("dbname=$DB_URL&authToken=$DB_TOKEN");

$db->execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
$db->execute('INSERT INTO users (name) VALUES (?)', ['Ada']);

$rows = $db->query('SELECT * FROM users')->fetchArray(LibSQL::LIBSQL_ASSOC);

Transactions: $tx = $db->transaction('deferred'); → $tx->execute(...) → $tx->commit(); / $tx->rollback();.

Full tour (fetch modes, transactions, query builder, *Return statements): Wiki · Basic Usage.

Documentation

The full user manual & tutorial lives on the Wiki:

Verification

  • Pest suite: 60 tests, 103 assertions, all green — repeatedly re-seeded from a pristine database.
  • Live Turso Cloud tests (tests/Feature/TursoCloudConnectionTest.php): 2 tests / 11 assertions covering the typed round trip (Hrana v3 int / float / text / NULL) and transactions — against a real cloud database, env-gated on TURSO_CLOUD_DB_URL / TURSO_CLOUD_DB_TOKEN (skipped otherwise). Self-cleaning tables, safe to run repeatedly.
  • CI: GitHub Actions matrix on PHP 8.3 / 8.4 / 8.5 against a seeded libsql-server service container — all green.
  • docker/laravel-proof/: fresh Laravel 12 app, package installed via path repository — 5/5 assertions green on all three PHP versions (service provider discovery, facade resolution, connectivity, facade round trip, transaction commit).
  • HTTP errors (401 / 403 / 404) surface as catchable LibSQLError exceptions with the server's message — no silent failures.

Links: docker/laravel-proof · CI workflow · Releases

Testing

composer install
./vendor/bin/pest

The suite re-seeds a local libsql-server on 127.0.0.1:8081 itself (or whatever DB_URL points at). Set TURSO_HTTP_SKIP_SEED=1 to skip seeding.

The Turso Cloud tests run too when the live endpoint is configured (they skip otherwise):

TURSO_CLOUD_DB_URL=libsql://<db>-<org>.turso.io
TURSO_CLOUD_DB_TOKEN=<token>

See Wiki · Verification.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please do not open public issues for vulnerabilities. Report them privately via GitHub Security Advisories.

Contributors

Contributors

License

Licensed under the MIT License. See LICENSE for details.