Fast Cgi Client Laravel Package

Getting Started

Start by installing the package via Composer: composer require hollodotme/fast-cgi-client. The main entry point is the FastCgi\Client class — instantiate it with a connector (e.g., TcpSocketConnector or UnixSocketConnector) pointing to your FastCGI backend (e.g., 127.0.0.1:9000 for PHP-FPM or /run/php/php-fpm.sock). To execute a PHP script, prepare a Request with the script path, query string (optional), and custom params (e.g., $_SERVER variables). Then call execute() and read the response using getStdout() or getStderr(). A minimal first use case is running a PHP snippet directly against FPM without Apache/Nginx:

$connector = new \FastCgi\Connectors\UnixSocket('/run/php/php-fpm.sock');
$client    = new \FastCgi\Client($connector);
$request   = new \FastCgi\Request('/path/to/script.php', [], ['SCRIPT_FILENAME' => '/path/to/script.php']);
$response  = $client->execute($request);
echo $response->getStdout();

Check the examples/ directory in the repo for quick start patterns.

Implementation Patterns

• Background workers: Spawn FPM-managed workers programmatically for long-running tasks (e.g., queue consumers), passing environment via Request to configure behavior.
• Health checks: Verify PHP-FPM readiness and script execution latency without HTTP overhead by sending a trivial <?php echo 'ok'; snippet.
• Integration testing: Mock HTTP flows by executing PHP scripts in isolation with controlled $_SERVER and $_ENV, avoiding fixture dependencies on web servers.
• CLI tooling: Build CLI tools that leverage PHP-FPM’s process pooling (e.g., for concurrency control, memory isolation, or opcache reuse) — ideal for batch processing.
• Custom environments: Use setParams() to inject arbitrary FastCGI params (e.g., PHP_VALUE, PHP_ADMIN_VALUE) for runtime configuration overrides without .ini changes.
• Connection pooling: Reuse a single Client instance (thread-safe) for multiple requests to reduce socket overhead — especially beneficial under load.

Gotchas and Tips

• Script path must exist on the FPM server: The SCRIPT_FILENAME must be resolvable by the FPM process — misconfigurations (e.g., mismatched paths between client/server) yield 404 or 500 silently. Enable debug logging via Request::setVerbose(true) or inspect $response->getRawRecords().
• Protocol version mismatch: Ensure the FastCGI backend (e.g., PHP-FPM 7.4/8.x) supports the protocol version used — the library defaults to FCGI_VERSION_1, which is standard, but older FPM versions may need manual tuning.
• Stderr not always populated: Failed scripts may write to stderr, but FPM often logs errors internally instead. Always inspect raw records ($response->getStderr() + protocol-level FCGI_STDERR blocks) for debugging.
• Blocking I/O limitations: The client uses blocking sockets by default — pair with pcntl_async_signals() or reactive loops (e.g., ReactPHP via reactphp/socket) for non-blocking usage.
• Connection timeout handling: Wrap calls in try/catch — TimeoutException may be thrown; configure timeouts via connector: (new UnixSocket($path))->setTimeout(3.0).
• No built-in concurrency: For high-throughput workloads, manually pool connections or use StreamSelectLoop (see examples in repo).
• Legacy config: Set clear_env = no in php-fpm.conf if expecting to pass arbitrary $_SERVER values — otherwise, FPM may discard custom params.