[Suggestion] HTTP related features (similar to nock in JS)

[MatanYadaev]

TL;DR

A new HTTP server mocking plugin, similar to nock in JavaScript, with the following features:

1. Disable/enable outgoing HTTP requests (reference in nock)
2. Option to mock HTTP responses (reference in nock) - built-in in Laravel, but only for Laravel's Http facade
3. Option to record HTTP requests (reference in nock)

Motivation

1. Most tests should not make outgoing HTTP requests, and when they do, you want to control it. Sometimes tests make unwanted HTTP requests, but you miss them because of the size of the project, or because a third-party package executed them without you knowing.
2. Mocking HTTP responses allows you to make integration tests easier, without mocking classes and methods, even when using third-party SDKs/packages. (think of testing PaymentService that uses Stripe SDK, for instance)
3. Recording responses makes mocking HTTP responses easier. You execute the request once, it's stored in the project, and in the next times it'll use this recorded request. You don't need to write the response manually, or to execute the request manually, or to have the mocked responses in your test code.

Examples

Disable/enable outgoing HTTP requests

describe('file_get_contents', function () {
    test('disable network', function () {
        network()->disable();

        expect(function () {
            file_get_contents('https://pestphp.com');
        })->toThrow("Access to 'pestphp.com' is denied.");

        network()->enable();
    });

    test('enable network', function () {
        network()->disable()->enable();

        expect(file_get_contents('https://pestphp.com'))->toBeString();
    });

    test('enable network to specific URLs', function () {
        network()->disable()->enable(['pestphp.com']);

        expect(file_get_contents('https://pestphp.com'))->toBeString();
        expect(function () {
            file_get_contents('https://google.com');
        })->toThrow("Access to 'google.com' is denied.");

        network()->enable();
    });
});

Or for stricter projects:

// In `tests/Pest.php`

uses()->beforeEach(function () {
    network()->disable();
})->in('*');

Mock HTTP requests

// @TODO

Record HTTP requests

// @TODO

How it can be done

Disable/enable HTTP requests

I already created a POC locally with Patchwork, a monkey patching package for PHP:

<?php

declare(strict_types=1);

namespace Pest;

use Exception;
use Patchwork\CallRerouting\Handle;

use function Patchwork\redefine;
use function Patchwork\relay;
use function Patchwork\restore;

/**
 * @internal
 */
final class Network
{
    private static ?self $instance = null;

    private static bool $disabled = false;

    /**
     * @var array<string>
     */
    private static array $enabledHosts = [];

    private static ?Handle $curlExecHandle = null;

    private static ?Handle $fileGetContentsHandle = null;

    private static ?Handle $fopenHandle = null;

    private function __construct()
    {
        //
    }

    public static function make(): self
    {
        return self::$instance ??= new self();
    }

    public function disable(): Network
    {
        self::$disabled = true;
        self::$enabledHosts = [];

        $this->applyMonkeyPatching();

        return $this;
    }

    /**
     * @param array<string>|null $hosts
     */
    public function enable(?array $hosts = null): Network
    {
        if ($hosts === null) {
            self::$disabled = false;
            self::$enabledHosts = [];
        } else {
            self::$enabledHosts = $hosts;
        }

        $this->applyMonkeyPatching();

        return $this;
    }

    private function resetMonkeyPatching(): void
    {
        $handles = [
            self::$curlExecHandle,
            self::$fileGetContentsHandle,
            self::$fopenHandle,
        ];

        foreach ($handles as $handle) {
            if ($handle !== null) {
                restore($handle);
            }
        }
    }

    private function validateUrl(string $url): void {
        $parsedUrl = parse_url($url);

        $host = $parsedUrl['host'] ?? $parsedUrl['path'];

        if (!in_array($host, self::$enabledHosts, true)) {
            throw new Exception("Access to '{$host}' is denied.");
        }
    }

    private function applyMonkeyPatching(): void
    {
        $this->resetMonkeyPatching();

        if (!self::$disabled) {
            return;
        }

        self::$curlExecHandle = redefine('curl_exec', function ($ch) {
            $url = curl_getinfo($ch, CURLINFO_EFFECTIVE_URL);

            $this->validateUrl($url);

            return relay();
        });

        self::$fileGetContentsHandle = redefine('file_get_contents', function ($url) {
            $this->validateUrl($url);

            return relay();
        });

        self::$fopenHandle = redefine('fopen', function ($filename) {
            $parsedUrl = parse_url($filename);

            if (!isset($parsedUrl['scheme'])) {
                return relay();
            }

            $scheme = strtolower($parsedUrl['scheme']);

            if (!in_array($scheme, ['http', 'https'], true)) {
                return relay();
            }

            $this->validateUrl($filename);

            return relay();
        });
    }
}

@nunomaduro Would you accept adding such a plugin to the PestPHP organization?