karmabunny/visor

A supervisor for PHP-CLI servers

v1.1.0 2023-08-03 04:45 UTC

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

README

This is a small utility to wrap the built-in PHP cli-server feature.

There are two three parts to this library:

1. An abstract 'server' instance that will manage the lifecycle of any cli-server compatible script.

2. An 'echo server' implementation that, uh, echos. What you say at it, it says back.

3. A 'mock server' implementation that will reply with defined responses.

Install

Using Composer:

composer require karmabunny/visor

Usage

This is ideal for creating small integration tests with a local application or creating mock servers and testing HTTP libraries.

Server Instance

use karmabunny\visor\Server;
use PHPUnit\Framework\TestCase;

/**
 * The application bootstrap is found at: 'index.php'. This must be capable
 * of accepting cli-server requests.
 */
class MyServer extends Server
{
    protected function getTargetScript(): string
    {
        return __DIR__ . '/index.php';
    }
}

class MyServerTest extends TestCase
{
    public function testThings()
    {
        // This create a server at localhost:8080
        $server = MyServer::create();

        // One can then perform tests against the application.
        $res = file_get_contents($server->getHostUrl() . '/health');
        $this->assertEquals('ok', $res);
    }
}

Echo Server

use karmabunny\visor\EchoServer;
use PHPUnit\Framework\TestCase;

class ClientTest extends TestCase
{
    public function testThings()
    {
        // This creates an echo server at localhost:8080
        $server = EchoServer::create();

        // Imagine this to be some kind of client that hits a remote
        // server of sorts.
        $res = file_get_contents($server->getHostUrl() . '/hello?test=123');

        // Not only is 'res' a JSON body of the payload, the payload is
        // also accessible from the the server instance.

        $payload = $server->getLatestPayload();

        $this->assertEquals('/hello', $payload['path']);
        $this->assertEquals(['test' => '123'], $payload['query']);
    }
}

Mock Server

use karmabunny\visor\MockServer;
use PHPUnit\Framework\TestCase;

class FakeTest extends TestCase
{
    public function testThings()
    {
        // This creates a mock server at localhost:8080
        $server = MockServer::create();

        $server->setMock('/mock-this', [], 'a fake response');
        $res = file_get_contents($server->getHostUrl() . '/mock-this');

        $payload = $server->getLatestPayload();

        $this->assertEquals('/mock-this', $payload['path']);
        $this->assertEquals('a fake response', $res);
    }
}

Config

name	-	default
host	a binding address	localhost
port	HTTP port number	8080
wait	pause until the server is ready (milliseconds)	100
path	working directory of the server	-

By default the log file path is randomised in a temporary system directory.

Log files

The server emit a log file to aid testing and debugging.

This includes logs from the server process, the application, and visor itself.

Server that extend the base class can use Server::log(). Applications can use the native error_log().

Mock + Echo Server

The included implementations will log additional data also.

• latest.json is the request payload stored for introspection. Used by getLastPayload().
• mocks.json is a store of response objects for the mock server.

Echo (+ Mock) payloads

Both Mock and Echo servers store the request object in a specific format.

Note that the body is unchanged, if you've sent a JSON or URL payload this will be 'as is' in it's encoded string form.

• path - the request path, without the query string
• query - an key-value array, from parse_str()
• method - always uppercase
• headers - key-value pairs, keys are lowercase
• body - string body, from php://input

The JSON-encoded log file looks like this:

{
    "path": "/hello-world.json",
    "query": {
        "rando1": "7bb1166f0cf451cc3eb4cbb977ad932f674aac6c"
    },
    "method": "POST",
    "headers": {
        "host": "localhost:8080",
        "connection": "close",
        "content-length": "53",
        "content-type": "application/json"
    },
    "body": "{\"rando2\":\"267f3bf70d8939c2c7e77d1f8ea164e1df071bba\"}"
}