README

Serverless HTTP client - make requests to PHP scripts on the CLI.

This library lets you make HTTP requests to PHP applications without running a web server. Instead of Apache or nginx, it executes your PHP scripts directly via the command line while emulating the full HTTP environment ($_GET, $_POST, $_SERVER, $_SESSION, headers, cookies, etc.).

Perfect for testing, CI pipelines, unreleased deployment or any scenario where spinning up a web server is overkill or not possible.

Installation

composer require n5s/http-cli

Usage

use n5s\HttpCli\Client;
use n5s\HttpCli\RequestOptions;

$client = new Client('/path/to/your/app');

// Simple GET request
$response = $client->request('GET', 'https://example.com/api/users');
echo $response->getContent();

// POST with JSON
$response = $client->request('POST', '/api/users',
    RequestOptions::create()
        ->json(['name' => 'John', 'email' => 'john@example.com'])
        ->build()
);

// POST with form data
$response = $client->request('POST', '/login',
    RequestOptions::create()
        ->formParams(['username' => 'admin', 'password' => 'secret'])
        ->build()
);

How It Works

When you make a request, the library:

1. Spawns a PHP CLI process targeting your script
2. Injects a bootstrap that populates $_GET, $_POST, $_SERVER, $_COOKIE, and $_SESSION
3. Provides polyfills for specific HTTP context functions: header(), headers_sent(), http_response_code(), etc.
4. Captures the output and headers, returning a Response object

Your PHP scripts run exactly as they would under a web server, but without one.

Framework Adapters

Use your favorite HTTP client library - just swap in our handler.

Guzzle

composer require guzzlehttp/guzzle

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use n5s\HttpCli\Guzzle\CliHandler;
use n5s\HttpCli\Client;

$cliClient = new Client('/path/to/your/app');
$handler = new CliHandler($cliClient);

$client = new Client([
    'handler' => HandlerStack::create($handler),
]);

// Use Guzzle as normal
$response = $client->get('/api/users');
$response = $client->post('/api/users', [
    'json' => ['name' => 'John'],
]);

Symfony HttpClient

composer require symfony/http-client

use n5s\HttpCli\Symfony\CliClient;
use n5s\HttpCli\Client;

$cliClient = new Client('/path/to/your/app');
$client = new CliClient($cliClient);

// Use Symfony HttpClient as normal
$response = $client->request('GET', '/api/users');
$data = $response->toArray();

WordPress Requests

composer require rmccue/requests

use WpOrg\Requests\Requests;
use n5s\HttpCli\WordPress\Cli;
use n5s\HttpCli\Client;

$cliClient = new Client('/path/to/your/app');

Requests::set_transport([Cli::class]);
Cli::setClient($cliClient);

// Use WordPress Requests as normal
$response = Requests::get('/api/users');

Request Options

Build requests with a fluent API:

use n5s\HttpCli\RequestOptions;

$options = RequestOptions::create()
    // Body
    ->json(['key' => 'value'])           // JSON payload
    ->formParams(['field' => 'value'])   // Form data (application/x-www-form-urlencoded)
    ->body('raw content')                // Raw body
    ->multipart([                        // Multipart form data
        ['name' => 'file', 'contents' => 'data', 'filename' => 'test.txt'],
    ])

    // Headers & Auth
    ->headers(['X-Custom' => 'value'])
    ->basicAuth('user', 'pass')
    ->bearerToken('token')
    ->cookies(['session' => 'abc123'])

    // Other
    ->query(['page' => 1, 'limit' => 10])
    ->timeout(30.0)
    ->build();

$response = $client->request('POST', '/api/endpoint', $options);

Response

$response = $client->request('GET', '/api/users');

$response->getStatusCode();  // 200
$response->getHeaders();     // ['Content-Type: application/json', ...]
$response->getContent();     // Response body as string
$response->getSession();     // Session data array
$response->getProcess();     // Symfony Process instance (for debugging)

Configuration

$client = new Client(
    documentRoot: '/path/to/your/app',   // Required: your app's root directory
    file: 'index.php',                   // Entry point (default: index.php)
    globalsHandler: null,                // GlobalsHandler to customize superglobals
    phpExecutable: null,                 // PHP binary path (auto-detected)
);

Globals Handler

By default, the child PHP process receives a clean set of superglobals built from the HTTP request only. If your application depends on environment variables from the parent process (e.g. APP_ENV, DATABASE_URL), you can use the built-in InheritEnvGlobalsHandler:

use n5s\HttpCli\Client;
use n5s\HttpCli\InheritEnvGlobalsHandler;

$client = new Client(
    documentRoot: '/path/to/your/app',
    globalsHandler: new InheritEnvGlobalsHandler(),
);

This merges the parent's $_SERVER and $_ENV into the child process. Request-specific variables take precedence over inherited ones.

You can also implement the GlobalsHandler interface to customize superglobals however you need:

use n5s\HttpCli\GlobalsHandler;

final class MyGlobalsHandler implements GlobalsHandler
{
    public function handle(array &$globals): void
    {
        $globals['_SERVER']['APP_ENV'] = 'testing';
        $globals['_ENV']['CUSTOM_VAR'] = 'value';
    }
}

Adapter Options Support

Guzzle

Symfony HttpClient

WordPress Requests

Limitations

Running PHP scripts via CLI instead of a web server comes with inherent limitations:

Not Supported

Behavioral Differences

• Performance: Process spawning overhead, but no DNS resolution, TCP/SSL handshake, or network latency
• $_SERVER values: Some values like SERVER_SOFTWARE will differ from Apache/nginx
• File uploads: Multipart parts are written to temp files and populated in $_FILES
• Session handling: Works but uses an in-memory handler, not file-based persistence
• php://input: Custom stream wrapper provides the request body

License

MIT