localzet / core
High-performance asynchronous event-driven server for PHP.
Fund package maintenance!
Requires (Dev)
- phpstan/phpstan: ^2.3
- 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().
Provides
None
Conflicts
None
Replaces
None
- dev-main / 7.2.x-dev
- v7.2.2
- v7.2.1
- v7.2.0
- v7.1.0
- v7.0.4
- v7.0.3
- v7.0.2
- v7.0.1
- v7.0.0
- v4.5.3
- v4.5.2
- v4.5.1
- v4.5.0
- v4.4.4
- v4.4.3
- v4.4.2
- v4.4.1
- v4.4.0
- v4.3.9
- v4.3.8
- v4.3.7
- v4.3.6
- v4.3.5
- v4.3.4
- v4.3.3
- v4.3.2
- v4.3.1
- v4.3.0
- v4.2.39
- v4.2.38
- v4.2.37
- v4.2.36
- v4.2.35
- v4.2.34
- v4.2.33
- v4.2.32
- v4.2.31
- v4.2.30
- v4.2.29
- v4.2.28
- v4.2.27
- v4.2.26
- v4.2.25
- v4.2.24
- v4.2.23
- v4.2.22
- v4.2.21
- v4.2.20
- v4.2.19
- v4.2.18
- v4.2.17
- v4.2.16
- v4.2.15
- v4.2.14
- v4.2.12
- v4.2.11
- v4.2.10
- v4.2.9
- v4.2.8
- v4.2.7
- v4.2.6
- v4.2.5
- v4.2.4
- v4.2.3
- v4.2.2
- v4.2.1
- v4.2.0
- v4.1.6
- v4.1.5
- v4.1.3
- v4.1.2
- v4.1.1
- v4.1.0
- v4.0.10
- v4.0.9
- v4.0.8
- v4.0.7
- v4.0.6
- v4.0.5
- v4.0.4
- v4.0.3
- v4.0.2
- v4.0.1
- v4.0.0
- v3.1.2
- v3.1
- v3.0.20
- v3.0.19
- v3.0.18
- v3.0.17
- v3.0.16
- v3.0.15
- v3.0.14
- v3.0.13
- v3.0.12
- v3.0.11
- v3.0.10
- v3.0.9
- v3.0.8
- v3.0.7
- v3.0.6
- v3.0.5
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v2.2.8
- v2.2.7
- v2.2.6
- v2.2.5
- v2.2.4
- v2.2.3
- v2.2.2
- v2.2.0
- v2.1.0
- v2.0.0
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.9
- v1.1.7
- v1.1.6
- v1.1.5
- v1.1.4
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.10
- v1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-fix/reject-unsupported-http-alpn
- dev-feat/server7-dependency-refresh
- dev-feat/server-tls-alpn
- dev-release/server-v7.2.1
- dev-feat/server7-mtls-verification
- dev-fix/graceful-dispatch-state
- dev-feat/license-runtime-lifecycle
- dev-PHP-8.2
- dev-psr
- dev-dev
This package is auto-updated.
Last update: 2026-11-21 16:26:59 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.
The current stable release is 7.2.1. It provides process supervision, HTTP/1.x and WebSocket protocols, and a bounded L4/L7 gateway. Packages from version 4.x have a different public API; see the compatibility guide for the changes and migration notes.
Requirements
- PHP 8.1+
- Composer is required for package installation, but the runtime core has no mandatory third-party PHP package dependency
- Unix:
pcntlandposixare recommended for multi-process mode - Windows works in single-process mode
- The core CI matrix covers PHP 8.1 through 8.5; optional extension combinations are not all covered by that matrix
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 benchmark -- --smoke
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.
The core keeps composer.lock out of version control because this is a library: consuming applications resolve and lock
their own dependency graph. CI resolves one PHP 8.1-compatible toolchain for the PHP matrix and separately resolves and
tests the latest allowed dev dependencies in its weekly update job. The project uses PHPStan for static analysis and
script-based PHP smoke/integration tests; PHPUnit is not installed because the current test suite does not use it. Run
composer audit when reviewing dependency updates.
Support and operations
- The declared runtime floor is PHP 8.1. CI exercises PHP 8.1–8.5 on Linux; Windows is documented for single-process use, but is not part of this CI matrix. Optional extension/backend combinations require separate validation.
- On Unix, multi-process supervision depends on
pcntlandposix. Hot upgrade requires PHP 8.4+ withext-socketsclose-on-exec socket flags and descriptor passing support. PHP 8.1–8.3 can run the server without hot upgrade; checkphp server.php capabilities --jsonon the target host before relying on it. - Keep HTTP header/frame/connection limits and timeouts appropriate to the deployment. Configure trusted proxies
explicitly before consuming forwarded client-IP headers. Terminate TLS at a trusted edge or configure the TLS
listener; use graceful
SIGTERMshutdown in orchestrators. - For mutual TLS, set
LOCALZET_SSL_VERIFY_PEER=trueand pointLOCALZET_SSL_CAFILEat the CA that issued client certificates. The listener also needs its server certificate and private key; keep the key readable only by the service account. Client-certificate validation gates the TLS connection and does not replace application-level identity mapping or authorization. The built-in HTTP and WebSocket codecs close a TLS connection when ALPN selects a protocol other thanhttp/1.1; they never parse another protocol as HTTP/1.x. - The gateway is an HTTP/1.x and raw TCP proxy, not a general-purpose API gateway. Route only to trusted upstreams, review forwarded-header policy, and size connection/time limits for expected traffic.
- Pin and test the exact package version used by applications. Do not assume code written for version 4.x works with version 7.x; the compatibility guide describes the differences.
Development setup
See contribution guidelines before submitting changes. Repository settings are provided for PhpStorm and VS Code; VS Code recommends Intelephense, EditorConfig and Xdebug. Install Composer dev dependencies, then use the Composer commands listed above or the VS Code task palette. The test suite consists of PHP scripts rather than PHPUnit test cases.
For security reports, follow the security policy. Do not put vulnerability details in public issues.
Performance measurement
Run the repeatable parser microbenchmark with composer benchmark. It prints JSON including PHP version, OS,
architecture, warm-up, iteration count, elapsed time, throughput and peak memory. For a quick harness check use
composer benchmark -- --smoke; smoke numbers are not performance results. Use the same host, PHP build, extensions,
and configuration when comparing revisions. This microbenchmark measures HTTP request parsing only; it does not
represent end-to-end throughput, latency under load, or multi-worker capacity.
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.
Mutual TLS
The HTTPS listener uses PHP's TLS stream context. To require a client certificate issued by a trusted CA, configure the server certificate/key and the client CA before starting the process:
export LOCALZET_SSL_CERT=/etc/localzet/server.pem export LOCALZET_SSL_CERT_KEY=/etc/localzet/server.key export LOCALZET_SSL_VERIFY_PEER=true export LOCALZET_SSL_CAFILE=/etc/localzet/client-ca.pem php server.php start
The client must present its certificate and private key during the TLS handshake. Connections with a missing or
untrusted client certificate are rejected before onConnect and the HTTP callback run. For TLS listeners, onConnect
runs only after a successful handshake. Protect the server private key and distribute client private keys through your
normal secret-management process. This verifies the certificate chain; map client certificates to application
identities and permissions separately.
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.
Hot upgrade needs PHP 8.4+; on PHP 8.1–8.3 the server runs without that capability. Explicitly selecting an unavailable
event-loop 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/UpstreamPoolwith 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
Copyright © 2016-2026 Localzet Group. All rights reserved. Original authorship and third-party licenses remain applicable. See AUTHORS.