Download the PHP package initphp/http without Composer

InitPHP HTTP

Standards-compliant PSR-7 message, PSR-17 factory, PSR-18 client and SAPI response emitter for PHP 7.4+.

A single dependency-light package that ships the four building blocks every PHP project ends up wiring by hand: immutable HTTP messages, a unified factory, a cURL-backed client, and an emitter that converts a ResponseInterface into bytes on the wire.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
  • Building a PSR-7 Request
  • Building a PSR-7 Response
  • Sending an HTTP request (PSR-18)
  • Emitting a response (SAPI)
  • Hydrating a ServerRequest from globals
  • Using the static facades
• Documentation
• PSR Compliance
• Migration from 2.x
• Contributing
• Security
• License

Features

• PSR-7 v1 & v2 compatible — works with the entire PSR-7 ecosystem.
• PSR-17 factory — one class implements every factory interface (Request, Response, ServerRequest, Stream, UploadedFile, Uri).
• PSR-18 client backed by cURL with sane production defaults: 30 s request timeout, 10 s connect timeout, redirect following, raw CURLOPT_* overrides without subclassing.
• SAPI emitter that streams the response to the browser with optional chunked output and Content-Range support.
• Lazy static facades for projects that prefer Factory::createResponse() over instantiating helpers explicitly.
• Strict PSR-7 immutability — with*() returns deep-cloned messages; mutating the clone never touches the original (verified by a dedicated immutability test suite).
• Zero runtime dependencies outside psr/http-*. ext-curl is only required when you actually use the client.
• Passes the upstream php-http/psr7-integration-tests and http-interop/http-factory-tests suites.

Requirements

Tested on PHP 7.4, 8.0, 8.1, 8.2, 8.3 and 8.4 in CI.

Installation

Quick Start

Building a PSR-7 Request

Building a PSR-7 Response

Convenience producers on the concrete Response:

Sending an HTTP request (PSR-18)

Higher-level helpers when you don't want to build a Request by hand:

PSR-18 contract is honoured: 4xx/5xx responses are returned, not thrown. Only transport failures raise Psr\Http\Client\NetworkExceptionInterface.

Resilience: retry with exponential backoff + jitter

The client is single-attempt by default. Attach a RetryPolicy to opt in to automatic retries of transient failures — connection errors, timeouts and the retryable HTTP status set (408, 425, 429, 500, 502, 503, 504 by default) — with exponential backoff, bounded jitter, a hard max-attempts cap, and Retry-After support:

Behaviour and backward-compatibility:

• Default (no policy) = exactly one attempt — identical to previous releases.
• A non-retryable 4xx/5xx response is still returned, never thrown (PSR-18).
• A retryable response that exhausts the attempt cap is returned as-is (the last response); a transport exception that exhausts the cap is re-thrown.
• A parseable Retry-After header (delay-seconds or HTTP-date) on a retryable response overrides the computed backoff unless you disable it.
• The retryable status set, whether transport exceptions are retried, and Retry-After handling are all configurable on RetryPolicy.

Emitting a response (SAPI)

Range requests (Content-Range: bytes 0-1023/...) are honoured automatically.

Hydrating a ServerRequest from globals

The factory is stateless — every call returns a fresh instance computed from the supplied arrays. Safe under Swoole, RoadRunner, Octane and FrankenPHP.

Using the static facades

For projects that prefer terseness over explicit DI:

Each facade lazily resolves a singleton on first call; subsequent calls return the same instance. Facades are entirely optional — every facade is just a thin static wrapper over a concrete service class you can instantiate yourself.

Documentation

In-depth guides live under docs/:

• Getting Started
• PSR-7 — Uploaded Files
• PSR-17 — Factory
• PSR-18 — Configuration
• Emitter — Content-Range
• Facades — Customisation
• Recipes — Proxying requests
• HTTP status code reference
• Upgrade guide (2.x → 3.x)

PSR Compliance

This package is verified against the official compliance suites:

Relevant specs: PSR-7, PSR-17, PSR-18.

Migration from 2.x

Version 3.0 is a breaking release. The highlights:

• The custom InitPHP\HTTP\Message\Interfaces\* interfaces have been removed. Type-hint against the PSR-7 interfaces directly (Psr\Http\Message\RequestInterface, etc.).
• Request::createFromGlobals() and the magic $request->name = $value parameter bag have been removed. Use ServerRequest::createFromGlobals() (now stateless) and $request->getParsedBody() instead.
• Client::sendRequest() no longer inspects the concrete Request class — it only sees the PSR-7 contract. Pre-encode array/DOM/XML payloads before calling.
• Client now defaults to a 30 s request timeout and 10 s connect timeout. Pass ->withTimeout(0) if you need the legacy "no timeout" behaviour.
• The misspelled facade trait/interface names Facadeble[Interface] are now Facadable[Interface]; the old names remain as @deprecated aliases and will be removed in 4.0.

See docs/upgrade-guide.md for the full migration walk-through and a copy-pasteable code-mod list.

Contributing

Contributions are welcome — bug reports, doc improvements, performance patches, anything.

• Open issues and pull requests against InitPHP/HTTP.
• The project's organisation-wide Contributing Guide and Code of Conduct apply.
• Local development:

Security

If you discover a security vulnerability please review the project's Security Policy and report it privately. Please do not file public GitHub issues for security problems.

License

MIT License — Copyright © Muhammet ŞAFAK and contributors.