Use the PHP SDK

Applies to: current development source bundles. Obtain a matched client/server release through early-access support; registry publication is not available yet. Paths below are relative to the supplied source checkout.

Synchronous PHP 8.2+ client using FFI and libsmkv. Requires 64-bit PHP, ext-ffi, and ext-json. Initial source package; not published to Packagist.

Install

Build/install the C transport. Set SMKV_LIBRARY to the absolute path of its shared library. Install OpenSSL/json-c runtime dependencies. Load src/Client.php directly or use this directory as a Composer path repository with package simplemagic/smkv (dev-main). Composer metadata includes a classmap.

FFI must be enabled for the process. For CLI examples use:

SMKV_LIBRARY=/absolute/path/libsmkv.so php -d ffi.enable=1 your-app.php

On macOS the suffix is .dylib. PHP-FPM/web deployments need administrator-enabled FFI; shared hosts may disallow it. Do not enable FFI globally merely for a demo. Native binaries must match the process's OS and architecture; Windows is unqualified.

Usage

require 'php-smkv/src/Client.php';
use SimpleMagic\Smkv\{Client, Bytes, WriteOptions};

$client = new Client('127.0.0.1:7379');
try {
    $client->put('greeting', "hello\0", new WriteOptions(ttlMs: 60000, sync: true));
    echo $client->get('greeting');
    $users = $client->table('users');
    $users->put('42', ['name'=>'Ada', 'visits'=>1, 'payload'=>new Bytes("\0\xff")]);
    $users->update('42', ['visits'=>2]);
    print_r($users->get('42', ['name', 'visits']));
} finally { $client->close(); }

Raw keys/values are binary PHP strings. Column strings are UTF-8 text; wrap binary columns in Bytes (reads also return Bytes). Other values are int64, float64, and bool. Numeric-looking column names follow PHP array-key conversion rules.

WriteOptions supports TTL, sync, replicaAck, durableReplicaAck. Omitted TTL means no expiry on put, preserved expiry on update; zero expires immediately. Delete rejects TTL. Updates atomically set/remove columns; get supports projection.

Cluster, security, and errors

Client::cluster(['host:7381']) accepts management seeds. The first request discovers owners. get($key, replica: true) explicitly permits stale reads. Constructor arrays accept the native config schema: timeout_ms, record limits, independent security and management_security. A ca PEM path enables verified TLS; name/token enable auth. Both are optional. Certificates and endpoint hostnames/IPs are always verified; no TLS downgrade.

SmkvException::$status identifies server/client errors; outcomeUnknown means a mutation may have completed. Do not blindly retry. Only explicit WrongOwner is retried automatically. Defaults are five-second total timeout, 1 KiB key limit, and 1 MiB value limit. DNS may outlive the timeout; numeric endpoints avoid this.

One client retains one connection; create clients after worker fork and close them explicitly. Native handles cannot be cloned or serialized. Calls block the PHP thread; fibers do not make them asynchronous. No scans, batching, async API, or load qualification yet. See tests.

Run php -d ffi.enable=1 php-smkv/examples/basic.php 127.0.0.1:7379 after setting SMKV_LIBRARY, against a disposable node. This writes expiring example records.