fast-cgi-client talks to PHP-FPM over the FastCGI protocol from PHP

FastCGI from PHP, not HTTP from PHP

fast-cgi-client is a PHP fast CGI client for sending requests, synchronously or asynchronously, to PHP-FPM using the FastCGI Protocol. The distinction from an HTTP client is the whole point of the library, and it is worth being clear about because the name invites confusion. An HTTP client speaks HTTP to a web server, which then decides what to run. A FastCGI client speaks FastCGI directly to a PHP-FPM process, which means it asks FPM to execute a specific script and returns the result. The library is based on the work of Pierrick Charron's PHP-FastCGI-Client and was ported and modernized to latest PHP versions, extended with some features for handling multiple requests, in loops, and with unit and integration tests. The default branch is master, the current release line is 4.x, and the licence is a custom one (see the LICENSE file). The primary language is PHP, and the last push to the repository was on 2026-10-05.

The object model: connection, request, response

The quick example in the documentation is compact enough to read in one pass, and it shows the shape of the API. You create a client, you create a connection, you create a request, and you send it.

<?php declare(strict_types=1);

use hollodotme\FastCGI\Client;
use hollodotme\FastCGI\RequestContents\UrlEncodedFormData;
use hollodotme\FastCGI\Requests\PostRequest;
use hollodotme\FastCGI\SocketConnections\NetworkSocket;

$client     = new Client();
$connection = new NetworkSocket( '127.0.0.1', 9000 );
$request    = new PostRequest( '/path/to/target/script.php', new UrlEncodedFormData( ['key' => 'value'] ) );

$response = $client->sendRequest( $connection, $request );

echo $response->getBody();

The namespaces carry the design. SocketConnections is where the transport lives, and NetworkSocket takes a host and a port, so the obvious first implementation is a TCP socket to an FPM listener on port 9000. Requests holds the request types, and PostRequest takes a script path and a body, with UrlEncodedFormData as one of the content types. The response object is then read with getBody. Separating the connection from the request is what makes the asynchronous and multi-request features possible, because one connection can carry several requests and you decide per call whether to wait for the answer.

Why the FastCGI protocol is the constraint

Everything about this library follows from the protocol it implements. The FastCGI protocol is a binary framing protocol where a request carries a set of FastCGI records describing the environment variables the script should see, the standard input stream and the standard output stream. A client has to negotiate the record types, multiplex the streams, and handle the connection record that marks the end of a response. That is a real amount of work to do correctly, and it is why an HTTP client cannot be reused for it. The upshot for an adopter is that the client is a protocol implementation with a request and response model layered on top, not a general HTTP client with a FastCGI mode. The documentation site at fast-cgi-client.hollo.me has a section on what it is, installation, getting started, and a use cases and examples category covering connections, single requests, multiple requests, requests, responses, exceptions and troubleshooting, plus an API reference for the 4.x line. The README also notes that sending requests asynchronously, reacting to responses with callbacks, and streaming output are described there.

Version lines, PHP requirements and the upgrade warning

The versions table in the README is the compatibility contract, and it is worth reading before you pick a line. The current line is 4.x, which requires PHP 8.0 or later, with documentation and changelog for that line. The 3.x line requires PHP 7.1 or later, and 2.x also requires PHP 7.1, while 1.x requires PHP 7.0. The README states plainly that version 3.x still gets bug fixes, but no new features, which makes 3.x the safe destination for an application that cannot move to PHP 8 yet, and 4.x the line to target for anything new. There is an explicit warning to look at the backwards incompatible changes in the changelog when upgrading from a previous version, and the changelog is split per line in the docs directory, with a separate 3.x changelog file listed. The CI badge covers PHP 8.0 through 8.5, and separate compatibility workflows exist for FastCGI servers written in Go, in Rust, in Rust with tokio, in C# and in Java, which is an unusually broad interoperability test matrix for a PHP library.

The development setup, and a compose file per PHP version

The repository ships a Docker Compose file with one service per supported PHP version, from php80 through php85, each building from a Dockerfile in the .docker/php context and mounting the repository at /repo, plus two documentation services behind a docs profile, one running node:24-alpine for the documentation website on port 3000 and one building the API documentation. The Makefile drives that stack with named targets, and the naming makes the workflow readable. The update target depends on dcbuild, dcpull and composer-update. The dcbuild target builds all the custom docker images in parallel, with a pull-extension-installer prerequisite that fetches the mlocati/php-extension-installer image. The dcpull target pulls the images and dcdown tears the stack down. The install-composer target downloads composer.phar into the .tools directory inside the container, and there is a comment explaining why: Composer cannot detect the version of the package itself, because there is no git in the containers, so the version is derived from the host with a git rev-parse fallback to main. The top level also carries phpcs.xml, phpstan.neon and phpunit.xml, so static analysis, coding standards and tests are all configured in the repository.

Where this library is the wrong tool

The boundaries are structural rather than a matter of missing features. First, if the target is a normal web application behind nginx or Apache, an HTTP client is the right thing, and using FastCGI here means you would be reimplementing what the web server already does for you. Second, the library is PHP, so a team whose runtime is not PHP gets nothing from it even though the protocol is language agnostic, and the interoperability badges with Go, Rust, C# and Java servers are about the server side, not the client. Third, the 4.x line needs PHP 8.0 or newer, so an application stuck on PHP 7.1 is limited to 3.x, which receives bug fixes but no new features, and the README asks you to read the changelog for the backwards incompatible changes before upgrading. Fourth, the library speaks to one pool over one connection, and the multiple request and loop handling the author added is about throughput through a single connection rather than about managing a fleet of workers, so if your problem is scheduling work across a queue you will still need a queue.

Editorial conclusion

Adopt fast-cgi-client if you run PHP and need to call a PHP-FPM process directly, for example to invoke a background worker or a script in another container, since the library implements the FastCGI protocol rather than trying to emulate HTTP. Do not adopt it to replace your web server, and do not adopt it if the target only speaks HTTP, because FastCGI and HTTP are different protocols and this client speaks the former. Verify two things before you build on it: that you have network access to the FPM pool you are connecting to, and that you are on the 4.x line, which requires PHP 8.0 or newer, with the changelog documenting the backwards incompatible changes from 3.x. The practical first step is to install the package with composer require and send one request to a local FPM listener on port 9000 using the NetworkSocket connection, then compare the response body with what the same script returns through a web server.

Frequently asked questions

Official sources

1. hollodotme/fast-cgi-client on GitHub
2. Issues
3. README
4. Releases