Building an HTTP Status Code Reference CLI in PHP — No Dependencies Required

A zero-dependency PHP 8.2 CLI that gives you instant HTTP status code details, RFC references, and common causes without leaving your terminal.

I look up HTTP status codes more often than I care to admit. Not the obvious ones — everyone knows 404 and 500. But when a reverse proxy starts returning 502s, or a client integration breaks with a 412, I end up in the same loop: open browser, search "HTTP 412", click through to the RFC, skim for the paragraph that actually explains when this happens in practice.

So I built http-status — a terminal-native reference tool that gives me everything I need about any HTTP status code in one command. No browser. No dependencies. Just PHP 8.2 and a data file that knows about 60+ status codes, their RFC sources, and the real-world situations that produce them.

📦 GitHub: https://github.com/sen-ltd/http-status

Why a CLI reference tool?

HTTP status codes are one of those things that sit in an awkward middle ground. You know the concept, but the specifics slip. What's the difference between 401 and 403? When should an API return 409 vs 422? Is 418 actually standardized?

Browser-based references work, but they break your flow. You're in the terminal debugging a failing request, you see a status code you need to look up, and now you're context-switching to a browser tab. A CLI tool keeps you where you already are.

The tool needed four things:

1. Instant lookup — http-status 404 shows name, description, RFC, and common causes
2. Browsing — list all codes, filter by class (1xx through 5xx)
3. Search — find codes by keyword when you don't know the number
4. Machine output — JSON mode for scripting and piping

Architecture

The project has five source files that each do one thing:

src/
├── StatusCode.php    # Value object: code, name, description, rfc, causes
├── Registry.php      # Complete HTTP status code database
├── Search.php        # Fuzzy keyword matching
├── Formatter.php     # Terminal table and JSON output
├── Cli.php           # Argument parsing and command routing
└── Bootstrap.php     # PSR-4 autoloader (no Composer at runtime)

The StatusCode value object

Every status code is a readonly value object with typed properties:

final readonly class StatusCode
{
    public function __construct(
        public int $code,
        public string $name,
        public string $description,
        public string $rfc,
        public string $category,
        public array $commonCauses = [],
    ) {}

    public function className(): string
    {
        return match (true) {
            $this->code >= 100 && $this->code < 200 => '1xx Informational',
            $this->code >= 200 && $this->code < 300 => '2xx Success',
            // ...
        };
    }
}

PHP 8.2's readonly classes are perfect for this kind of data. Once created, a status code is immutable — there's no reason to modify it, and the type system enforces that.

The Registry

The Registry is where the actual knowledge lives. It's a hand-curated database of 60+ HTTP status codes, each with metadata that goes beyond what you get from a quick search:

$this->add(
    409,
    'Conflict',
    'The request conflicts with the current state of the target resource.',
    'RFC 9110 §15.5.10',
    'Client Error',
    ['Concurrent edit conflict', 'Duplicate resource creation', 'Optimistic locking failure'],
);

The common causes field is what makes this tool actually useful compared to reading the RFC. The RFC tells you what 409 means. The common causes tell you why you're seeing it. When you're debugging a failing API integration and get a 409, knowing that it's often caused by optimistic locking failures or duplicate creation attempts is immediately actionable.

The registry covers all standard codes defined in RFC 9110 (the 2022 update to the core HTTP semantics), plus relevant codes from RFC 6585 (additional status codes), RFC 4918 (WebDAV), RFC 7725 (legal), and RFC 8470 (early data). I deliberately skipped unofficial codes like 499 (Nginx) or 520-527 (Cloudflare) to keep the data authoritative.

Fuzzy search

The search implementation is simple and effective: split the query into words, score each status code based on matches across its name, description, category, and common causes, then rank by score:

public function search(string $query): array
{
    $query = mb_strtolower(trim($query));
    $words = preg_split('/\s+/', $query);

    $results = [];
    foreach ($this->registry->all() as $code) {
        $score = $this->score($code, $words);
        if ($score > 0) {
            $results[] = ['code' => $code, 'score' => $score];
        }
    }

    usort($results, static fn(array $a, array $b) =>
        $b['score'] <=> $a['score']
    );

    return array_map(static fn(array $r) => $r['code'], $results);
}

The scoring weights name matches higher than description matches, which produces intuitive results. Searching for "not found" puts 404 at the top. Searching for "timeout" returns both 408 (Request Timeout) and 504 (Gateway Timeout), because both have "timeout" in their names and causes.

I considered using Levenshtein distance for true fuzzy matching, but in practice, substring matching with weighted scoring works better for this use case. When someone searches for "auth", they want authentication-related codes, not a fuzzy match on "authorization" that happens to be edit-distance-close to an unrelated word.

Terminal formatting

The formatter handles two output modes: human-readable terminal output and JSON. The terminal output uses ANSI colors to visually distinguish status code classes:

private function colorByClass(string $text, StatusCode $code): string
{
    return match ($code->classPrefix()) {
        '1xx' => "\033[36m{$text}\033[0m",   // cyan
        '2xx' => "\033[32m{$text}\033[0m",   // green
        '3xx' => "\033[33m{$text}\033[0m",   // yellow
        '4xx' => "\033[31m{$text}\033[0m",   // red
        '5xx' => "\033[35m{$text}\033[0m",   // magenta
        default => $text,
    };
}

The color scheme is deliberate: green for success, red for client errors, magenta for server errors. It follows the pattern most developers already associate with these ranges. Colors are automatically disabled when piping output or when the NO_COLOR environment variable is set, following the no-color.org convention.

CLI argument parsing

The CLI module does its own argument parsing without a framework. For a tool with only four commands and one modifier flag, pulling in a dependency like symfony/console would be absurd:

public function run(array $argv): int
{
    // Extract --json flag from anywhere in the args
    $jsonMode = false;
    $remaining = [];
    foreach ($args as $arg) {
        if ($arg === '--json') {
            $jsonMode = true;
        } else {
            $remaining[] = $arg;
        }
    }

    // Route to handler
    $command = $remaining[0];
    return match ($command) {
        '--list' => $this->handleList($jsonMode),
        '--class' => $this->handleClass($remaining[1], $jsonMode),
        '--search' => $this->handleSearch(...),
        default => is_numeric($command)
            ? $this->handleLookup((int) $command, $jsonMode)
            : self::EXIT_USAGE,
    };
}

The --json flag works as a modifier that can appear anywhere in the argument list. This means http-status --json 404 and http-status 404 --json both work — a small detail that makes the tool feel polished.

Exit codes follow Unix convention: 0 for success, 1 for "not found" (the query was valid but produced no results), and 2 for usage errors (invalid arguments). This lets you use the tool in shell scripts:

if http-status 418 > /dev/null 2>&1; then
    echo "Code exists"
fi

The zero-dependency approach

The tool uses a manual PSR-4 autoloader instead of requiring Composer at runtime:

spl_autoload_register(static function (string $class) use ($srcDir): void {
    $prefix = 'SenLtd\\HttpStatus\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $relative = substr($class, strlen($prefix));
    $file = $srcDir . '/' . str_replace('\\', '/', $relative) . '.php';
    if (is_file($file)) {
        require_once $file;
    }
});

When Composer's autoloader is available (e.g., during development with PHPUnit), it takes precedence. When running standalone or in Docker, the bootstrap autoloader handles class loading. This means git clone && bin/http-status 404 works immediately — no composer install needed.

The Docker image reflects this simplicity:

FROM php:8.2-cli-alpine
WORKDIR /app
COPY src/ src/
COPY bin/ bin/
RUN chmod +x /app/bin/http-status \
    && adduser -D -s /bin/sh runner
USER runner
ENTRYPOINT ["/app/bin/http-status"]

Single stage. No build step. No package manager. The image ships src/ and bin/, nothing else. It runs as a non-root user because there's no reason not to, and it costs nothing.

Testing

The test suite has 38 tests covering every component:

PHPUnit 10.5 — 38 tests, 307 assertions

RegistryTest (12 tests)
  - Known code lookup, unknown code returns null
  - All codes sorted, class filtering, grouping
  - RFC coverage, edge cases (418 Teapot)

SearchTest (6 tests)
  - Search by name, description, common causes
  - Empty/no-match edge cases
  - Multi-result ranking

FormatterTest (8 tests)
  - Detail, table, grouped, JSON output
  - Empty list handling
  - JSON structure validation

CliTest (12 tests)
  - Help, version, lookup, list, class, search
  - Exit codes for all error paths
  - JSON modifier flag

Tests run in 8ms. There's nothing to mock — the registry is a pure data structure, the formatter is a pure function from data to string, and the CLI is a thin routing layer. When your architecture doesn't need mocks, it's a sign the boundaries are clean.

Interesting HTTP status codes

Building this tool gave me an excuse to read through RFC 9110 more carefully. A few codes I found worth highlighting:

418 I'm a Teapot — Not just an easter egg. It's from RFC 2324 (Hyper Text Coffee Pot Control Protocol), published as an April Fools' joke in 1998. Despite being satirical, it's been implemented in enough systems that it functions as a de facto standard for "this server intentionally refuses this request in a humorous way."

425 Too Early — Added in RFC 8470 for TLS 1.3 early data (0-RTT). When a client sends a request using early data that might be replayed, the server can reject it with 425. This is a relatively recent addition that most developers haven't encountered yet.

451 Unavailable For Legal Reasons — The number is a reference to Ray Bradbury's Fahrenheit 451. RFC 7725 introduced it in 2016 specifically for censorship and legal takedown scenarios.

207 Multi-Status — From WebDAV, but increasingly used in REST APIs for batch operations. When you need to report success/failure for multiple sub-operations in a single response, 207 is the right choice — though many teams don't know it exists.

Usage patterns

Beyond quick lookups, the tool is useful in a few workflow patterns:

Debugging proxy chains: When a 502 or 504 shows up, http-status 502 immediately reminds you that the problem is between the proxy and the upstream, not the client.

API design reviews: http-status --class 4xx gives you the full menu of client error codes to choose from. It's a quick way to verify you're using the right status code for each error case.

Documentation writing: http-status --json 201 gives you structured data you can pipe into documentation generators or API spec files.

Shell integration: Combine with curl for readable HTTP debugging:

code=$(curl -s -o /dev/null -w '%{http_code}' https://example.com)
http-status "$code"

What I'd add next

The tool is deliberately minimal — it does one thing and does it well. But there are a few additions that would stay within that scope:

• Header suggestions: Show which headers are relevant to each status code (e.g., Retry-After for 429 and 503)
• Unofficial codes: An --unofficial flag to include Nginx (499), Cloudflare (520-527), and other vendor-specific codes
• Completion scripts: Bash/Zsh completion for status code numbers

Wrapping up

This took about two hours to build. The hardest part was curating the common causes — that required actually thinking about the real-world scenarios that produce each status code, not just copying RFC text.

The zero-dependency approach keeps the tool fast and portable. Clone it, run it, Docker it — no setup required. PHP 8.2's readonly classes and match expressions make the code clean without needing a framework.

If you work with HTTP APIs, give it a try. http-status 404 is faster than opening a browser tab, and the common causes section might save you some debugging time.

http-status is open source under the MIT license. Issues and PRs welcome.