Download the PHP package philharmony/http-message without Composer

philharmony/http-message

Strict, type-safe PSR-7 HTTP Message implementation for modern PHP (8.1+). Designed for maximum security, immutability, and seamless integration with modern PHP 8.1+ ecosystems.

📖 Description

philharmony/http-message provides a robust, high-performance implementation of the PSR-7 HTTP Message interfaces. This package serves as the foundational messaging layer for the Philharmony framework, focusing on:

• Full PSR-7 Compliance — Interchangeable with any PSR-compliant library.
• Strict Typing — Verified with PHPStan Level 9 for rock-solid reliability.
• Security by Design — Prevents common URI vulnerabilities like path/host ambiguity (RFC 3986).
• Smart Encoding — Handles UTF-8 characters and avoids double-encoding of existing percent-encoded sequences.
• IPv6 & IDN Support — Fully supports IPv6 hosts and internationalized domain names.
• Enum Integration — Works natively with philharmony/http-enum for scheme and port logic.
• Strict Validation — Prevents invalid hosts and illegal URI characters according to RFC 3986.

✨ Key Features

• Full PSR-7 compliance — Fully compatible with the PHP ecosystem.
• Strict typing — Verified with PHPStan Level 9.
• Immutable design — Safe for middleware pipelines.
• IPv6 & IDN support — Modern host formats supported out of the box.
• Smart URI encoding — Prevents double-encoding and handles Unicode safely.
• Security-focused validation — Rejects invalid hosts and illegal URI characters.
• Upload error abstraction — PHP upload errors wrapped in a type-safe enum.

💡 Why philharmony/http-message?

While many PSR-7 implementations focus on compatibility, philharmony/http-message focuses on:

• Maximum type safety through strict typing and PHPStan Level 9 analysis
• Security-first URI handling following RFC 3986
• Modern PHP support (8.1–8.4)
• Clean immutable design optimized for middleware architectures

📦 Installation

Install via Composer:

⚡ Quick Start

A minimal example demonstrating the core PSR-7 objects provided by this package.

🚀 Usage: URI

Creating a URI

IPv6 and IDN Hosts

The URI implementation supports modern host formats including IPv6 and internationalized domain names.

Immutability in Action

As per PSR-7, Uri objects are immutable. Every modification returns a new instance. If the new value is identical to the current one, the same instance is returned for performance.

Advanced Encoding

The library automatically handles complex paths and query strings, ensuring they are RFC-compliant.

🚀 Usage: Stream

The Stream class provides a type-safe wrapper around PHP resources (fopen, php://memory, etc.).

Polymorphic Creation

The static create() method is highly flexible and accepts strings, resources, or existing streams:

Direct File Creation

Use Stream::createFromFile() to create a stream directly from a file path. This method handles file opening and error management automatically:

Key benefits:

• Simplified creation — eliminates the need to manually call fopen(); the method handles file opening internally.
• Explicit error handling — throws InvalidArgumentException for empty file names or modes, and RuntimeException with detailed error messages if the file cannot be opened (e.g., due to permission issues or non‑existent paths).
• Consistent interface — returns a StreamInterface instance, maintaining compatibility with other Stream creation methods like create().
• Input validation — performs basic validation of required parameters ($fileName and $mode must not be empty) before attempting file operations.

Safe Operations

Unlike raw PHP functions, Stream ensures that system errors are handled gracefully:

Predictable Stream Behaviour

The Stream implementation ensures consistent and predictable behavior across different stream types.

• Automatic rewind for string bodies — when creating a stream from a non-empty string, the pointer is automatically rewound.
• Reliable mode detection — readable and writable capabilities are detected based on the underlying stream mode.
• Safe string casting — __toString() safely catches all Throwable errors as required by PSR-7.
• Robust size detection — stream size detection gracefully handles environments where fstat() may return unexpected values.

These guarantees make the Stream implementation safe to use with memory streams, file streams, and custom PHP resources.

🏗️ Architecture: Base Message

All HTTP entities inherit from the abstract Message class, providing robust header management:

• Case-insensitive headers — withHeader('content-type', ...) and getHeader('Content-Type') work seamlessly.
• Protocol versioning — Supports HTTP/1.0, 1.1, 2.0.
• Immutable state — Every change produces a new instance, preventing side effects in middleware chains.

🚀 Usage: HTTP Messages (Request & Response)

Philharmony provides full implementations of PSR-7 HTTP message types:

• Request — client-side HTTP request
• ServerRequest — server-side request containing environment data
• Response — HTTP response message

All messages extend the base Message abstraction and follow a fully immutable design.

Request (Client Request)

The Request class represents an outgoing HTTP request typically used by HTTP clients.

Creating a Request

Smart HTTP Method Helpers

Philharmony provides helper methods powered by the HttpMethod enum.

ServerRequest (Server-Side Request)

ServerRequest extends Request and represents an incoming HTTP request received by the server.

It provides access to additional environment data such as:

• server parameters ($_SERVER)
• cookies ($_COOKIE)
• query parameters ($_GET)
• uploaded files ($_FILES)
• parsed request bodies

Creating a ServerRequest

Parsed Body Helpers

The request body is automatically parsed depending on the Content-Type header.

Raw Body & Input Helpers

Convenience helpers allow retrieving input values from query parameters or parsed body data.

Lookup order:

1. Query parameters
2. Parsed request body

Response

The Response class automatically handles Reason Phrases using the Philharmony\Http\Enum\StatusCode.

🚀 Usage: Uploaded Files

Handle file uploads with full PSR-7 compatibility and support for modern PHP features like full_path (PHP 8.1+).

Upload Error Handling

Upload errors are represented internally by the UploadError enum.

🔍 Technical Specifications

🧪 Testing

The package is strictly tested with PHPUnit 10 to ensure full compliance with HTTP standards and RFCs.

Run Tests

Code Coverage

🏗️ Static Analysis & Code Style

Verified with PHPStan Level 9 to ensure total type safety and prevent runtime errors.

Check and fix code style (PSR-12):

📄 License

This package is open-source and licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome.

If you find a bug or have an idea for improvement, please open an issue or submit a pull request.

⭐ Support

If you find this package useful, please consider giving it a star on GitHub. It helps the project grow and reach more developers.