Http Range Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require ramsey/http-range

Then, use the RangeHeaderParser to parse incoming Range headers from requests:

use Ramsey\Http\Range\RangeHeaderParser;

$parser = new RangeHeaderParser();
$ranges = $parser->parse('bytes=0-499, 1000-1499'); 
// Returns array of RangeInterface objects, e.g. [Range(0, 499), Range(1000, 1499)]

For responding to range requests, create a ContentRange header to send back:

use Ramsey\Http\Range\ContentRange;

$contentRange = new ContentRange(0, 499, 2000); // start, end, total
// Result: "bytes 0-499/2000"

This is ideal for handling resumable uploads or video streaming where clients request specific byte ranges.

Implementation Patterns

• Streaming Partial Responses: Use parsed ranges to read slices from a file or stream (e.g., fseek(), fread()) and return a 206 Partial Content response with proper Content-Range and Content-Length.
• Validation Layer: Before serving, validate ranges against resource size using Range::validate($ranges, $resourceSize) to detect invalid or impossible requests.
• Range Merging & Overlap Handling: When multiple ranges overlap or are malformed (e.g., bytes=100-50), the parser normalizes or flags them—allow you to implement fallback logic or return 416 Range Not Satisfiable.
• Middleware Integration: In frameworks like Laravel, wrap parsing/validation in middleware: extract Range, validate, and short-circuit if ranges are unsatisfiable before heavy processing.
• Testing: Mock range requests with unit tests using RangeHeaderParser to assert correct parsing of edge cases like bytes=-500 (suffix ranges) or bytes=500- (to-end ranges).

Gotchas and Tips

• Resource Size is Critical: Always provide accurate total size when validating ranges; a mismatch causes false 416 errors or truncated/corrupt responses.
• Suffix Ranges: Range: bytes=-500 means "last 500 bytes"—validate this correctly: start = max(0, total - 500).
• Overlapping Ranges: The parser does not merge overlapping ranges; you must deduplicate or reorder them manually before deciding how to respond (multipart vs. concatenated).
• RFC 7233 Edge Cases: The library won’t auto-convert to unitless or invalid suffix forms—always use ContentRange with explicit start, end, and total.
• Memory Efficiency Tip: For large files, stream byte slices using generators rather than loading whole ranges into memory.
• Framework Gotcha: Don’t forget to set Content-Length as sum of range lengths (not the total file size) and ensure Accept-Ranges: bytes is present in responses.