localzet / core

v7.0.0 2026-09-30 17:12 UTC

Requires

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

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5 || ^11 || ^12
• revolt/event-loop: ^1.0

Suggests

• ext-ev: Native libev backend.
• ext-event: Native libevent backend.
• ext-pcntl: Multi-process supervision and hot-upgrade on Unix.
• ext-posix: Unix process, signal and privilege management.
• ext-redis: Redis-backed HTTP sessions.
• ext-sockets: Socket tuning and zero-downtime hot-upgrade descriptor passing.
• ext-swoole: Optional native Swoole coroutine event backend.
• ext-swow: Optional native Swow coroutine event backend.
• localzet/events: Optional Localzet lifecycle event bus integration.
• mongodb/mongodb: MongoDB-backed HTTP sessions.
• revolt/event-loop: Fiber-based event loop backend and non-blocking Timer::sleep().

AGPL-3.0-or-later

• Ivan Zorin

• http
• websocket
• tcp
• server
• event-loop
• udp
• asynchronous

Published on Packagist.org on 2026-09-30 17:17 UTC

README

Русская документация

High-performance event-driven server runtime for PHP with TCP, UDP, HTTP/1.1, WebSocket, timers, long-lived connections and multi-process workers.

This development branch targets the 7.0 runtime line, including process supervision, HTTP/1.x/WebSocket protocols and a bounded L4/L7 gateway. The released 4.x packages used by Cluster and other libraries are a separate compatibility line; do not treat installation of the published package as installation of this branch.

Requirements

• PHP 8.1+
• Composer is required for package installation, but the runtime core has no mandatory third-party PHP package dependency
• Unix: pcntl and posix are recommended for multi-process mode
• Windows works in single-process mode

Optional integrations such as revolt/event-loop, localzet/events, sockets, event, ev, swoole, swow, Redis and MongoDB add event-loop, lifecycle, hot-upgrade and session capabilities. Portable Select remains available without Revolt.

Install

composer require localzet/server

For development of this branch:

composer install
composer check
composer test:integration
composer release:audit
composer analyze

composer analyze performs basic PHPStan level-0 analysis of the core. Optional Swow and MongoDB adapters are excluded from this check because their extension/package declarations are not installed in the core environment. Higher-level type analysis and separate optional-adapter validation remain follow-up work.

HTTP example

<?php

use localzet\Server;
use localzet\Server\Connection\TcpConnection;
use localzet\Server\Protocols\Http\Request;
use localzet\Server\Protocols\Http\Response;

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

$server = new Server('http://0.0.0.0:8080');
$server->name = 'api';
$server->count = 4;

// Production guardrails are opt-in and can be tuned per endpoint.
$server->maxRequests = 10_000;
$server->maxLifetime = 3600;
$server->maxMemory = 256 * 1024 * 1024;
$server->maxConnections = 10_000;
$server->idleTimeout = 60;
$server->frameTimeout = 15;
$server->tlsHandshakeTimeout = 10;

$server->onMessage = static function (TcpConnection $connection, Request $request): void {
    $connection->send(new Response(200, [
        'Content-Type' => 'application/json; charset=utf-8',
    ], json_encode([
        'ok' => true,
        'path' => $request->path(),
    ], JSON_THROW_ON_ERROR)));
};

Server::runAll();

HTTP keep-alive and Connection: close are handled by the HTTP protocol/transport layer. Application code does not need to close every ordinary HTTP connection manually.

Process control

Use the same entry file to control the master process:

php server.php start
php server.php start -d
php server.php status
php server.php status --json
php server.php connections
php server.php connections --json
php server.php reload
php server.php reload -g
php server.php upgrade
php server.php capabilities
php server.php capabilities --json
php server.php restart
php server.php restart -g
php server.php stop
php server.php stop -g
php server.php version
php server.php help

reload performs a rolling worker replacement: one worker is replaced and restored before the next one is touched. reload -g drains connections through the graceful path. Because reload forks from the already loaded master image, definitions already resident in master are inherited unchanged.

upgrade is the code-deployment operation on supported Unix runtimes. The master performs pcntl_exec() without changing its PID, restores the startup lock/listening sockets through authenticated SCM_RIGHTS descriptor passing, rereads the application bootstrap and then rolling-replaces old worker images. If listener topology changes, use restart -g.

capabilities [--json] reports whether the host can hot-upgrade and which event-loop backends are actually available. Explicitly selecting an unavailable backend fails fast instead of silently degrading.

Concurrent start commands are protected by a startup flock, preventing a second master from racing the PID file or listener bind. External SIGTERM (the normal Docker/systemd/Kubernetes stop signal) uses graceful draining; SIGINT remains the fast-stop signal.

HTTP file serving

Response::withFileForRequest() understands common HTTP cache and range semantics:

$connection->send(
    (new Response())->withFileForRequest($request, __DIR__ . '/public/archive.zip')
);

It supports HEAD, ETag / If-None-Match, Last-Modified / If-Modified-Since, If-Match, If-Unmodified-Since, single byte ranges and If-Range. Large files are streamed with backpressure instead of being loaded wholly into memory. Multipart byte ranges are deliberately not implemented yet.

HTTP request limits are configurable globally when an application needs stricter bounds:

use localzet\Server\Protocols\Http;

Http::maxHeaderLength(16 * 1024);
Http::maxHeaderCount(100);

The parser also handles Expect: 100-continue, validates HTTP/1.1 Host, rejects ambiguous request framing and accepts standards-compliant extension methods such as WebDAV verbs rather than using a fixed method whitelist.

Gateway

The 6.4 line adds a deliberately small programmable gateway layer without coupling it to Server.php:

• Upstream / UpstreamPool with weighted round-robin, least-connections and random selection;
• passive quarantine and active TCP health checks;
• raw TCP proxying with backpressure and safe connect-time failover;
• streaming HTTP/1.x reverse proxying with host/path-prefix routing, optional path rewrite, Forwarded/X-Forwarded-*, upstream keep-alive and WebSocket Upgrade tunneling;
• retries only before an upstream connection is established, avoiding unsafe replay after bytes may have been consumed.

Gateway acceptance tests cover dead-first upstream failover, byte-exact L4 payloads, streaming request bodies, chunked requests, keep-alive and WebSocket tunneling.

License and provenance

Localzet Server is distributed under GNU AGPL-3.0-or-later.

Documentation: https://server.localzet.com

Attribution

Maintainer of Localzet contributions: Ivan Zorin (localzet) — [e-mail] · https://www.localzet.com. Copyright © 2026 Localzet Group. Original authorship and third-party licenses remain applicable. See AUTHORS.