symfony/http-foundation

symfony/http-foundation replaces PHP’s raw superglobals ($_GET, $_POST, $_SERVER, $_COOKIE, $_FILES) with a clean object model: a Request object that parses and normalizes incoming HTTP data, a Response object (plus JsonResponse, RedirectResponse, BinaryFileResponse, and StreamedResponse variants) for building output, and supporting classes for headers, cookies, sessions, and uploaded files. It underpins the Symfony framework’s HTTP layer but is fully decoupled and widely reused standalone — most notably as the HTTP data layer inside PHPUnit-adjacent tooling and countless microframeworks that need a battle-tested request/response abstraction without adopting all of Symfony.

What You Get

• Request — parses $_GET, $_POST, $_SERVER, $_COOKIE, and $_FILES into typed ParameterBag/HeaderBag/FileBag objects with helpers like getMethod(), isXmlHttpRequest(), and content-negotiation via AcceptHeader
• Response and its specializations — JsonResponse, RedirectResponse, BinaryFileResponse (for efficient file downloads with range support), and StreamedResponse/StreamedJsonResponse for chunked output
• Session management — Session, storage handlers, and flash-message bags for per-request state across requests
• Cookie and header utilities — Cookie, HeaderBag, HeaderUtils, and ResponseHeaderBag for RFC-compliant header construction and parsing
• Security helpers — RequestMatcher/ChainRequestMatcher for route/IP/method matching, UriSigner for tamper-proof signed URLs, and IpUtils for trusted-proxy IP resolution

Common Use Cases

• Building a custom PHP micro-framework or middleware stack on a proven Request/Response abstraction instead of hand-rolling superglobal parsing
• Serving file downloads efficiently with BinaryFileResponse, including HTTP range requests for resumable downloads and streaming media
• Generating signed, tamper-proof URLs (e.g. for unsubscribe links or temporary access) with UriSigner
• Managing session state and flash messages across requests in any PHP application, framework or not

Under The Hood

Architecture - The component centers on two classes, Request and Response, each backed by specialized “bag” objects (ParameterBag, HeaderBag, FileBag, ServerBag) that wrap the raw superglobal arrays and expose typed accessors; Request::createFromGlobals() is the standard entry point that snapshots PHP’s global state into an immutable-feeling object graph, while subclasses of Response (JsonResponse, RedirectResponse, BinaryFileResponse, StreamedResponse) override sendContent()/prepare() to specialize output behavior like range-request handling or chunked streaming. Supporting subsystems — Session/, RequestMatcher/, RateLimiter/, File/ — are organized as sibling namespaces under the same PSR-4 root, each independently usable. Tech Stack - Pure PHP (8.4+ required for the current branch) with minimal runtime dependencies (symfony/deprecation-contracts, symfony/polyfill-mbstring); optional integrations with symfony/cache, symfony/mime, doctrine/dbal, and predis/predis are dev-only, keeping the core library dependency-light while supporting pluggable session/cache backends. Code Quality - The Tests/ directory mirrors the source tree file-for-file (ServerBagTest.php, CookieTest.php, RedirectResponseTest.php, etc.) with PHPUnit, reflecting Symfony’s long-standing contract of full BC-compatible test coverage across every public class; code follows strict typing and PSR-12-adjacent conventions enforced across the wider Symfony monorepo. API Design - The Request/Response split maps directly onto the HTTP model developers already understand, and bag objects ($request->query, $request->headers, $request->files) give discoverable, IDE-autocompletable access to what would otherwise be untyped array lookups — the tradeoff is a larger surface area to learn than raw superglobals, offset by far fewer footguns around encoding, trusted proxies, and header parsing edge cases.