darkterminal / turso-client-http
The Turso HTTP Client for PHP (wraps Turso Hrana-over-HTTP)
Requires
- php: ^8.3
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- monolog/monolog: ^3.8
- vlucas/phpdotenv: ^5.8
Requires (Dev)
- pestphp/pest: ^3.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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.
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:
- Installation
- Configuration
- Basic Usage
- Laravel Integration
- Query Builder
- Verification & Proof Harness
- Known Limitations
- Troubleshooting
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 onTURSO_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 catchableLibSQLErrorexceptions 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
License
Licensed under the MIT License. See LICENSE for details.