Last indexed: 7 February 2026 (a324f6)

Utility Classes

Purpose and Scope

This document provides an overview of the utility classes that support HTTP operations in the hypervel/http package. These classes handle low-level HTTP concerns including header parsing, header manipulation, query string processing, and range request validation. They are primarily used internally by the Request and Response objects but can also be used directly when building custom HTTP functionality.

For information about how these utilities integrate with request handling, see Request Handling. For response-specific utilities like streaming, see Streaming & Range Requests.

Overview

The utility layer consists of three primary components:

Class	File	Purpose
`HeaderUtils`	src/HeaderUtils.php	Static methods for header parsing, quoting, Content-Disposition generation, query parsing, and range validation
`AcceptHeader`	src/AcceptHeader.php	Parses and manages Accept-* headers with quality values and preference sorting
`AcceptHeaderItem`	src/AcceptHeaderItem.php	Represents individual items within an Accept-* header
`RequestUtils`	src/RequestUtils.php	Helper methods for accessing GET/POST parameters (detailed in Request Utilities)

These utilities originated from the Symfony HTTP Foundation component and have been adapted for use with Hyperf's PSR-7 implementation.

Sources: src/HeaderUtils.php1-372 src/AcceptHeader.php1-161

Utility Class Architecture

Sources: src/HeaderUtils.php24-372 src/AcceptHeader.php24-160

HeaderUtils Methods

The HeaderUtils class provides static methods organized by functionality:

Header Parsing Methods

Method	Purpose	Return Type
`split(string $header, string $separators)`	Splits headers by multiple separators with proper quote handling	`array`
`combine(array $parts)`	Combines nested arrays into associative array	`array`
`parseQuery(string $query, bool $ignoreBrackets, string $separator)`	Parses query strings preserving dots in variable names	`array`

Header Formatting Methods

Method	Purpose	Return Type
`quote(string $s)`	Quotes strings for HTTP header values	`string`
`unquote(string $s)`	Removes quotes from header values	`string`
`toString(array $assoc, string $separator)`	Joins associative arrays into header strings	`string`
`makeDisposition(string $disposition, string $filename, string $filenameFallback)`	Generates RFC 6266 compliant Content-Disposition headers	`string`

Validation Methods

Method	Purpose	Return Type
`validateRangeHeaders(string $rangeHeader, ?int $fileSize)`	Validates and parses Range header values	`array`

Sources: src/HeaderUtils.php24-372

Accept Header Processing Flow

Sources: src/AcceptHeader.php46-60 src/AcceptHeader.php132-148

AcceptHeader Class Structure

The AcceptHeader class represents a parsed Accept-* header with automatic quality-based sorting:

Construction and Parsing

The class is constructed from a raw header string using AcceptHeader::fromString() src/AcceptHeader.php46-60 The parsing process:

Splits the header using HeaderUtils::split() with separators ,;=
Creates AcceptHeaderItem instances for each item
Assigns sequential index values to preserve original order
Stores items in an associative array keyed by value

Item Management

Method	Line Numbers	Description
`add()`	src/AcceptHeader.php91-97	Adds an item and marks the collection as unsorted
`has()`	src/AcceptHeader.php73-76	Checks if a value exists in the header
`get()`	src/AcceptHeader.php81-84	Retrieves an item with wildcard fallback support (`/`, `type/*`)
`all()`	src/AcceptHeader.php104-109	Returns all items sorted by quality
`first()`	src/AcceptHeader.php122-127	Returns the highest quality item
`filter()`	src/AcceptHeader.php114-117	Filters items by regex pattern

Quality-Based Sorting

The sort() method src/AcceptHeader.php132-148 implements a comparator that:

Compares quality values (q parameter) in descending order
Uses the original index as a tiebreaker to maintain stable sorting
Only sorts when the sorted flag is false to optimize performance

Sources: src/AcceptHeader.php24-160

Integration with Request Processing

Sources: src/AcceptHeader.php46-60 src/HeaderUtils.php65-92

Common Usage Patterns

Header Splitting

The HeaderUtils::split() method src/HeaderUtils.php65-92 handles complex header parsing with nested separators:

HeaderUtils::split('text/html; charset=utf-8, application/json; q=0.9', ',;=')
// Returns:
// [
// ['text/html', ['charset', 'utf-8']],
// ['application/json', ['q', '0.9']]
// ]

The method properly handles:

Quoted strings with escaped characters
Multiple levels of separators (e.g., , then ; then =)
Whitespace normalization

Content-Disposition Headers

The HeaderUtils::makeDisposition() method src/HeaderUtils.php185-216 generates RFC 6266 compliant headers:

HeaderUtils::makeDisposition('attachment', 'résumé.pdf', 'resume.pdf')
// Returns: "attachment; filename=resume.pdf; filename*=utf-8''r%C3%A9sum%C3%A9.pdf"

The method validates:

Disposition type must be attachment or inline src/HeaderUtils.php27-28
Fallback filename must be ASCII-only src/HeaderUtils.php196-198
No percent characters in fallback src/HeaderUtils.php201-203
No path separators in either filename src/HeaderUtils.php206-208

Range Header Validation

The HeaderUtils::validateRangeHeaders() method src/HeaderUtils.php286-328 parses and validates HTTP Range requests:

HeaderUtils::validateRangeHeaders('bytes=100-200', 1000)
// Returns: [100, 200]

HeaderUtils::validateRangeHeaders('bytes=-500', 1000)
// Returns: [500, 999] (last 500 bytes)

The method handles:

Byte ranges with start and end positions
Suffix byte ranges (last N bytes)
Open-ended ranges (from position to end)
Validation against file size
Throws RangeNotSatisfiableHttpException for invalid ranges src/HeaderUtils.php292-297 src/HeaderUtils.php314-320

Sources: src/HeaderUtils.php65-92 src/HeaderUtils.php185-216 src/HeaderUtils.php286-328

Query String Parsing

The HeaderUtils::parseQuery() method src/HeaderUtils.php221-274 provides an alternative to PHP's parse_str() that preserves dots in variable names:

The $ignoreBrackets parameter src/HeaderUtils.php244-248 controls whether bracket notation is processed. When true, all values are collected into arrays without interpreting brackets.

Sources: src/HeaderUtils.php221-274

Format Constants

The HeaderUtils::$formats array src/HeaderUtils.php30-42 maps format names to MIME types:

Format	MIME Types
`html`	`text/html`, `application/xhtml+xml`
`json`	`application/json`, `application/x-json`
`xml`	`text/xml`, `application/xml`, `application/x-xml`
`js`	`application/javascript`, `application/x-javascript`, `text/javascript`
`css`	`text/css`
`txt`	`text/plain`
`jsonld`	`application/ld+json`
`rdf`	`application/rdf+xml`
`atom`	`application/atom+xml`
`rss`	`application/rss+xml`
`form`	`application/x-www-form-urlencoded`, `multipart/form-data`

This mapping is used for content type negotiation and format detection throughout the package.

Sources: src/HeaderUtils.php30-42

Type Matching

The AcceptHeader::matchesType() static method src/AcceptHeader.php150-159 implements structured syntax suffix matching per RFC 6839:

AcceptHeader::matchesType('application/json', 'application/vnd.api+json')
// Returns: true (matches json suffix)

AcceptHeader::matchesType('text/html', 'text/xml')
// Returns: false

The method checks:

Exact match between actual and requested type
Structured syntax suffix match (e.g., +json, +xml)

Sources: src/AcceptHeader.php150-159

Related Components

For detailed information about specific utility classes:

HeaderUtils methods: See HeaderUtils for comprehensive method documentation
Accept header parsing: See Accept Header Parsing for detailed AcceptHeader and AcceptHeaderItem documentation
Request utilities: See Request Utilities for RequestUtils helper methods

These utilities support the core HTTP components:

Used by Request for content negotiation: Headers & Content Negotiation
Used by Response for file downloads: Response Types
Used by Response for streaming: Streaming & Range Requests