Download the PHP package iviphp/http without Composer

Ivi HTTP

HTTP request, response, header and uploaded-file primitives for the IviPHP ecosystem.

Overview

iviphp/http provides the low-level HTTP objects used by IviPHP applications and packages.

The package includes:

• case-insensitive HTTP header management;
• request creation from PHP superglobals;
• query, body, JSON, cookie and server access;
• normalized single and multiple file uploads;
• secure uploaded-file validation and movement;
• optional Gzip file compression;
• immutable response transformations;
• JSON, HTML, text, redirect and empty responses;
• structured HTTP exceptions.

This package does not provide routing, middleware execution or application bootstrapping. Those responsibilities belong to higher-level IviPHP components.

Installation

Requirements

• PHP 8.2 or later
• Composer
• iviphp/support
• PHP Fileinfo extension for trusted media-type detection
• PHP Zlib extension for optional Gzip compression

Request

Create a request manually:

Create a request from PHP superglobals:

Request::fromGlobals() reads:

• $_SERVER;
• $_GET;
• $_POST;
• $_COOKIE;
• $_FILES;
• php://input.

Optional arguments can be passed for isolated tests.

Request method and URI

The request path is not automatically URL-decoded. This preserves encoded path separators and avoids changing security-sensitive URI data.

Request headers

Header names are case-insensitive.

All three calls resolve the same header.

Content type and authentication

contentType() removes parameters such as the character set.

becomes:

Query parameters

Nested query values can be accessed with dot notation.

Parsed request body

Dot notation is available when the parsed body is an array.

JSON requests

Invalid JSON throws an InvalidArgumentException containing the original JsonException.

Check the media type before expecting JSON:

Combined input

Query parameters and body values can be accessed through one interface.

Body values override query values when the same key exists.

Cookies

Cookie values are untrusted user input and must be validated before use.

Server values

isSecure() checks the direct PHP server environment.

Forwarded headers such as X-Forwarded-Proto are intentionally not trusted automatically. Proxy trust must be configured by a higher-level application component.

Request attributes

Request attributes can store routing and middleware data.

Request transformation methods return a new request.

The original request is not modified.

Uploaded files

Retrieve an uploaded file:

Check whether an upload entry exists:

Multiple and nested PHP upload arrays are normalized automatically.

A nested upload may return an array containing multiple UploadedFile instances.

Creating an UploadedFile

From a PHP $_FILES entry:

For tests and internal file processing:

Files created with fromPath() are not treated as genuine PHP HTTP uploads.

Upload validity

A genuine HTTP upload is considered valid only when:

• the PHP upload error is UPLOAD_ERR_OK;
• the temporary file exists;
• the temporary file is readable;
• PHP confirms that it was uploaded through HTTP;
• the file has not already been moved.

Uploaded filename security

The original filename is available through:

The client-provided filename must never be used directly as a filesystem path.

Use the sanitized filename instead:

Provide a fallback when necessary:

The client extension can be retrieved with:

The extension is still client-controlled and must not be used as the only validation mechanism.

Media-type validation

The client-provided type is available through:

This value is not trustworthy.

Detect the media type from the file contents:

Validate against accepted types:

Wildcard families are supported:

Content-based media-type detection requires the PHP Fileinfo extension.

Upload size validation

Retrieve the real filesystem size:

Retrieve the client-declared size:

Validate the maximum accepted size:

The example allows files up to 5 MiB.

Server limits such as upload_max_filesize and post_max_size must also be configured correctly.

Upload checksums

Calculate a SHA-256 checksum:

Use another supported hash algorithm:

Checksums can help with:

• duplicate detection;
• integrity verification;
• content-addressed storage;
• audit records.

A checksum does not replace malware scanning or media validation.

Reading uploaded files

Open the uploaded file as a binary stream:

Streaming avoids loading large files entirely into memory.

Moving uploaded files

Existing files are not overwritten by default.

Optional permissions can be applied:

The destination directory must already exist and be writable.

After movement:

path() returns the temporary path before movement and the final path afterward.

An uploaded file cannot be moved twice.

Upload compression

Compression is explicit and optional.

Select a Gzip compression level from 0 to 9:

Allow replacement of an existing compressed file:

Compression creates a compressed copy and does not move or delete the source upload.

Automatic compression is intentionally avoided. Formats such as these are already compressed or may gain little from Gzip:

• JPEG;
• PNG;
• WebP;
• MP4;
• ZIP;
• PDF.

Gzip compression is most useful for text-based files such as:

• JSON;
• CSV;
• XML;
• plain text;
• application logs;
• large SQL exports.

Compression requires the PHP Zlib extension.

Upload security recommendations

For production upload handling:

1. Validate the PHP upload error.
2. Enforce a maximum file size.
3. Detect the media type from file contents.
4. Allow only explicitly supported media types.
5. Generate a server-controlled storage filename.
6. Store uploads outside the public web root when possible.
7. Prevent script execution inside upload directories.
8. Calculate a checksum when integrity matters.
9. Scan untrusted files when malware detection is required.
10. Never trust the original filename, extension or media type.

Example:

Headers

Create a header collection:

Read headers:

Set and append values:

Remove headers:

Return all values:

Flatten values into strings:

Create modified copies:

Header names and values are validated to prevent invalid names and line-break injection.

Response

Create a basic response:

Text responses

With a custom status:

HTML responses

The default content type is:

JSON responses

With a status code:

Invalid JSON values throw an InvalidArgumentException containing the original JsonException.

Redirect responses

Permanent redirect:

Temporary method-preserving redirect:

Redirect locations are validated against empty values and response-header injection.

Empty responses

Equivalent form:

Informational responses, 204 No Content and 304 Not Modified cannot contain a body.

Reading a response

Check the response category:

Transforming a response

Responses support immutable transformations.

Replace the body:

Remove a header:

The original response remains unchanged.

Sending a response

Send headers and status without the body:

Sending after PHP output has already started throws a RuntimeException.

HTTP exceptions

Create a generic HTTP exception:

Common factories are available:

Method not allowed:

Rate limiting:

Temporary service outage:

Exception headers

Some exception factories include HTTP response headers automatically.

Other examples include:

• WWW-Authenticate for unauthorized requests;
• Retry-After for rate limits;
• Retry-After for temporary service outages.

Exception context

Internal diagnostic data can be attached to an exception:

Read the context:

Exception context is intended for logs and debugging. It must not be returned directly to clients without filtering.

Converting an exception to a response

Production applications should avoid exposing internal exception messages and context for server errors.

Available classes

Headers

Request

UploadedFile

Response

HttpException

Design principles

• Small framework-independent HTTP primitives
• Case-insensitive and validated headers
• Immutable request and response transformations
• Explicit JSON parsing and encoding failures
• Safe normalization of PHP file uploads
• Content-based upload media detection
• Stream-oriented large-file handling
• No automatic trust of proxy headers
• No automatic trust of client upload metadata
• No hidden global request or response state
• Explicit exception status codes and headers

Package boundaries

This package is responsible for:

• representing incoming requests;
• representing outgoing responses;
• managing HTTP headers;
• normalizing uploaded files;
• securely moving and optionally compressing uploads;
• representing HTTP failures.

It is not responsible for:

• routing;
• middleware pipelines;
• controllers;
• sessions;
• authentication;
• CSRF protection;
• validation rules;
• template rendering;
• application lifecycle management.

These responsibilities belong to other IviPHP packages.

Ecosystem

This package is part of the IviPHP ecosystem:

• iviphp/contracts
• iviphp/support
• iviphp/config
• iviphp/container
• iviphp/validation
• iviphp/database
• iviphp/cache
• iviphp/view
• iviphp/auth
• iviphp/framework

Contributing

Contributions should preserve the focused scope of the package.

Changes should:

• remain independent from the full framework;
• avoid global request or response state;
• preserve header-injection protections;
• preserve safe upload handling;
• avoid trusting client-controlled file metadata;
• avoid loading large files entirely into memory;
• keep compression explicit;
• provide clear exceptions for invalid HTTP operations.

Security

Please report security issues privately to the Softadastra maintainers instead of opening a public issue.

License

This project is licensed under the MIT License.

Maintainer

Created and maintained by Softadastra.