README

Object-oriented wrapper for handling HTTP requests in PHP.

Small footprint, enumerated status codes and reason phrases to help developers avoid magic strings.

Installation

composer require simplemehanizm/http

Usage

Request Class

The standard Request class wraps PHP superglobals in an object-oriented interface:

use SimpleMehanizm\Http\Request;

$request = Request::fromSuperglobals();

// HTTP method
$request->method();           // "POST"
$request->isMethod('post');   // true (case-insensitive)

// URI and path
$request->uri();              // "/users/123?include=profile"
$request->path();             // "/users/123"
$request->queryString();      // "include=profile"

// Parameters
$request->query('include');   // "profile"
$request->post('email');      // "user@example.com"
$request->input('key');       // from $_REQUEST

// Headers (case-insensitive)
$request->header('Content-Type');
$request->hasHeader('Authorization');
$request->headers();

// Cookies
$request->cookie('session_id');
$request->cookies();

// Request body
$request->rawBody();          // raw php://input
$request->json();             // decoded JSON

// Content type checks
$request->isJson();
$request->isForm();
$request->isMultipart();

// Metadata
$request->isAjax();
$request->isSecure();
$request->clientIp();
$request->host();

NativeRequest Class (High-Performance)

For performance-critical applications, NativeRequest can use the optional signalforge_http C extension:

use SimpleMehanizm\Http\NativeRequest;

$request = NativeRequest::capture();

// Same API as Request class
$request->method();
$request->header('Authorization');
$request->query('page');
// ... all methods work identically

How it works:

• When the C extension is loaded, NativeRequest delegates to native code for ~6x faster request capture
• When the extension is unavailable, it falls back to pure PHP with identical behavior
• Check availability with NativeRequest::isNativeAvailable()

Performance comparison (100,000 iterations):

The C extension is most beneficial for high-throughput applications where request parsing overhead matters.

Installing the C Extension

The extension source is located in ext/signalforge_http/. To build:

cd ext/signalforge_http
phpize
./configure --enable-signalforge_http
make
make test
sudo make install

Enable in php.ini:

extension=signalforge_http.so

Requirements:

• PHP 8.3+
• Non-ZTS (non-thread-safe) build
• Linux

Method Override

Both classes support HTTP method override for clients that cannot send PUT/PATCH/DELETE:

// Via header: X-HTTP-Method-Override: PUT
// Via form field: _method=PUT

$request->method();     // Returns "PUT" (resolved)

JSON Body Handling

When Content-Type: application/json is present, the JSON body is automatically parsed and merged into the request input:

// POST /api/users with {"name": "John"}
$request->input('name');  // "John"
$request->json();         // ["name" => "John"]

Protocol Enums

The src/Protocol directory contains enums for HTTP constants:

• StatusCode - HTTP status codes (200, 404, 500, etc.)
• ReasonPhrase - Standard reason phrases
• Headers - Common header names
• ContentType - MIME types
• MagicStrings - Framework conventions

use SimpleMehanizm\Http\Protocol\StatusCode;
use SimpleMehanizm\Http\Protocol\Headers;

$status = StatusCode::OK;           // 200
$header = Headers::CONTENT_TYPE;    // "Content-Type"

License

MIT