File Uploads

This page documents the file upload handling system in Hypervel HTTP, including the UploadedFile class, file validation, storage operations, MIME type detection, and testing utilities. For general request data access including files, see Input & Data Access.

Overview

The file upload system provides a robust abstraction over PHP's uploaded file handling, with features for validation, storage, MIME type detection, and error handling. The UploadedFile class extends Hyperf's base implementation with additional functionality for secure file processing and integration with filesystem storage.

Sources: src/UploadedFile.php1-515

File Upload System Architecture

Sources: src/Request.php48-51 src/UploadedFile.php28-30 src/Testing/File.php10-41

Retrieving Uploaded Files

From Request Object

The Request class provides the allFiles() method to retrieve all uploaded files as an array tree of UploadedFile instances:

The returned array structure matches the nested structure of uploaded files, where each leaf is an UploadedFile instance.

Sources: src/Request.php48-51

Individual File Access

Files are accessed through standard PSR-7 methods inherited from Hyperf's request implementation. Individual files can be retrieved using array access on the result of allFiles() or through the PSR-7 getUploadedFiles() method.

Sources: src/Request.php48-51 src/Request.php409-422

UploadedFile Class

Class Definition and Constructor

The UploadedFile class extends Hyperf\HttpMessage\Upload\UploadedFile and includes the Macroable trait for runtime extensibility:

Parameter	Type	Description
$path	string	Path to the temporary uploaded file
$originalName	string	Original filename from client
$mimeType	?string	Client-provided MIME type (optional)
$error	?int	PHP upload error code (defaults to UPLOAD_ERR_OK)
$size	?int	File size in bytes (auto-detected if null)
$test	bool	Whether this is a test file (defaults to false)

The constructor validates that the file exists (when no error occurred) and throws FileNotFoundException if missing.

Sources: src/UploadedFile.php28-73

Creating from Base Instance

This static factory method converts Hyperf's base UploadedFile instances to Hypervel's extended version.

Sources: src/UploadedFile.php432-442

File Metadata and Validation

Client-Provided Metadata

These methods return data provided by the client, which should not be trusted for security decisions:

Method	Return Type	Description
getClientOriginalName()	string	Original filename from upload
getClientOriginalExtension()	string	Extension extracted from original filename
getClientOriginalPath()	string	Full path (for webkitdirectory uploads)
getClientMimeType()	string	MIME type from client
guessClientExtension()	?string	Extension guessed from client MIME type
clientExtension()	string	Alias for guessClientExtension()

Sources: src/UploadedFile.php89-169

Server-Side MIME Type Detection

The getMimeType() method performs server-side MIME type detection using FileinfoMimeTypeGuesser (which uses finfo_file()) or falls back to mime_content_type(). This is the trusted MIME type:

The detected MIME type is cached in the $mimeType property after first detection.

Sources: src/UploadedFile.php238-256

Extension Guessing

The getExtension() method returns a trusted extension based on the server-detected MIME type, preferring the client's extension if it matches one of the valid extensions for the detected MIME type.

Method	Description
getExtension()	Returns trusted extension (never null, returns empty string if unknown)
extension()	Alias for getExtension()
guessExtension()	Returns extension or null if unknown

Sources: src/UploadedFile.php182-219

Validation

The isValid() method checks whether the file was uploaded successfully:

For test files ($test = true), this checks if the error code is UPLOAD_ERR_OK. For real uploads, it delegates to the parent class which verifies the file was uploaded via HTTP POST.

Sources: src/UploadedFile.php272-277

Error Handling

Upload Error Constants

The class defines error messages for all PHP upload error codes:

Constant	Error Message Template
UPLOAD_ERR_INI_SIZE	"The file "%s" exceeds your upload_max_filesize ini directive (limit is %d KiB)."
UPLOAD_ERR_FORM_SIZE	"The file "%s" exceeds the upload limit defined in your form."
UPLOAD_ERR_PARTIAL	"The file "%s" was only partially uploaded."
UPLOAD_ERR_NO_FILE	"No file was uploaded."
UPLOAD_ERR_CANT_WRITE	"The file "%s" could not be written on disk."
UPLOAD_ERR_NO_TMP_DIR	"File could not be uploaded: missing temporary directory."
UPLOAD_ERR_EXTENSION	"File upload was stopped by a PHP extension."

Sources: src/UploadedFile.php32-40

Exception Hierarchy

When move() is called on an invalid file, the appropriate exception is thrown based on the error code.

Sources: src/UploadedFile.php385-402

Error Messages

The getErrorMessage() method returns a formatted error message with the filename and, for UPLOAD_ERR_INI_SIZE, the maximum file size limit:

Sources: src/UploadedFile.php493-501

Maximum File Size

The static getMaxFilesize() method returns the effective upload limit from PHP configuration:

This returns the minimum of post_max_size and upload_max_filesize ini settings, parsing size strings like "8M" or "1G".

Sources: src/UploadedFile.php410-416 src/UploadedFile.php444-476

File Operations

File Path Access

Method	Description
path()	Returns the fully qualified path to the file
getPathname()	Returns the file pathname (inherited)
getRealPath()	Returns the real path (inherited)

Sources: src/UploadedFile.php224-227

Reading File Contents

The getContent() method reads the entire file and throws FileException if reading fails. The get() method additionally validates the file before reading. The getStream() method returns a PSR-7 StreamInterface for streaming operations.

Sources: src/UploadedFile.php258-267 src/UploadedFile.php327-334 src/UploadedFile.php350-357

Moving Files

The move() method moves the uploaded file to a permanent location:

• Creates directory if it doesn't exist (with mode 0777)
• Uses move_uploaded_file() for real uploads, rename() for CLI/test files
• Sets file permissions to 0666 & ~umask()
• Returns a new UploadedFile instance pointing to the new location
• Throws specific exceptions based on upload error code

Sources: src/UploadedFile.php364-403 src/UploadedFile.php503-514

Storing to Filesystem

The store() and storeAs() methods integrate with Hypervel's FilesystemManager:

Options can be specified as an array or as a string disk name. The disk option is extracted and passed to FilesystemManager, while other options are passed to the storage operation.

Sources: src/UploadedFile.php300-322 src/UploadedFile.php481-488

Hash Name Generation

The hashName() method generates a random 40-character filename with the file's extension:

The hash is generated once and cached in the $hashName property for consistent naming.

Sources: src/UploadedFile.php282-295

Testing Utilities

File Factory

The UploadedFile::fake() static method returns a FileFactory instance for creating test files:

Sources: src/UploadedFile.php78-81

Creating Test Files

The File class in the testing namespace provides convenient methods for creating fake uploaded files:

Sources: src/Testing/File.php46-65

Customizing Test Files

Test files support chainable methods for customization:

The size() method sets $sizeToReport (returned by getSize()), while mimeType() sets $mimeTypeToReport (returned by getMimeType()).

Sources: src/Testing/File.php70-107

Test File Properties

Test files differ from real uploaded files in these ways:

1. Created with $test = true flag, causing isValid() to check only the error code
2. Stored in temporary locations created by tmpfile()
3. Can override size and MIME type for testing validation logic
4. Extension guessing uses MimeTypeExtensionGuesser directly instead of file introspection

Sources: src/Testing/File.php27-41 src/Testing/File.php98-107

File Upload Lifecycle

Sources: src/Request.php48-51 src/UploadedFile.php272-277 src/UploadedFile.php238-256 src/UploadedFile.php198-211 src/UploadedFile.php300-322 src/UploadedFile.php364-383