Download the PHP package koriym/file-upload without Composer

Koriym.FileUpload

Type-safe file upload handling with immutable value objects.

Motivation

Testing file uploads in PHP applications is traditionally complex and time-consuming. It often requires setting up a built-in web server, making HTTP requests, and managing multipart form data. This approach leads to slow, unreliable tests that are difficult to debug and maintain, especially in CI environments.

This library simplifies both the handling of file uploads and their testing. Instead of dealing with PHP's native $_FILES array directly, you work with immutable value objects that provide type safety and early validation. For testing, rather than simulating HTTP file uploads, you can create test instances directly from files on your filesystem. This approach makes tests faster, more reliable, and easier to debug while still testing real-world scenarios with actual file types and contents.

Installation

Usage

From $_FILES

From File Path (for Testing)

Properties

Both FileUpload and ErrorFileUpload have the following properties:

Additionally, ErrorFileUpload has:

Validation Options

You can pass the following validation options to both create() and fromFile():

• maxSize: Maximum file size in bytes
• allowedTypes: Array of allowed MIME types
• allowedExtensions: Array of allowed file extensions

Testing

Using toArray()

The library provides a toArray() method to convert a FileUpload object back to $_FILES format array, which is useful for creating test stubs:

Using fromFile()

For more realistic testing scenarios, you can create a FileUpload instance directly from a file:

This is particularly useful when you want to test with real files and MIME types.

Note: The move() method behaves differently in CLI and web environments:

• In web environment: Uses move_uploaded_file() for security
• In CLI environment (testing): Uses rename() for testability

Testing Tips

Testing Code That Depends on $_FILES

When testing code that depends on $_FILES, you can use the combination of fromFile() and toArray() to create controlled, reproducible tests without the complexity of setting up actual HTTP file uploads:

See the example in docs/UploadHandlerTest.php.

Similar Libraries

Both Symfony HttpFoundation and Laravel provide file upload handling as part of their frameworks. While these frameworks offer more comprehensive features including storage abstraction and integration with their ecosystems, Koriym.FileUpload takes a more focused approach by providing a lightweight, framework-independent solution that transforms PHP's native $_FILES array into type-safe immutable objects.

Additional Information

PHP's $_FILES structure:

For multiple file uploads:

PHP Upload Error Codes: