King PHP Extension

Systems-grade networking and infrastructure primitives for PHP

King turns PHP into a systems platform for transport-heavy, realtime,
infrastructure-aware software. Instead of pushing critical networking,
orchestration, discovery, storage, and control-plane work into sidecars,
gateways, or glue layers, King keeps that work inside one native runtime that
is directly available to PHP.

That changes what PHP can be used for. With King, PHP is no longer limited to
short request handlers and thin application wrappers. It can own live sessions,
streams, protocol state, routing decisions, telemetry, persistence, scaling
signals, and cluster-facing workflows in one coherent runtime model.

The current line is beta. The repo-local baseline is green, the multi-backend
object-store and control-plane surfaces are real, and the remaining closure
work is now about narrower hardening, distributed-operating proof, and
multi-node fleet behavior rather than placeholder subsystem stories.

If you do not have a Hetzner account yet, it is time to fix that. Use the
Hetzner Cloud referral link and you
help support the live infrastructure tests that keep King honest.

How To Install And Run It

For a repository-local build:

git clone --recurse-submodules https://github.com/Intelligent-Intern/king.git
cd king
./infra/scripts/build-profile.sh release
php -d extension="$(pwd)/extension/modules/king.so" -r 'echo king_version(), PHP_EOL;'

That gives you the extension plus the matching QUIC runtime artifacts for the
local release profile. If you only want the extension build, use
./infra/scripts/build-extension.sh.

If you want the beginner path from zero to a local WebSocket roundtrip, start
with documentation/getting-started.md.

King also ships a
PIE install path. PIE is the successor to PECL.
Tagged releases that publish the matching PIE source asset can be installed
with pie install intelligent-intern/king-ext. Packaging details and local
verification steps live in
documentation/pie-install.md.

Small But Oho

One good first King application is this:

• clients subscribe over WebSocket to /watch?bucket=inbox
• an uploader sends POST /upload?bucket=inbox&object=demo.txt
• the application stores the file in the object store
• every subscriber for that bucket immediately gets a realtime notification

The event looks like this:

{
  "event": "object.available",
  "bucket": "inbox",
  "object_id": "demo.txt",
  "content_type": "text/plain",
  "size": 1234
}

The important point is that the durable write and the realtime fanout happen in
the same native runtime. The object lands in King storage, and the same PHP
process can immediately push the event over live WebSocket handles without
handing the work to a sidecar or an external glue service.

The bucket-subscription registry in this example is intentionally
application-managed and process-local. King already gives you the real object
store and WebSocket runtime needed for it, but it does not currently claim a built-in distributed bucket-watch API. For the same reason, this README example
stays single-node on purpose instead of pretending the current router or
load-balancer control-plane layer is already a verified WebSocket forwarding
dataplane.

The core shape looks like this. It keeps WebSocket handling procedural while
using the King\ObjectStore OO facade for durable writes:

<?php

use King\ObjectStore;

$subscribers = [];

function king_demo_bucket_from_request(array $request): string
{
    $query = [];
    parse_str((string) parse_url($request['uri'] ?? '/', PHP_URL_QUERY), $query);

    return (string) ($query['bucket'] ?? 'inbox');
}

function king_demo_object_from_request(array $request): string
{
    $query = [];
    parse_str((string) parse_url($request['uri'] ?? '/', PHP_URL_QUERY), $query);

    return (string) ($query['object'] ?? 'upload.bin');
}

function king_demo_publish(array &$subscribers, string $bucket, array $event): void
{
    $payload = json_encode($event, JSON_UNESCAPED_SLASHES);

    foreach ($subscribers[$bucket] ?? [] as $index => $websocket) {
        if (!is_resource($websocket) || !king_websocket_send($websocket, $payload)) {
            unset($subscribers[$bucket][$index]);
        }
    }
}

ObjectStore::init([
    'primary_backend' => 'local_fs',
    'storage_root_path' => __DIR__ . '/storage',
    'max_storage_size_bytes' => 50 * 1024 * 1024,
]);

$watchHandler = static function (array $request) use (&$subscribers): array {
    $bucket = king_demo_bucket_from_request($request);
    $websocket = king_server_upgrade_to_websocket($request['session'], $request['stream_id']);

    if (!is_resource($websocket)) {
        return ['status' => 400, 'body' => 'websocket upgrade failed'];
    }

    $subscribers[$bucket][] = $websocket;
    king_websocket_send($websocket, json_encode([
        'event' => 'subscribed',
        'bucket' => $bucket,
    ], JSON_UNESCAPED_SLASHES));

    return ['status' => 101, 'headers' => [], 'body' => ''];
};

$uploadHandler = static function (array $request) use (&$subscribers): array {
    $bucket = king_demo_bucket_from_request($request);
    $objectId = king_demo_object_from_request($request);
    $storageKey = $bucket . '/' . $objectId;

    $source = fopen('php://temp', 'r+');
    fwrite($source, (string) ($request['body'] ?? ''));
    rewind($source);

    ObjectStore::putFromStream($storageKey, $source, [
        'content_type' => 'text/plain',
    ]);

    king_demo_publish($subscribers, $bucket, [
        'event' => 'object.available',
        'bucket' => $bucket,
        'object_id' => $objectId,
        'content_type' => 'text/plain',
        'size' => strlen((string) ($request['body'] ?? '')),
    ]);

    return [
        'status' => 202,
        'headers' => ['content-type' => 'application/json'],
        'body' => json_encode([
            'stored' => true,
            'key' => $storageKey,
        ], JSON_UNESCAPED_SLASHES),
    ];
};

King brings the following into one extension:

• QUIC, HTTP/1, HTTP/2, HTTP/3, TLS, streaming, cancellation, and upgrade flows
• client and server APIs over explicit session and stream state
• WebSocket and WebTransport-class realtime communication
• Smart DNS / Semantic DNS for service discovery and routing
• router and load-balancer control-plane configuration and policy
• IIBIN for schema-defined native binary encoding and decoding
• MCP for agent and tool protocol integration
• real multi-backend object-store and CDN primitives
• telemetry, metrics, tracing, and admin control surfaces
• autoscaling, orchestration, and cluster-facing infrastructure hooks

King is built for applications that need serious transport, state, and runtime
control: edge services, realtime systems, AI backends, internal control planes,
data-heavy platforms, and distributed application nodes that need native
protocol behavior without leaving PHP.

Runtime Planes

King does not treat async work as one generic promise layer.
It separates the runtime into four clear planes so transport work, realtime
work, remote control work, and fleet behavior do not collapse into one blurry
"evented" abstraction.

1. Realtime Plane

The realtime plane is for long-lived interactive channels.
This is where chat messages, presence updates, room state, small control
messages, and other high-frequency bidirectional traffic belong.
In King, that plane is built around WebSocket and IIBIN.
WebSocket keeps the connection open and bidirectional.
IIBIN gives that connection a compact, schema-defined binary message format.
If an application needs to push many small messages quickly and keep both sides
in sync, this is the right plane.

2. Media And Transport Plane

The media and transport plane is for session ownership, stream ownership,
protocol state, transport reuse, and QUIC-aware behavior.
This is where HTTP/1, HTTP/2, HTTP/3, QUIC, TLS, session tickets, stream
lifecycle, cancellation, timeout, and polling logic live.
The key idea is that a request is not always the same thing as a connection.
King exposes Session, Stream, and protocol-specific transport paths because
serious network software needs explicit control over the transport kernel under
the application logic.

3. Control Plane

The control plane is for remote work that is not just "serve one response now".
This is where MCP and the pipeline orchestrator live.
MCP moves structured requests, uploads, downloads, deadlines, and cancellation
between peers.
The orchestrator manages multi-step work, queue-backed execution, remote-worker
execution, run snapshots, and restart-aware control flow.
If work needs to continue beyond one request, move to another process, or be
tracked as an explicit runtime job, it belongs here.

4. State And Fleet Plane

The state and fleet plane is for durable system behavior across many requests,
nodes, and services.
This is where the object store, CDN hooks, Semantic DNS, telemetry, autoscaling,
and router or load-balancer policy surfaces fit.
The object store holds artifacts and large state across local, distributed, and
real cloud backends.
Semantic DNS decides where traffic should go.
Telemetry measures what the system is doing.
Autoscaling reacts to that telemetry.
This plane is what lets King operate as infrastructure instead of only as a
request library.

Why This Model Matters

This split keeps the system readable.
Realtime messaging does not have to pretend it is a batch job.
Transport code does not have to pretend it is business logic.
Remote orchestration does not have to masquerade as a normal HTTP request.
Fleet control does not have to hide inside random helper functions.

The result is that PHP code can stay simple while the runtime underneath stays
honest.
An application can use the small surface when that is enough, and still drop
into explicit session, stream, channel, control-plane, or fleet-plane behavior
when the system actually needs it.

System Model

King follows a few hard rules:

• Configuration is explicit. A King\Config snapshot governs behavior.
• State is explicit. A King\Session owns connection or listener state.
• Streams are explicit. A King\Stream models bidirectional protocol work.
• Responses are explicit. A King\Response models structured receive state.
• Ownership is deterministic. Native resources are tied to PHP-visible handles.
• The OO and procedural APIs are parallel surfaces over the same native kernels.
• Security defaults stay conservative unless an operator explicitly loosens them.
• Runtime policy beats convenience. There is no hidden global magic pool.
• The target contract is not allowed to shrink just because the correct
  implementation is harder. If a subsystem matters for v1, the work is to make
  the stronger contract real, not to quietly redefine it downward.

Target Subsystems

Transport and Protocols

King is intended to expose a native transport stack for:

• QUIC transport
• HTTP/1 request and response handling
• HTTP/2 multiplexed transport
• HTTP/3 over QUIC
• TLS policy, certificate handling, and ticket reuse
• cancellation, timeouts, retry policy, and streaming response control
• upgrade-oriented flows such as WebSocket and related realtime protocols

Client and Server Runtime

King targets symmetric client and server operation:

• outbound request clients for protocol-specific and generic HTTP use
• inbound listener and dispatch surfaces for server use
• session-scoped protocol metadata
• request and response streaming
• early hints, upgrade, close, and control hooks
• admin and operational control APIs

Discovery and Control Plane

King includes a native control-plane model around:

• Smart DNS and Semantic DNS service registration
• topology awareness
• route selection
• router/loadbalancer backend discovery, configuration, and policy
• mother-node or control-node coordination
• policy-aware service discovery
• control and telemetry endpoints

Data Plane

King is also a data and protocol runtime:

• IIBIN for schema-defined binary serialization
• MCP for tool and agent protocol traffic
• real multi-backend object-store primitives
• CDN-oriented cache distribution hooks
• pipeline orchestration for multi-step, recovery-aware workloads

Observability and Operations

Operational visibility is a first-class concern:

• OpenTelemetry-compatible tracing and metrics surfaces
• health and status reporting
• performance and component introspection
• config policy enforcement
• ticket, certificate, and reload lifecycle management
• autoscaling and cluster integration hooks

Public Programming Model

The core programming model is:

• King\Config defines transport, protocol, security, and subsystem policy.
• King\Session represents a live native runtime context.
• King\Stream represents one unit of protocol work inside a session.
• King\Response represents structured receive state for request flows.
• King\Client\* and King\Server\* expose higher-level protocol roles.
• King\MCP, King\IIBIN, King\ObjectStore, King\Autoscaling, and
  King\WebSocket\Connection expose subsystem-specific runtime surfaces.

The procedural API exists for direct systems work and low-friction interop.
The OO API exists for typed composition and long-lived application structure.
Neither exists only as a thin wrapper around the other.

Design Priorities

King optimizes for:

• predictable ownership and teardown
• native protocol semantics instead of generic adapter layers
• typed error boundaries
• config-driven behavior
• minimal impedance between PHP code and native transport state
• operator control over policy and security
• compatibility with serious production environments

Architecture

At a high level, the target architecture is:

PHP Userland
  -> procedural functions and OO classes

PHP Extension Surface
  -> arginfo, object handlers, resource handlers, exception hierarchy

Native Subsystem Kernels
  -> client, server, semantic DNS, IIBIN, MCP, object store, telemetry, etc.

Configuration and Lifecycle Layer
  -> defaults, ini, config snapshot, runtime policy, shutdown semantics

External Backends
  -> quiche, OpenSSL, libcurl, kernel networking facilities

The important boundary is this:
King is not supposed to look like "PHP calling random native helpers".
It is supposed to look like one native system with a PHP-facing control surface.

Documentation

The handbook lives under documentation/

Build

To build the extension from source:

git clone --recurse-submodules https://github.com/Intelligent-Intern/king.git
cd king
./infra/scripts/build-extension.sh

For a fully runnable local release profile, including libquiche.so and
quiche-server, use:

cd king
./infra/scripts/build-profile.sh release

The build path above bootstraps the pinned QUIC dependency checkout recorded in
infra/scripts/quiche-bootstrap.lock
and normalizes the matching workspace lockfile before cargo is invoked. Do not
replace it with ad hoc local quiche clones or unlocked cargo retries.

The build entrypoint above is the repository build path.
Canonical release-install verification then runs through
./infra/scripts/package-release.sh, ./infra/scripts/install-package-matrix.sh, and
./infra/scripts/container-smoke-matrix.sh.
The supported host/runtime verification matrix spans PHP 8.1 through 8.5.

PIE

King now carries the first honest maintainer surface for
PIE, the PHP Installer for Extensions.

The intended package shape is:

• root composer.json with type = php-ext
• build-path = extension
• a pre-packaged source asset built with
  ./infra/scripts/package-pie-source.sh

That source asset is the important part. King cannot rely on the default
repository ZIP for PIE because the bundled quiche/ tree is part of the active
build. The maintainer workflow is documented in
documentation/pie-install.md.

Contributing

See CONTRIBUTE.

License

MIT. See https://opensource.org/licenses/MIT.