PHP runtimes

​

Overview

​

The 5-second budget

​

PHP-FPM

• The session lock. On every web runtime, before it delivers, AgentCat writes and closes an active PHP session (session_write_close()), so the next request of the same client does not wait for the lock. A destructor that writes to $_SESSION after that loses its write.
• The time limit. On every web runtime, when max_execution_time is set, AgentCat gives its delivery its own limit with set_time_limit(6), so a request that used most of its time does not end the delivery with a fatal error. That call can also shorten a longer limit for code that runs after AgentCat’s shutdown function.
• request_terminate_timeout. This limit of the FPM pool counts wall-clock time, and PHP code cannot change it. When it is shorter than your slowest request plus the delivery, FPM kills the worker during the delivery, and the events of that request are lost. Leave at least 6 seconds plus the time your hooks take over your slowest request.
• Diagnostics. AgentCat sends its diagnostics after the response, within the budget. Each diagnostics request has a 250 ms connect timeout and a 1-second total timeout, so a collector that does not answer holds the worker only briefly.
• A host that disables fastcgi_finish_request() gets the behavior of Apache mod_php (below): the response goes out at the end of the script.

​

FrankenPHP

<?php

declare(strict_types=1);

use AgentCat\AgentCat;
use Http\Discovery\Psr17Factory;
use Mcp\Server;
use Mcp\Server\Transport\StreamableHttpTransport;

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

$handler = static function (): void {
    $builder = Server::builder()
        ->setServerInfo('worker-mcp', '1.0.0')
        ->addTool(static fn(string $msg): string => $msg, 'echo', description: 'Echo a message');
    AgentCat::track($builder, 'proj_YOUR_PROJECT_ID');

    $factory = new Psr17Factory();
    $response = $builder->build()->run(new StreamableHttpTransport($factory->createServerRequestFromGlobals(), $factory, $factory));
    http_response_code($response->getStatusCode());
    foreach ($response->getHeaders() as $name => $values) {
        header($name . ': ' . implode(', ', $values));
    }
    echo $response->getBody();
};

while (frankenphp_handle_request($handler)) {
    AgentCat::flush(1.0); // after each response: deliver this request's events, waiting at most 1 second
}

• Worker detection. AgentCat detects worker mode from the FRANKENPHP_WORKER environment variable that FrankenPHP sets. Inside a request, $_SERVER does not have it, so keep the variable in the worker’s environment.
• Errors after the response. The official FrankenPHP Docker image has no php.ini, so log_errors is off, and a fatal error after the response (in a hook, for example) leaves no trace. Turn it on in the Caddyfile, or ship a php.ini:

{
    frankenphp {
        php_ini log_errors 1
    }
}

​

Apache mod_php, php-cgi and php -S

• The Laravel and Symfony bridges set Content-Length on the plain JSON answers of a tracked server. They never set it on a streamed (SSE) answer, on an answer without a body (1xx, 204, 304) or to a HEAD request, on an answer that has a Content-Length or Transfer-Encoding already, or after other output went out first.
• A plain mcp/sdk script sets it itself, before it echoes the answer: header('Content-Length: ' . strlen($body)); (see the HTTP server of the mcp/sdk page).
• Headers after that point. A destructor that sets a header after AgentCat closed the buffers gets a “headers already sent” warning.
• zlib.output_compression. AgentCat closes the compression buffer with the others. Output written after that, for example an echo in a destructor, is not part of the compressed body and breaks it.
• Warnings. Under Laravel and Symfony, the framework’s error handler catches PHP’s warnings, so they reach the framework’s log, not Apache’s error log.

​

NGINX Unit

​

The CLI and containers

• Signals. With ext-pcntl, AgentCat sends the waiting events at SIGTERM and SIGINT. The mcp/sdk page explains the handlers, inherited ignores and disableSignalHandlers. The official PHP Docker images have no ext-pcntl: add RUN docker-php-ext-install pcntl to your image.
• PID 1. In a container, the process with PID 1 ignores a signal whose handler is the default one. After its delivery, AgentCat gives the signal back to that default handler, which then does not end the process. Start the server with docker run --init (or init: true in Docker Compose), as production images should, so that an init process is PID 1.
• Thread-safe (ZTS) builds, such as the official php:*-zts images: a second SIGTERM or Ctrl+C during the delivery waits until the delivery ends, up to the 5-second budget.
• Windows has no ext-pcntl, so the events that wait at Ctrl+C are lost. AgentCat logs no line for that.
• Symfony’s bin/console mcp:server ends with exit code 0 after the delivery at SIGTERM, because Symfony Console handles the signal itself, not 143.

​

Swoole, OpenSwoole, RoadRunner and Workerman

• With Laravel Octane or Symfony Runtime, AgentCat delivers in the framework’s terminate hooks: Laravel’s terminating() callbacks and Symfony’s kernel.terminate. It waits at most 1 second after each request. Events that are still waiting go out at a later request of the worker, or when the worker stops. See Laravel for Octane’s worker stop.
• A raw worker loop calls AgentCat::flush(1.0) after each request, as in the FrankenPHP loop.
• No signal handlers under Swoole and OpenSwoole. When ext-swoole or ext-openswoole is loaded, AgentCat installs no SIGTERM or SIGINT handlers: those servers stop their workers with handlers that PHP cannot see. The check looks at the loaded extension, so a stdio server on a PHP with ext-swoole loaded gets no delivery at those signals either.
• RoadRunner and Workerman install PHP signal handlers. AgentCat keeps them: after its delivery, it calls the handler that was there before.
• No async runtimes. Version 1 does not support async runtimes that interleave calls in one process, such as Swoole coroutines or ReactPHP. Serve one request at a time per worker.

​

Hardened hosts

• ext-curl, with the curl_multi_* functions, to send anything.
• One of hrtime() and microtime(). With both disabled, delivery fails.
• PHP’s core string, array, math, JSON, PCRE, mbstring, hash and error-handler functions, like every Composer package. No hosting list disables them.