README.md

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 PHP 7.0/PHP 7.1 and extended with unit tests.

You can find an experimental use-case on my related blog post: Experimental async PHP vol. 1

---

Installation

Use version 1.x for compatibility with PHP 7.0.x

composer require hollodotme/fast-cgi-client:^1.0

Use version 2.x for compatibility with PHP 7.1.x

composer require hollodotme/fast-cgi-client:^2.0

---

Usage

Init client with a unix domain socket connection

<?php declare(strict_types=1);

namespace YourVendor\YourProject;

require( 'vendor/autoload.php' );

use hollodotme\FastCGI\Client;
use hollodotme\FastCGI\SocketConnections\UnixDomainSocket;

$connection = new UnixDomainSocket(
	'unix:///var/run/php/php7.0-fpm.sock',  # Socket path to php-fpm
	5000,                                   # Connect timeout in milliseconds (default: 5000)
	5000,                                   # Read/write timeout in milliseconds (default: 5000)
	false,                                  # Make socket connection persistent (default: false)
	false                                   # Keep socket connection alive (default: false) 
);

$client = new Client( $connection );

Init client with a network socket connection

<?php declare(strict_types=1);

namespace YourVendor\YourProject;

require( 'vendor/autoload.php' );

use hollodotme\FastCGI\Client;
use hollodotme\FastCGI\SocketConnections\NetworkSocket;

$connection = new NetworkSocket(
	'127.0.0.1',    # Hostname
	9000,           # Port
	5000,           # Connect timeout in milliseconds (default: 5000)
	5000,           # Read/write timeout in milliseconds (default: 5000)
	false,          # Make socket connection persistent (default: false)
	false           # Keep socket connection alive (default: false) 
);

$client = new Client( $connection );

Send request synchronously

<?php declare(strict_types=1);

namespace YourVendor\YourProject;

require( 'vendor/autoload.php' );

use hollodotme\FastCGI\Client;
use hollodotme\FastCGI\SocketConnections\UnixDomainSocket;

$client  = new Client( new UnixDomainSocket( 'unix:///var/run/php/php7.0-fpm.sock' ) );
$content = http_build_query( ['key' => 'value'] );

$response = $client->sendRequest(
	[
		'GATEWAY_INTERFACE' => 'FastCGI/1.0',
		'REQUEST_METHOD'    => 'POST',
		'SCRIPT_FILENAME'   => '/path/to/target/script.php',
		'SERVER_SOFTWARE'   => 'hollodotme/fast-cgi-client',
		'REMOTE_ADDR'       => '127.0.0.1',
		'REMOTE_PORT'       => '9985',
		'SERVER_ADDR'       => '127.0.0.1',
		'SERVER_PORT'       => '80',
		'SERVER_NAME'       => 'your-server',
		'SERVER_PROTOCOL'   => 'HTTP/1.1',
		'CONTENT_TYPE'      => 'application/x-www-form-urlencoded',
		'CONTENT_LENGTH'    => strlen( $content )	
	],
	$content
);

print_r( $response );

Send request asynchronously

<?php declare(strict_types=1);

namespace YourVendor\YourProject;

require( 'vendor/autoload.php' );

use hollodotme\FastCGI\Client;
use hollodotme\FastCGI\SocketConnections\NetworkSocket;

$client  = new Client( new NetworkSocket( '127.0.0.1', 9000 ) );
$content = http_build_query( ['key' => 'value'] );

$requestId = $client->sendAsyncRequest(
	[
		'GATEWAY_INTERFACE' => 'FastCGI/1.0',
		'REQUEST_METHOD'    => 'POST',
		'SCRIPT_FILENAME'   => '/path/to/target/script.php',
		'SERVER_SOFTWARE'   => 'hollodotme/fast-cgi-client',
		'REMOTE_ADDR'       => '127.0.0.1',
		'REMOTE_PORT'       => '9985',
		'SERVER_ADDR'       => '127.0.0.1',
		'SERVER_PORT'       => '80',
		'SERVER_NAME'       => 'your-server',
		'SERVER_PROTOCOL'   => 'HTTP/1.1',
		'CONTENT_TYPE'      => 'application/x-www-form-urlencoded',
		'CONTENT_LENGTH'    => strlen( $content )	
	],
	$content
);

echo "Request sent, got ID: {$requestId}";

Optionally wait for a response, after sending the async request

<?php declare(strict_types=1);

namespace YourVendor\YourProject;

require( 'vendor/autoload.php' );

use hollodotme\FastCGI\Client;
use hollodotme\FastCGI\SocketConnections\NetworkSocket;

$client  = new Client( new NetworkSocket( '127.0.0.1', 9000 ) );
$content = http_build_query( ['key' => 'value'] );

$requestId = $client->sendAsyncRequest(
	[
		'GATEWAY_INTERFACE' => 'FastCGI/1.0',
		'REQUEST_METHOD'    => 'POST',
		'SCRIPT_FILENAME'   => '/path/to/target/script.php',
		'SERVER_SOFTWARE'   => 'hollodotme/fast-cgi-client',
		'REMOTE_ADDR'       => '127.0.0.1',
		'REMOTE_PORT'       => '9985',
		'SERVER_ADDR'       => '127.0.0.1',
		'SERVER_PORT'       => '80',
		'SERVER_NAME'       => 'your-server',
		'SERVER_PROTOCOL'   => 'HTTP/1.1',
		'CONTENT_TYPE'      => 'application/x-www-form-urlencoded',
		'CONTENT_LENGTH'    => strlen( $content )	
	],
	$content
);

echo "Request sent, got ID: {$requestId}";

$response = $client->waitForResponse( 
	$requestId,     # The request ID 
	3000            # Optional timeout to wait for response,
					# defaults to read/write timeout in milliseconds set in connection
);

Responses

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

<?php declare(strict_types=1);

echo "Hello World";

The response would look like this:

Content-type: text/html; charset=UTF-8

Hello World

Please note:

• All headers sent by your script will precede the response body
• There won't be any HTTP specific headers like HTTP/1.1 200 OK, because there is no webserver involved.

Custom headers will also be part of the response:

<?php declare(strict_types=1);

header('X-Custom: Header');

echo "Hello World";

The response would look like this:

X-Custom: Header
Content-type: text/html; charset=UTF-8

Hello World

---

Command line tool (for debugging only)

Run a call through a network socket:

bin/fcgiget localhost:9000/status

Run a call through a Unix Domain Socket

bin/fcgiget unix:/var/run/php/php7.0-fpm.sock/status