Search by

darkterminal / turso-api-client-php

darkterminal

Turso Platform PHP SDK — typed client for the Turso Platform API

Package info

github.com/darkterminal/turso-api-client-php

pkg:composer/darkterminal/turso-api-client-php

Fund package maintenance!

darkterminal

Other

Statistics

Installs: 33

Dependents: 1

Suggesters: 0

Stars: 5

Open Issues: 0

2.1.0 2026-11-12 12:19 UTC

This package is auto-updated.

Last update: 2026-11-12 12:58:09 UTC


README

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

Turso Platform SDK for PHP

MIT License Discord Contributors Total downloads Version Tag

Turso Platform PHP SDK

PHP SDK for the Turso Platform API. Typed, resource-oriented client built against the pinned OpenAPI snapshot — the same platform that powers libSQL, Turso Cloud, and self-hosted sqld over HTTP. Works in plain PHP as well as any framework; there is no framework dependency.

Coverage is pinned against the OpenAPI snapshot pinned in this repository (see openapi/coverage-manifest.yaml). All 53/53 operations are implemented and covered by automated tests.

Requirements

Component Version
PHP 8.3+
ext-curl required
ext-json required
PSR-18 HTTP client optional — SDK ships a reasonable default (CurlTransport)

Installation

composer require darkterminal/turso-api-client-php

Quick start

use Darkterminal\TursoPlatformAPI\Client\Client;

$client = Client::builder()
    ->withToken(getenv('TURSO_API_TOKEN'))
    ->withOrganization('acme')            // slug, for organization-scoped resources
    ->build();

$databases = $client->databases()->list();
$me        = $client->user()->get();

Configuration

Method Purpose
withToken(string) Bearer token sent as Authorization: Bearer …
withOrganization(string) Organization slug (e.g. 'acme') — needed for databases/groups/members/etc.
withOrganizationId(string) Organization ID (UUID) — needed for the v3 recovery operations (listDeletedDatabases, restoreDatabase, listDeletedGroups, restoreGroup)
withBaseUrl(string) Custom base URL (default https://api.turso.tech)
withTimeout(int) cURL timeout in seconds (default 20)
withTransport(Psr\Http\Client\ClientInterface) Inject any PSR-18 client (e.g. Guzzle)

Resources

Every resource maps to the pinned OpenAPI operationId.

Resource Operations
user() user()->get() — GET /v1/user
auth() auth()->validate() — GET /v1/auth/validate
locations() locations()->list() — GET /v1/locations
organizations() list, get, update, listPlans, listInvoices, getSubscription, getUsage
members() list, add (email or username), get, updateRole, remove
invites() list, create (exactly one of email|username), delete (v2)
databases() list, create, get, delete, get/update configuration, list/get instances, createToken, invalidateTokens, usage, stats
groups() list, create, get, delete, get/update configuration, transfer, unarchive, add/remove location, update, createToken, invalidateTokens
apiTokens() list, create, revoke (personal)
organizationApiTokens() list, revoke (organization-scoped)
recovery() listDeletedDatabases, restoreDatabase, listDeletedGroups, restoreGroup (v3, requires withOrganizationId())
auditLogs() list (page / page_size)

See docs/api-map.md for the full operation inventory and contract coverage map.

Integrations

Two standalone integrations, not wired to the Platform API by default (ADR-005 / ADR-009):

Integration Purpose
Integrations\DatabaseUploader Upload a SQLite dump to a database created with seed.type='database_upload'. Pre-flight validates WAL mode, page_size=4096, auto_vacuum=0, UTF-8 encoding. Requires a database token (never the Platform token).
Integrations\RegionResolver Read-only GET https://region.turso.io/ — returns the AWS region serving the client and the airport code. No auth.
use Darkterminal\TursoPlatformAPI\Integrations\DatabaseUploader;
use Darkterminal\TursoPlatformAPI\Integrations\RegionResolver;

$uploader = new DatabaseUploader('dmpload-….turso.io', $databaseToken);
$uploader->uploadDump('/path/to/dump.db');

$region = (new RegionResolver())->closest();   // ['server' => 'aws-us-west-2', 'client' => 'lax']

Error handling

HTTP status Exception
Network/transport failure TransportException
401 / 403 AuthenticationException
404 NotFoundException
429 RateLimitException (with ->retryAfter when the server supplies it)
5xx ServerException
Other non-2xx HttpException
Validation (pre-flight) ValidationException
Config (missing token/organizationId/…) ConfigurationException

Credentials are never reflected in exception messages, bodies, or logs; network-level failures throw a transport-only TransportException.

Testing

composer install
./vendor/bin/pest

78 tests / 166 assertions cover all resources (via an in-memory PSR-18 double).

What is not supported yet

  • Laravel adapter — planned as a follow-up package; this package is Laravel-free.
  • Offline/journaled-write modes — out of scope for an HTTP Platform API client.
  • Region resolver push notifications — resolver is stateless; there is no webhook/edge-push API.

Versioning

  • Semantic Versioning. Migration guide lives in CHANGELOG.md.
  • Public API of v2.x is the typed client built via Client::builder().
  • v1.x API was removed entirely in v2.0.0 — see the migration notes.

Security

  • Bearer token is attached only after validating the configured base URL and request path; the default CurlTransport does not follow redirects, so it cannot leak credentials across host boundaries.
  • No endpoint is called with the wrong transport: organization-scoped resources throw ConfigurationException when no organization is configured; v3 recovery operations throw when no organizationId is configured.
  • Secrets never appear in logs, exceptions, or error bodies (see tests: “never leaks the token in exception messages”).

Documentation

Contributors

See the contributor graph on GitHub.

Contributing & Security

Please see CONTRIBUTING.md. Report vulnerabilities privately via GitHub Security Advisories.

License

MIT — see LICENSE.