darkterminal / turso-api-client-php
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
Requires
- php: ^8.3
- ext-curl: *
- ext-json: *
- nyholm/psr7: ^1.8
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0 || ^2.0
Requires (Dev)
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.3
- phpstan/phpstan-phpunit: ^2.1
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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
CurlTransportdoes not follow redirects, so it cannot leak credentials across host boundaries. - No endpoint is called with the wrong transport: organization-scoped resources throw
ConfigurationExceptionwhen no organization is configured; v3 recovery operations throw when noorganizationIdis 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.
