PHPackages                             karmabunny/visor - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. karmabunny/visor

ActiveLibrary[CLI & Console](/categories/cli)

karmabunny/visor
================

A supervisor for PHP-CLI servers

v2.2.5(5mo ago)01.2k↓43.8%1[1 PRs](https://github.com/Karmabunny/visor/pulls)2MITPHPCI passing

Since Jan 30Pushed 5mo ago4 watchersCompare

[ Source](https://github.com/Karmabunny/visor)[ Packagist](https://packagist.org/packages/karmabunny/visor)[ RSS](/packages/karmabunny-visor/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (5)Versions (10)Used By (2)

Visor
=====

[](#visor)

This is a small utility to wrap the built-in PHP [cli-server](https://www.php.net/manual/en/features.commandline.webserver.php) 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
-------

[](#install)

Using Composer:

```
composer require karmabunny/visor

```

Usage
-----

[](#usage)

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

### Server Instance

[](#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

[](#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

[](#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
------

[](#config)

name-defaulthosta binding addresslocalhostportHTTP port number8080waitpause until the server is ready (milliseconds)100pathworking directory of the server-By default the log file path is randomised in a temporary system directory.

Log files
---------

[](#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

[](#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
----------------------

[](#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\"}"
}
```

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance70

Regular maintenance activity

Popularity20

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~129 days

Recently: every ~0 days

Total

9

Last Release

176d ago

Major Versions

v1.1.0 → v2.1.02025-11-24

### Community

Maintainers

![](https://www.gravatar.com/avatar/11b33084210490439a6fb2c0b277e0bf39f8d0e368f20bebb703834003a617df?d=identicon)[karmabunny](/maintainers/karmabunny)

---

Top Contributors

[![gwillz](https://avatars.githubusercontent.com/u/3466850?v=4)](https://github.com/gwillz "gwillz (64 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/karmabunny-visor/health.svg)

```
[![Health](https://phpackages.com/badges/karmabunny-visor/health.svg)](https://phpackages.com/packages/karmabunny-visor)
```

###  Alternatives

[wp-cli/wp-cli

WP-CLI framework

5.1k17.2M320](/packages/wp-cli-wp-cli)[consolidation/annotated-command

Initialize Symfony Console commands from annotated command class methods.

22569.8M19](/packages/consolidation-annotated-command)[seld/cli-prompt

Allows you to prompt for user input on the command line, and optionally hide the characters they type

24725.8M17](/packages/seld-cli-prompt)[buggregator/trap

A simple and powerful tool for debugging PHP applications.

2591.7M40](/packages/buggregator-trap)[illuminate/console

The Illuminate Console package.

12944.1M5.1k](/packages/illuminate-console)[php-tui/php-tui

Comprehensive TUI library heavily influenced by Ratatui

589747.0k6](/packages/php-tui-php-tui)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)