Skip to content

Latest commit

 

History

History
341 lines (222 loc) · 10.1 KB

README.md

File metadata and controls

341 lines (222 loc) · 10.1 KB
Raw

Build Status Tested PHP versions Latest Stable Version Total Downloads Coverage Status

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 in my related blog posts:

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.1-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\Requests\PostRequest;
use hollodotme\FastCGI\SocketConnections\UnixDomainSocket;

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

$request = new PostRequest('/path/to/target/script.php', $content);

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

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\Requests\PostRequest;
use hollodotme\FastCGI\SocketConnections\NetworkSocket;

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

$request = new PostRequest('/path/to/target/script.php', $content);

$requestId = $client->sendAsyncRequest($request);

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\Requests\PostRequest;
use hollodotme\FastCGI\SocketConnections\NetworkSocket;

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

$request = new PostRequest('/path/to/target/script.php', $content);

$requestId = $client->sendAsyncRequest($request);

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
);

Requests

As of version 1.1.0 (PHP 7.0) and 2.1.0 (PHP 7.1), request are defined by the following interface:

<?php declare(strict_types=1);

namespace hollodotme\FastCGI\Interfaces;

interface ProvidesRequestData
{
	public function getGatewayInterface() : string;

	public function getRequestMethod() : string;

	public function getScriptFilename() : string;

	public function getServerSoftware() : string;

	public function getRemoteAddress() : string;

	public function getRemotePort() : int;

	public function getServerAddress() : string;

	public function getServerPort() : int;

	public function getServerName() : string;

	public function getServerProtocol() : string;

	public function getContentType() : string;

	public function getContentLength() : int;

	public function getContent() : string;

	public function getCustomVars() : array;

	public function getParams() : array;
}

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

  • hollodotme\FastCGI\Requests\GetRequest
  • hollodotme\FastCGI\Requests\PostRequest
  • hollodotme\FastCGI\Requests\PutRequest
  • hollodotme\FastCGI\Requests\PatchRequest
  • hollodotme\FastCGI\Requests\DeleteRequest

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
CUSTOM_VARS empty array You can use the methods setCustomVar, addCustomVars to add own key-value pairs

Responses

As of version 1.1.0 (PHP 7.0) and 2.1.0 (PHP 7.1), responses are defined by the following interface:

<?php declare(strict_types=1);

namespace hollodotme\FastCGI\Interfaces;

interface ProvidesResponseData
{
	public function getRequestId() : int;

	public function getHeaders() : array;

	public function getHeader( string $headerKey ) : string;

	public function getBody() : string;

	public function getRawResponse() : string;

	public function getDuration() : float;
}

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

<?php declare(strict_types=1);

echo "Hello World";

The raw 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 raw response would look like this:

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

Hello World

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

# Get the request ID
echo $response->getRequestId(); # random int set by client

# Get a single response header
echo $response->getHeader('X-Custom'); # 'Header'

# Get all headers
print_r($response->getHeaders());
/*
Array (
	[X-Custom] => Header
	[Content-type] => text/html; charset=UTF-8
)
*/

# Get the body
echo $response->getBody(); # 'Hello World'

# Get the raw response
echo $response->getRawResponse();
/*
X-Custom: Header
Content-type: text/html; charset=UTF-8

Hello World
*/

# Get the duration
echo $response->getDuration(); # e.g. 0.0016319751739502

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