Changelog 4.x
All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning and Keep a CHANGELOG.
This file covers the 4.x releases. For previous major versions see: 3.x, 2.x, 1.x
4.0.0 - 2026-10-05
Backwards incompatible changes (BC breaks)
-
PHP >= 8.0 is required. Support for PHP 7.1 - 7.4 was dropped. Version 3.x keeps supporting these PHP versions and still gets bug fixes, but no new features. - #57
-
The
fileinfoextension is required. It is used to detect the MIME type of files in multipart form-data requests. - #81 -
The content of a request is a
ComposesRequestContentobject instead of a string. - #57AbstractRequest#__construct()expects an optional content object as second argument:__construct( string $scriptFilename, ?ComposesRequestContent $content = null )AbstractRequest#setContent()expects aComposesRequestContentobject and also sets the content type of the request. A content type that was set before is overwritten.ProvidesRequestData#getContent()returns?ComposesRequestContentinstead ofstring.- The named constructor
newWithRequestContent(), introduced in 3.1.0, was removed from all request classes. - The content length and, unless it was set explicitly, the content type of a request are determined from the
content object when the request is sent, which composes the content twice: once for the
CONTENT_LENGTHparameter and once for the body. Changes to the content object after it was passed to the request are taken into account. - #76, #97
# Previous versions$request = new PostRequest( '/path/to/script.php', http_build_query( ['key' => 'value'] ) );$request = PostRequest::newWithRequestContent( '/path/to/script.php', new UrlEncodedFormData( ['key' => 'value'] ) );$request = new PostRequest( '/path/to/script.php', 'plain text' );$request->setContentType( 'text/plain' );# Since 4.0.0$request = new PostRequest( '/path/to/script.php', new UrlEncodedFormData( ['key' => 'value'] ) );$request = new PostRequest( '/path/to/script.php', new PlainText( 'plain text' ) );Content types that are not covered by the classes in
hollodotme\FastCGI\RequestContentsneed an own implementation of theComposesRequestContentinterface. -
The interface
ConfiguresSocketConnectionhas the new methodgetStreamSelectTimeout() : int, which must be added to own implementations of this interface. - #82 -
Client#readResponses()andClient#readReadyResponses()throw the exception, if a response cannot be read, e.g. aTimedoutException. Before, such responses were skipped silently. Unknown socket IDs are still skipped. -
Client#waitForResponse()andClient#waitForResponses()time out after the read/write timeout of the connection, if no timeout is passed. The failure callbacks of requests without response are notified with aTimedoutExceptionthen. Before, both methods waited until the response was received, also for scripts that run longer than the read/write timeout before they send output. Pass a timeout that is long enough for your scripts. -
The interface
ProvidesResponseDatahas the new methodgetStatusCode() : int, which must be added to own implementations of this interface. -
The public constant
Socket::STREAM_SELECT_USECwas removed in favour of the configurable stream select timeout of the socket connections. - #82 -
Classes that extend
AbstractRequestor a request class must adapt overriddensetContent()andgetContent()methods and calls ofparent::__construct()to the content object. New public methods may collide with methods of own subclasses:Client#tryRequest(),Client#tryAsyncRequest(),AbstractRequest#setQueryParams(),AbstractRequest#getQueryParams(),AbstractRequest#getQueryString()andResponse#getStatusCode(). - #57
Added
- Method
Response#getStatusCode(), which returns the status code of theStatusheader, or 200 if there is none. - Request content composer
PlainTextfor content typetext/plain. - Configurable stream select timeout as third timeout of the socket connections
NetworkSocketandUnixDomainSocket. It defines how long the client waits when checking for responses. The default isDefaults::STREAM_SELECT_TIMEOUT(200 ms), which is the value used in previous versions. - #82, #18 - Query parameters can be passed as an array to all requests with
AbstractRequest#setQueryParams(). They are sent asQUERY_STRINGand appended to theREQUEST_URI.AbstractRequest#getQueryParams()andAbstractRequest#getQueryString()return the parameters and the encoded query string. - #83 - Methods
Client#tryRequest()andClient#tryAsyncRequest(), which send a request again on another socket, if writing the request to a socket failed. - #84 - Compatibility with PHP 8.2, 8.3, 8.4 and 8.5. All test suites run on PHP 8.0 - 8.5.
- Validation of received packets according to the FastCGI specification. A
ReadFailedExceptionis thrown, if a packet has an unsupported protocol version, an unexpected record type, the ID of another request or, in case of an end-request record, an unexpected length. - #78, #95
Improved
- Idle sockets that were closed by the peer, e.g. because their php-fpm child process was terminated, are detected and replaced before a request is sent. - #84
- Use of PHP 8.0 language features like typed properties, constructor property promotion,
matchandmixed. - PHPStan (level 8) is part of the test pipeline and analyses the code on and for each supported PHP version.
- Values passed to
chr()when encoding packets are limited to one byte, because values out of this range are deprecated in PHP 8.5. - A single PHPUnit version is used for all supported PHP versions.
- Compatibility with FastCGI servers of other programming languages is checked continuously in a workflow per server,
independently of the CI workflow (
make test-compatibility). - PHP_CodeSniffer is part of the test pipeline and checks the coding standard, PSR-12 with the adjustments listed
in the contribution guide (
make phpcs,make phpcbf). - #75, #98 - Integration tests do not depend on fixed waiting times anymore. - #86
- Documentation and changelog are split by major version. - #87
- The documentation moved to a website at fast-cgi-client.hollo.me, with the
documentation of all major versions and their API reference. It is built with Docusaurus and Doctum
(
make docs-serve,make docs-build) and deployed to GitHub Pages. The README gives a short overview. - Interactive animations in the documentation show step by step what happens when sending requests synchronously, asynchronously and in parallel, with callbacks, pass-through callbacks and retries, how sockets are reused and how a request is sent as FastCGI records — next to the example code and its output.
- Code examples and their printed output in the documentation were checked against the library by running them, and corrected where they differed, e.g. the pass-through callback example prints the output and the error output only if the callback receives them.
- A migration guide in the documentation shows what to change in your code when upgrading from 3.x, and the changelogs of all major versions are part of the documentation website.
- New design of the documentation website with self-hosted fonts and a homepage showing the download numbers from Packagist, the packages depending on the library, the results of the compatibility tests, all contributors and a card for sponsoring the maintainer on GitHub.
- The development environment uses the
docker composeplugin instead of the standalonedocker-composebinary.
Fixed
Most of these fixes were also released for 3.x in version 3.1.8.
Client#waitForResponse()andClient#waitForResponses()did not return, if the server did not respond, even if a timeout was passed. After the timeout the failure callbacks of the request are notified with aTimedoutExceptionnow.- A socket that could not connect stayed in the collection of the client.
- Endless loop when the connection was closed before a packet was received completely, e.g. when the process
handling the request was terminated while it sent its response, or when the client was connected to a HTTP server
instead of a FastCGI server. A
ReadFailedExceptionis thrown now. - #78, #95 - Reading a response that was not completed by the server timed out after twice the read/write timeout.
- Packet headers are read completely before they are decoded, also if they arrive in several parts.
NameValuePairEncoder#decodePairs()decoded names and values of 16 MiB and more with a wrong length.- The first two lines of a response were lost, if it did not start with a header.
- Output that starts with header lines, but has no blank line after them, was split into headers and a body that lost its first line. It is the body of the response now, without headers. The headers of a response are separated from its body by a blank line, which php-fpm always sends.
- A header value continued on the next line (obsolete line folding) ended the headers and was lost. It is appended to the value of the header now.
- Headers and body of a response are separated independently of the line endings of the platform the client runs on.
- Request parameters longer than 65535 bytes in total corrupted the request, because the length of a record was cut
to 2 bytes. They are sent in multiple records now, split between name-value pairs.
PacketEncoder#encodePacket()splits content that is longer than one record into consecutive records of the same type. - Request content
"0"was not sent. - A request that could only be written partly, e.g. because the server did not read it before the read/write timeout,
was treated as sent. A
TimedoutExceptionorWriteFailedExceptionis thrown now. - A read timeout passed to
readResponse()and the other methods reading responses applied to writing the next request on the same socket as well. The read/write timeout of the connection applies again. - An idle socket was reported as having a response, when the server closed its connection. Its response was then
returned again by
readReadyResponses(), and its callbacks were notified again byhandleReadyResponses()andwaitForResponses(). Client#hasResponse()andClient#waitForResponse()checked the stream of a socket whose response was already read withreadResponse().hasResponse()returnedfalse, andtrueonce the server closed the idle connection.waitForResponse()blocked until then. Such a socket has its response now.- A response without any packet was returned as an empty response, if the socket had no stream anymore. A
ReadFailedExceptionis thrown now. Client#getSocketIdsHavingResponse()and the methods based on it could throw aValueErroron PHP 8, if the sockets of the client had no stream, e.g. after a failed connect.- An end-request record without protocol status caused an "Uninitialized string offset" warning and was treated as
a completed request. A
ReadFailedExceptionis thrown now. - #78, #95