Download the PHP package thingmabobby/file-upload-service without Composer

FileUploadService

A comprehensive PHP service for handling file uploads from base64 encoded data URIs or traditional file uploads ($_FILES array). Supports images, PDFs, CAD drawings, videos, and other common file types with pluggable storage backends, advanced security features, and flexible validation options.

Features

• Multiple Input Types: Handles both $_FILES arrays and base64 data URIs seamlessly
• Comprehensive File Type Support: Images, PDFs, CAD files, documents, archives, and videos
• Custom MIME Type Support: Allow specific MIME types and custom extensions beyond predefined categories
• Advanced Security: Path traversal protection, filename sanitization, MIME type validation, atomic file operations
• HEIC/HEIF Conversion: Automatically converts HEIC/HEIF files to JPEG with graceful degradation
• Collision Resolution: Multiple strategies for handling filename conflicts (increment, UUID, timestamp, custom)
• Error Handling: Comprehensive error tracking with rollback support
• High Performance Mode: Optimized for network storage and high-collision scenarios
• Pluggable Storage: Extensible storage backends via FileSaverInterface (filesystem, cloud, custom)
• Type Safety: Full enum-based type system for file types and strategies
• Separate DTOs: Specialized data transfer objects for different input types
• Cross-Platform: Full Windows, Linux, and macOS compatibility with proper path handling

Minimum Requirements

• PHP 8.1 or higher

Suggested Requirements

• ext-fileinfo for MIME type validation to work
• maestroerror/php-heic-to-jpg for HEIC/HEIF conversion

Installation

Basic Usage

Structured Successful Uploads

$result->successfulFiles remains an array of path/identifier strings for backward compatibility.

$result->successfulUploads contains FileUploadSuccess objects with input provenance and final processed-file metadata. Use this when you need original vs requested vs stored names, MIME type, size, or whether HEIC conversion actually produced the stored artifact.

Input vs output fields:

• Input / provenance: originalFilename, requestedFilename, inputIndex
• Output (processed artifact): storedFilename, extension, mimeType, sizeBytes, wasConverted
• Storage identifier: storedPath — opaque saver return value. Do not parse it to recover filename, extension, MIME type, or size. storedFilename is the logical processed name and may not appear in storedPath.

originalFilename is untrusted provenance metadata. It intentionally preserves the raw incoming $_FILES['name'] (or is null for base64/data-URI input, which has no intrinsic original filename). It may contain unsafe client-supplied text. Never use it as a filesystem path, stored filename, or Content-Disposition value, and never treat it as sanitized output. storedFilename is the package-produced logical/sanitized filename for the successfully processed artifact.

Traditional Usage (Backward Compatible)

Custom MIME Type Support

The service now supports custom MIME types and extensions beyond the predefined categories:

Using Constructor with MIME Types

Using Setter Methods

Mixed Configuration Example

Video File Support

The service now includes comprehensive video file support:

Exception Handling

The FileUploadService uses a two-tier exception handling strategy:

Critical Errors (Thrown Exceptions)

These errors prevent the entire operation from proceeding and should be caught with try-catch:

• Directory Issues: Upload destination doesn't exist and can't be created
• Permission Issues: Upload destination is not writable
• Parameter Mismatches: Filename count doesn't match input count
• Configuration Errors: Invalid file types provided

Individual File Errors (Captured in Result)

These errors affect individual files but allow the operation to continue:

• File Validation Failures: Invalid file types, corrupted data
• Upload Errors: PHP upload errors (file too large, partial upload, etc.)
• Processing Errors: HEIC conversion failures, file saving issues

Best Practice

Always wrap the save() method in a try-catch block to handle critical errors, then check the result for individual file errors:

Configuration

File Type Restrictions

HEIC/HEIF Conversion

The service automatically attempts to convert HEIC/HEIF files to JPEG format. If the conversion library is not available, it gracefully degrades by saving the original HEIC/HEIF file as-is.

HEIC Conversion Behavior:

• Default behavior: HEIC/HEIF files are automatically detected via MIME type and converted to JPEG format
• Detection method: Uses MIME type from uploaded file (primary), finfo detection (fallback), and binary header checks (last resort)
• Extension-agnostic: Files are detected by content, not file extension, preventing misidentification
• Conversion fails: Falls back to saving the original HEIC/HEIF file
• Always graceful: Never fails uploads due to conversion issues
• Library dependency: Uses maestroerror/php-heic-to-jpg package (required dependency)

On a successful conversion, FileUploadSuccess describes the JPEG output: storedFilename ends in .jpg, mimeType is image/jpeg, wasConverted is true, and originalFilename still records the incoming name (for example IMG_1234.HEIC). wasConverted is true only when conversion actually produced the stored artifact — not merely because conversion was enabled. Data-URI uploads have originalFilename === null.

Collision Resolution Strategies

High Performance Mode

Error Handling and Rollback

Storage Backends

Input Types

$_FILES Structure Handling

The service automatically detects and handles different $_FILES array structures:

Single File Upload:

Multiple File Upload:

Base64 Data URIs

Mixed Input Types

Supported File Types

The service supports a comprehensive range of file types through the SupportedFileTypesEnum. Here are all supported file types organized by category:

Images

Videos

PDF Documents

Documents

CAD Files

Archives

File Type Categories

The service organizes file types into the following categories (accessible via FileTypeEnum):

• image - All image formats (JPEG, PNG, GIF, WebP, AVIF, JXL, BMP, TIFF, HEIC, HEIF)
• video - All video formats (MP4, AVI, MOV, WMV, FLV, WebM, MKV, MPEG, 3GP, M4V, OGV)
• pdf - PDF documents (all MIME variants)
• doc - All document formats (Office, OpenDocument, text files)
• cad - CAD and technical drawing files
• archive - Compressed archive formats
• all - Allow all file types (no restrictions)

Note: For programmatic access to this information, use the SupportedFileTypesEnum class which provides methods to get extensions, MIME types, and categories for each supported file type.

Security Features

Path Traversal Protection

• FilesystemSaver::resolvePath() prevents ../ attacks in filenames
• Upload destinations can use legitimate directory navigation (e.g., ../images/)
• All paths are validated to stay within basePath
• Absolute paths are rejected for security

Filename Sanitization

• FilenameSanitizer::cleanFilename() removes dangerous characters
• Null byte removal prevents security bypasses
• Unicode normalization prevents confusion attacks
• Length limits prevent filesystem issues

MIME Type Validation

• FileServiceValidator::isFileTypeAllowed() validates actual file content
• Uses finfo to detect real MIME types
• Prevents file type spoofing attacks
• Custom MIME types are validated against actual file content

Atomic File Operations

• All file saves use temporary files + rename() for atomicity
• Prevents race conditions and partial file writes
• Secure temporary directory creation with restricted permissions

Double Extension Protection

• Files like malware.php.txt are treated as .txt files (safe)
• Files like malware.txt.php are blocked by MIME validation
• MIME type detection prevents execution of disguised files

API Reference

FileUploadService

Constructor

Public Methods

File Management:

• save(array $inputs, string $uploadDestination, array $filenames, bool $overwriteExisting = false, bool $generateUniqueFilenames = false, ?FileSaverInterface $fileSaver = null): FileUploadResult

Configuration:

• setAllowedFileTypes(array $allowedFileTypes): void

• getAllowedFileTypes(): array<FileTypeEnum|string>

• setAllowedCategories(array $categories): void

• getAllowedCategories(): array<FileTypeEnum>

• setAllowedExtensions(array $extensions): void

• getAllowedExtensions(): array<string>

• setAllowedMimeTypes(array $mimeTypes): void

• getAllowedMimeTypes(): array<string>

• allowFileType(string|array $fileTypes): void
• disallowFileType(string|array $fileTypes): void

Status Checks:

• isRollbackOnErrorEnabled(): bool
• isHeicConversionEnabled(): bool
• isFileTypeCategoryAllowed(string $fileType): bool
• isFileTypeAllowedByExtension(string $extension): bool
• isUnrestricted(): bool

Utilities:

• getFileTypeCategoryFromExtension(string $extension): FileTypeEnum|string
• getRestrictionDescription(): string
• cleanFilename(string $filename, bool $removeUnderscores = false): string

Static Methods

• getAvailableFileTypeCategories(): array

FileUploadResult

Properties:

• public readonly array $successfulFiles - Array of successfully uploaded file paths / storage identifiers (strings)
• public readonly array $successfulUploads - Array of FileUploadSuccess objects for each successful file
• public readonly array $errors - Array of upload errors
• public readonly int $totalFiles - Total number of files attempted
• public readonly int $successfulCount - Number of successfully uploaded files

Methods:

• hasErrors(): bool
• isCompleteSuccess(): bool
• hasSuccessfulUploads(): bool
• getErrorMessages(): array
• getErrorForFile(string $filename): ?FileUploadError

FileUploadError

Properties:

• public readonly string $filename - The filename that caused the error
• public readonly string $message - The error message
• public readonly string $code - The error code (optional, defaults to empty string)

Methods:

• getDescription(): string

FileUploadSuccess

One successfully processed and saved upload. Filename fields are not aliases.

Properties:

• public readonly ?string $originalFilename - Untrusted provenance: raw $_FILES['name'] when present; null for data URIs. May contain unsafe client-supplied text. Never use as a filesystem path, stored filename, or Content-Disposition value. Never treat as sanitized output. Exists only to record what the client originally supplied.
• public readonly string $requestedFilename - Caller filenames[] value for this slot, before sanitization, collision resolution, and conversion
• public readonly string $storedFilename - Package-produced logical/sanitized final filename after processing. Independent of storedPath. This is the appropriate filename metadata for the processed artifact.
• public readonly string $storedPath - Opaque saver-returned storage identifier. May have a completely different basename than storedFilename. Do not parse this value to recover filename, extension, MIME type, or size.
• public readonly string $extension - Final processed-file extension derived from storedFilename (lowercase, no dot)
• public readonly ?string $mimeType - MIME type of the bytes handed to the saver
• public readonly ?int $sizeBytes - Byte length of the file handed to the saver
• public readonly bool $wasConverted - true only when the stored artifact is a transformed version of the input (for example a successful HEIC → JPEG conversion)
• public readonly int $inputIndex - 0-based index in the expanded input list

Architecture

The service is built with a clean separation of concerns:

• FileUploadService: Main orchestrator and public API
• FileServiceValidator: Handles file validation and type checking
• FileCollisionResolver: Manages filename collision resolution
• FileUploadSave: Handles actual file processing and saving operations
• FileSaverInterface: Pluggable storage backend interface
• FilesystemSaver: Default filesystem storage implementation
• CloudStorageSaver: Example cloud storage implementation
• Enum Classes: Type-safe constants and enumerations (FileTypeEnum, CollisionStrategyEnum, UploadErrorCodeEnum, SupportedFileTypesEnum)
• DTO Classes: Specialized data transfer objects (FileUploadDTO, DataUriDTO)
• Result objects: FileUploadResult, FileUploadSuccess, FileUploadError
• Utils: Utility classes (FilenameSanitizer)

Storage Backend Interface

The service uses the FileSaverInterface to abstract file storage operations, allowing for different storage backends:

• FilesystemSaver: Local filesystem storage (included)
• Cloud Storage: AWS S3, Google Cloud Storage, Azure Blob Storage (implementations can be added)
• Custom Storage: Any storage system can be implemented by implementing FileSaverInterface

The interface provides methods for:

• saveFile(string $source, string $targetPath, bool $overwriteExisting = false): string
• resolveTargetPath(string $uploadDestination, string $filename): string
• ensureUploadDestinationExists(string $uploadDestination): void
• fileExists(string $targetPath): bool
• deleteFile(string $targetPath): bool
• getBasePath(): string

Testing

The package includes comprehensive test coverage with PHPUnit:

License

MIT - See LICENSE file for details.