Download the PHP package hollodotme/fast-cgi-client without Composer

On this page you can find all versions of the php package hollodotme/fast-cgi-client. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

Please rate this library. Is it a good library?

All versions of fast-cgi-client with dependencies

Informations about the package fast-cgi-client

FastCGI Client CI PHP 7.1 - 8.0 Latest Stable Version Total Downloads codecov

Fast CGI Client

A PHP fast CGI client to send requests (a)synchronously to PHP-FPM using the FastCGI Protocol.

This 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 unit and integration tests as well.


This is the documentation of the latest release.

Please have a look at the backwards incompatible changes (BC breaks) in the changelog.

Please see the following links for earlier releases:

Read more about the journey to and changes in v2.6.0 in this blog post.


You can find an experimental use-case in my related blog posts:

You can also find slides of my talks about this project on speakerdeck.com.


Installation


Usage - connections

This library supports two types of connecting to a FastCGI server:

  1. Via network socket
  2. Via unix domain socket

Create a network socket connection

Create a unix domain socket connection

Usage - single request

The following examples assume that the content of /path/to/target/script.php looks like this:

Send request synchronously

Send request asynchronously (Fire and forget)

Read the response, after sending the async request

Notify a callback when async request responded

You can register response and failure callbacks for each request. In order to notify the callbacks when a response was received instead of returning it, you need to use the waitForResponse(int $socketId, ?int $timeoutMs = null) method.


Usage - multiple requests

Sending multiple requests and reading their responses (order preserved)

Sending multiple requests and reading their responses (reactive)

Sending multiple requests and notifying callbacks (reactive)

Reading output buffer from worker script using pass through callbacks

It may be useful to see the progression of a requested script by having access to the flushed output of that script. The php.ini default output buffering for php-fpm is 4096 bytes and is (hard-coded) disabled for CLI mode. (See documentation) Calling ob_implicit_flush() causes every call to echo or print to immediately be flushed.

The callee script could look like this:

The caller than could look like this:


Requests

Requests are defined by the following interface:

Alongside with this interface, this package provides an abstract request class, containing default values to make the API more handy for you and 5 request method implementations of this abstract class:

So you can either implement the interface, inherit from the abstract class or simply use one of the 5 implementations.

Default values

The abstract request class defines several default values which you can optionally overwrite:

Key Default value Comment
GATEWAY_INTERFACE FastCGI/1.0 Cannot be overwritten, because this is the only supported version of the client.
SERVER_SOFTWARE hollodotme/fast-cgi-client
REMOTE_ADDR 192.168.0.1
REMOTE_PORT 9985
SERVER_ADDR 127.0.0.1
SERVER_PORT 80
SERVER_NAME localhost
SERVER_PROTOCOL HTTP/1.1 You can use the public class constants in hollodotme\FastCGI\Constants\ServerProtocol
CONTENT_TYPE application/x-www-form-urlencoded
REQUEST_URI
CUSTOM_VARS empty array You can use the methods setCustomVar, addCustomVars to add own key-value pairs

Request contents

In order to make the composition of different request content types easier there are classes covering the typical content types:

You can create your own request content type composer by implementing the following interface:

ComposesRequestContent

Request content example: URL encoded form data (application/x-www-form-urlencoded)

This example produces the following $_POST array at the target script:

Request content example: multipart form data (multipart/form-data)

Multipart form-data can be used to transfer any binary data as files to the target script just like a file upload in a browser does.

PLEASE NOTE: Multipart form-data content type works with POST requests only.

This example produces the following $_POST and $_FILES array at the target script:

Request content example: JSON encoded data (application/json)

This example produces the following content for php://input at the target script:

Responses

Responses are defined by the following interface:

Assuming /path/to/target/script.php has the following content:

The raw response would look like this:

Please note:

Custom headers will also be part of the response:

The raw response would look like this:

You can retrieve all of the response data separately from the response object:


Trouble shooting

"File not found." response (php-fpm)

This response is generated by php-fpm for the preceding error Primary script unknown in case the requested script does not exists or there are path traversals in its path like /var/www/../run/script.php.

Although the given path may exist and would resolve to an absolute path in the file system, php-fpm does not do any path resolution and accepts only absolute paths to the script you want to execute.

Programatically you can handle this error like this:


Prepare local development environment

This requires docker and docker-compose installed on your machine.

make update

Run examples

make examples

Run all tests

make tests

Command line tool (for local debugging only)

Please note: bin/fcgiget is not included and linked to vendor/bin via composer anymore since version v3.1.2for security reasons. Read more.

Run a call through a network socket:

docker-compose exec php74 php bin/fcgiget localhost:9001/status

Run a call through a Unix Domain Socket

docker-compose exec php74 php bin/fcgiget unix:///var/run/php-uds.sock/status

This shows the response of the php-fpm status page.


Version
Requires php Version >=7.1
ext-json Version *

The package hollodotme/fast-cgi-client contains the following files

Loading the files please wait ....