filisko/fastcgi-client

A modern and lightweight FastCGI client that works with Guzzle promises and PSR-7 responses

dev-main 2025-05-31 18:47 UTC

Requires

• php: >=7.2
• filisko/testable-functions: ^1.2
• guzzlehttp/promises: ^2.2
• middlewares/utils: ^2 || ^3 || ^4
• psr/http-factory: ^1.0
• psr/http-factory-implementation: *
• psr/http-message: ^1.0 || ^2.0
• psr/http-message-implementation: *

Requires (Dev)

• ext-json: *
• friendsofphp/php-cs-fixer: ^3
• guzzlehttp/psr7: ^2.7
• phpstan/phpstan: ^1 || ^2
• phpunit/phpunit: ^7 || ^8 || ^9

Suggests

• guzzlehttp/psr7: Guzzle's PSR-7 and PSR-17 implementation
• laminas/laminas-diactoros: Laminas' PSR-7 and PSR-17 implementation
• nyholm/psr7: A Lightweight PSR-7 and PSR-17 implementation
• sunrise/http-message: Sunrise's PSR-7, PSR-17 and RFC-7230 implementation

MIT

• client
• sockets
• unit
• functional
• tests
• fastcgi
• integration
• testcase
• psr7
• psr17
• phpfpm
• endtoend

README

A modern, fully compliant FastCGI client for PHP that allows sending PSR-7 HTTP requests directly to FastCGI applications like PHP-FPM. The library supports request multiplexing, provides a Promise-based API using Guzzle Promises, and automatically converts FastCGI responses into PSR-7 responses.

🚩 Requirements

• PHP >= 7.2
• PSR-7 - HTTP mesage implementation
• PSR-17 - HTTP message factory implementation

🧑‍🔧 Installation

In order for this package to work, you need to install a PSR-7 and PSR-17 implementation. You can install guzzlehttp/psr7, which is used by this lib for development purposes:

composer require guzzlehttp/psr7

The package itself is installable and autoloadable via Composer as filisko/fastcgi-client.

composer require filisko/fastcgi-client

🎯 Use Cases

• Talk directly to PHP-FPM without an HTTP server (e.g., from a custom gateway).
• Benchmark or test PHP-FPM pools under load.
• Run end-to-end tests with PHPUnit in a much faster way (no HTTP yet still PSR-7 responses).

📖 Story

This library came out of the need to perform end-to-end tests in the fastest possible way. My main goal was to get outside the app in order to make assertions.

We could say it fills the gap between browser-based testing tools like Selenium (very slow) and Symfony's KernelTestCase, which doesn't go outside the app, although it's at the very edge (very fast).

By communicating directly with PHP's FastCGI interface via socket connections, it provides true end-to-end feedback with exceptional performance, which allows developers to test their applications from the outside while maintaining the speed needed for efficient test-driven development and go through the full request life cycle; request starts and ends, different than interacting with the App multiple times within the same process and sharing memory.

The implementation leverages modern tools like Guzzle Promises for asynchronous processing and standardised PSR-7 responses for seamless integration with your existing knowledge.

Additionally, the documentation in the code is outstanding! It serves both as a guide for developers interested in improving this library and also as an educational resource for those wanting to learn how the FastCGI protocol works. Furthermore, the documentation helps turn the hard-to-understand code of a low-level protocol implementation into something understandable and maintainable.

👨‍💻 Usage

TODO

📃 License and Contribution

Please see CHANGELOG for more information about recent changes and CONTRIBUTING for contributing details.

The MIT License (MIT). Please see LICENSE for more information.