KoutenDB PHP Driver

PHP driver for KoutenDB, with native TCP server access and an optional FFI backend for embedded use.

It is intended as the foundation for plain PHP integrations and later Laravel/Symfony adapters. It does not try to pretend KoutenDB is an SQL database or an Eloquent model backend.

Status

• Package: Packagist koutendb/koutendb
• Current source version: 0.2.0
• Transports: native TCP for server access; C ABI / FFI for embedded and existing remote APIs.
• PHP: 8.2+
• TCP requires no ext-ffi, ext-sockets, or libkoutendb.so; 64-bit PHP is required.
• FFI mode requires ext-ffi and libkoutendb.so.
• Validated with KoutenDB v0.14.3: wire v1 for native TCP, C ABI v2 for FFI.

Install

Install from Packagist:

composer require koutendb/koutendb:^0.2

For local development from a checkout, you can still use a Composer path repository.

Native TCP is available starting with 0.2.0; 0.1.x remains FFI-only. See Native TCP for server setup, authentication, TLS, Laravel configuration, failure semantics, and tests.

$db = \KoutenDB\KoutenDB::connectTcp(
    peers: ['127.0.0.1:17301'],
    options: ['galaxy' => 'publarish'],
);
$id = $db->putJson('publarish/articles', ['title' => 'Example']);
$article = $db->getJson($id);
$db->close();

FFI Setup

Build the KoutenDB shared library first:

git clone https://github.com/puffball1567/koutendb.git
cd koutendb
nimble install -y --depsOnly
bash scripts/build_capi.sh

At runtime, make sure PHP can find both the driver and libkoutendb.so:

LD_LIBRARY_PATH=/path/to/koutendb/lib php app.php

Only the FFI APIs require ext-ffi. They fail explicitly at runtime when it is missing. Native TCP installation and usage do not load the shared library. For FFI verification without changing local PHP, use the Docker smoke test below.

Example

<?php
use KoutenDB\KoutenDB;
use KoutenDB\KoutenId;

$db = KoutenDB::open(8, "/path/to/koutendb/lib/libkoutendb.so");
$db->setGalaxyDescription("Product and support knowledge");
$db->setRingDescription("docs", "Documentation ring");

$id = $db->putJson("docs/php", [
    "title" => "PHP context",
    "kind" => "example",
]);

$roundtrip = KoutenId::parse((string) $id);
$doc = $db->getJson($roundtrip);
$view = $db->queryJson($id, "{ title }");

$vecId = $db->putJsonVec("docs/php", [
    "title" => "Vector-backed PHP document",
    "kind" => "example",
], [1.0, 0.0]);
$encoded = $db->getEncoded($id);
$page = $db->readRing("docs/php", [
    "filter" => ["kind" => "example"],
    "selection" => "{ title }",
    "limit" => 10,
]);
$value = $db->get($vecId);
$atlas = $db->atlas([1.0, 0.0], 8);
$db->close();

Test

cd /path/to/koutendb
bash scripts/build_capi.sh

From this driver repository:

KOUTENDB_CORE_DIR=/path/to/koutendb ./docker-test.sh

docker-test.sh builds a small php:8.3-cli based image with FFI enabled and mounts the KoutenDB core checkout into the container.

Current API

Native TCP exposes connectTcp, connectTcpAuth, and connectTcpTls, returning TcpClient with put, putJson, putCodec, get, getJson, getEncoded, query, queryJson, health, and close. See the native transport guide for its options and exceptions.

The following table describes the existing FFI backend:

Area	API
Open / connect	KoutenDB::open, openDir, openDirWith, connect, connectAuth
TLS connect	connectAuthTls, connectAuthTlsInsecure
Writes / mutations	put and codec/vector helpers, update, updateCodec, updateJson, remove
Reads	get, getEncoded, getJson, exists, batchGet, readRing
Payload codecs	EncodedPayload, raw, json, nif, bif
Projection	query, queryJson
Retrieval	retrieve, RetrieveResult, KoutenHit
Atlas	atlas
Metadata	configureRing, setGalaxyDescription, setRingDescription
Orbit helpers	locate, nextVisit, nextJoin
IDs	KoutenId, KoutenId::parse, KoutenId::__toString
Errors	KoutenDBException
Metrics	metrics, checkpointMetrics
Segment maintenance	segmentStatus, planSegmentMaintenance, runSegmentMaintenance, segmentMaintenanceStatus, recoverSegmentMaintenance
Generation checkpoints	createCheckpoint, checkpointStatus, listCheckpoints, cleanupCheckpoints, restoreCheckpoint

TLS

TLS requires an KoutenDB core built with -d:ssl. The shared library from scripts/build_capi.sh is built with it; a library built without it fails a TLS connect with TLS support requires building KoutenDB with -d:ssl.

To reach a server whose certificate is signed by a private CA — or is self-signed — point at the certificate PEM. Verification stays on:

$db = KoutenDB::connectAuthTls(
    '127.0.0.1:17651',
    'alice',
    'secret',
    tlsCaFile: '/path/to/server.crt',
);

connectAuthTlsInsecure() (or connectAuthTls(..., tlsInsecureSkipVerify: true)) disables certificate verification. The connection is then encrypted but unauthenticated and trivially impersonable, so it is for local smoke tests only — never a production server. Prefer a tlsCaFile for self-signed certificates.

Laravel Direction

Laravel support should live in a separate thin adapter, likely koutendb-laravel. The PHP driver should stay framework-neutral. The Laravel package can provide a service provider, facade, configuration, and a more Laravel-shaped API for persistent semantic state, context, and retrieval working sets. It should not try to emulate Eloquent.