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):

Operation	C Extension	PHP Fallback	Speedup
capture()	533 ns	3,297 ns	6.2x
method()	41 ns	47 ns	1.1x
header()	58 ns	62 ns	1.1x
contentType()	42 ns	97 ns	2.3x
isJson()	42 ns	89 ns	2.1x

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

simplemehanizm / http

Maintainers

Details