folk/sdk

Universal PHP SDK for Folk application server

v0.4.1 2026-07-09 15:44 UTC

Requires

• php: >=8.2
• ext-json: *

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^11.0
• psr/http-factory: ^1.0

Suggests

• ext-folk: Folk PHP extension — install via: pie install folk-project/ext-folk
• psr/http-factory: Required for PsrHttpHandler (PSR-7 framework integration)

MIT

• Folk Contributors

• php
• sdk
• worker
• folk

Published on Packagist.org on 2026-07-09 15:45 UTC

README

PHP SDK for Folk -- worker dispatch loop, HTTP handler, and request/response types.

Version: 0.2.0

Installation

composer require folk/sdk

Requires the folk.so PHP extension (built by folk-ext).

WorkerLoop

WorkerLoop is the PHP-side dispatch loop. It auto-detects the dispatch mode:

Mode	How it works	Serialization
Direct (preferred)	Rust calls PHP handler via call_user_function with zval arrays	None -- zero-copy
Extension	folk.so extension bridges Rust and PHP	Minimal
Pipe (legacy)	stdin/stdout msgpack-RPC	Full encode/decode

Direct dispatch (zero-copy)

When running inside folk.so, Rust passes request data as native PHP arrays (zvals) directly to the handler function. No JSON or msgpack encode/decode is needed. This is the fastest path.

Quick start

<?php
require __DIR__ . '/vendor/autoload.php';

use Folk\Sdk\Worker\WorkerLoop;
use Folk\Sdk\Http\HttpModeHandler;
use Folk\Sdk\Http\HttpRequest;
use Folk\Sdk\Http\HttpResponse;

class MyHandler implements HttpModeHandler
{
    public function handle(HttpRequest $request): HttpResponse
    {
        return new HttpResponse(
            status: 200,
            headers: ['Content-Type' => 'application/json'],
            body: json_encode(['uri' => $request->uri]),
        );
    }
}

$loop = new WorkerLoop();
$loop->registerHttpHandler(new MyHandler());
$loop->run();

Key classes

• WorkerLoop -- main dispatch loop, auto-detects mode, calls registered handlers
• HttpRequest -- fields: method, uri, headers, body
• HttpResponse -- fields: status, headers, body
• HttpModeHandler -- interface with handle(HttpRequest): HttpResponse

Requirements

• PHP 8.2+
• folk.so extension (ZTS build)

License

MIT