Download the PHP package phatnt93/php-upload-helper without Composer

PHP Upload Helper

English | Tiếng Việt

A modern, secure, and fluent PHP file upload and image processing library with first-class multi-file array support, inspired by the legendary verot/class.upload.php.

Table of Contents

1. Why Use PHP Upload Helper?
2. Key Advantages Over class.upload.php
3. System Requirements & Setup
4. Installation
5. Quick Start
   • Single File Upload
   • Multi-File Array Upload (First-Class Support)
   • Deeply Nested Multi-Dimensional Form Upload
6. Real-World Practical Examples
   • Example 1: User Profile Avatar with Automatic Crop & WebP
   • Example 2: E-Commerce Product Gallery with Atomic Batch Rollback
   • Example 3: Secure Document (PDF/Docx) Storage with Slug Naming
   • Example 4: Sanitized SVG Vector Upload (Stored-XSS Immunity)
   • Example 5: REST API / SPA Upload via Base64 or PSR-7
7. Comprehensive Action Pipeline & API Reference
   • Upload Factory API
   • Security & Validation Layer
   • File Naming Strategies
   • Storage Engine & Collision Handling
   • Image Manipulation (Resize Modes, Crop, Rotate, Watermark)
   • Format Conversion & Compression
   • Color Filters & Visual Effects
   • SingleResult & ProcessedFile API
   • BatchUploadBuilder & BatchResult API
   • Multi-Variant Pipeline (Thumbnails & Previews)
   • Lifecycle Hooks & Event Callbacks
8. Framework Integration Guides
   • Vanilla PHP Web Form
   • Laravel Integration
   • Symfony Integration
   • Phalcon Integration
   • Slim / PSR-7 Frameworks
9. Internationalization & Error Codes Catalog
10. Security Best Practices & Server Hardening
11. Feature Comparison with verot/class.upload.php
12. Using with AI Coding Agents
13. Callback Signatures & Extension Contracts
14. FAQ & Troubleshooting
15. Automated Testing & Code Quality
16. License & Credits

1. Why Use PHP Upload Helper?

Handling file uploads in native PHP is notorious for friction and security hazards:

• Chaotic Array Transposition: Native $_FILES splits multiple files into fragmented sub-arrays ($_FILES['photos']['name'][$i]), forcing developers to write repetitive matrix restructuring loops.
• Client Header Trust Vulnerabilities: Checking $_FILES['file']['type'] is insecure because it is an untrusted client header trivially spoofed with cURL or Burp Suite.
• Dangerous Extensions & Code Execution: Attackers easily bypass naive blacklists with .phtml, .php5, .phar, double extensions (shell.php.png), or null-byte injections (shell.php\0.jpg).
• Stored XSS in SVGs: Uploaded SVGs containing <script> or inline onload handlers execute scripts in users' browsers when rendered directly.
• Orphan File Pollution: In batch uploads, if 9 out of 10 files succeed and the 10th fails, native PHP leaves orphan files cluttering storage.
• Verbose GD Syntax: Resizing or watermarking images using procedural GD functions requires dozens of boilerplate lines.

php-upload-helper provides an all-in-one, modern, type-safe Fluent Pipeline that encapsulates input normalization, deep binary sniffing, SVG sanitization, image processing, atomic storage, and batch rollback into elegant, chainable PHP 8.1+ syntax.

2. Key Advantages Over class.upload.php

3. System Requirements & Setup

• PHP Compatibility: PHP >= 8.1 (tested on PHP 8.1, 8.2, 8.3, and 8.4 64-bit).
• Core Extensions:
  • ext-fileinfo: Required for magic bytes binary MIME type inspection.
  • ext-mbstring: Required for multibyte string manipulation, Vietnamese slug conversion, and UTF-8 font text rendering.
  • ext-gd: Required for the default image manipulation engine.
• Optional Extensions:
  • ext-imagick: For advanced image manipulation and vector rendering.
  • ext-exif: For automatic mobile photo orientation based on EXIF camera tags.

4. Installation

Install via Composer into your project:

Ensure your php.ini has adequate upload boundaries:

5. Quick Start

Single File Upload

Multi-File Array Upload (First-Class Support)

Say goodbye to manual foreach matrix restructuring for <input type="file" name="photos[]" multiple>!

Deeply Nested Multi-Dimensional Form Upload

Supports complex form inputs like <input type="file" name="catalog[category][items][0][attachments][]">:

6. Real-World Practical Examples

Example 1: User Profile Avatar with Automatic Crop & WebP

Enforce a clean square avatar, strip harmful metadata, resize to 300x300, and save in modern WebP:

Example 2: E-Commerce Product Gallery with Atomic Batch Rollback

Upload product photos in batch, apply watermarks, convert to progressive JPEG, and rollback if any photo is invalid:

Example 3: Secure Document (PDF/Docx) Storage with Slug Naming

Safely accept resumes or contracts, sanitize filenames (including Vietnamese accents), and auto-increment duplicates:

Example 4: Sanitized SVG Vector Upload (Stored-XSS Immunity)

SVGs can carry malicious <script> tags. With sanitizeSvg(true), the parser strips all scripts, event handlers (onload, onclick), and javascript: URIs before saving:

Example 5: REST API / SPA Upload via Base64 or PSR-7

Accept image uploads from mobile apps, Vue/React Canvas, or PSR-7 HTTP requests:

7. Comprehensive Action Pipeline & API Reference

Upload Factory API

Entry points from the UploadHelper\Upload facade:

Security & Validation Layer

All validation methods are available on UploadBuilder and BatchUploadBuilder:

File Naming Strategies

Storage Engine & Collision Handling

Image Manipulation (Resize Modes, Crop, Rotate, Watermark)

1. Resize Modes

• fit (Default): Proportional scaling so the whole image fits inside $width × $height. Never distorts aspect ratio.
• crop: Scales and centers the image to completely fill the $width × $height box, cropping excess parts.
• pad: Fits the image proportionally inside the box and fills the outer space with $background (e.g. '#FFFFFF').
• stretch: Distorts the image to match the exact dimensions.
• withoutEnlarging(true): Prevents upscaling if original image is smaller than target dimensions.

2. Cropping, Rotating & Orientation

3. Watermarking

Format Conversion & Compression

Color Filters & Visual Effects

SingleResult & ProcessedFile API

Calling ->saveTo() or ->process() on UploadBuilder returns a SingleResult:

BatchUploadBuilder & BatchResult API

Calling ->process() on BatchUploadBuilder returns a BatchResult:

Multi-Variant Pipeline (Thumbnails & Previews)

Generate multiple derivative sizes, formats, or watermarked variants from a single uploaded file without re-uploading:

Lifecycle Hooks & Event Callbacks

Attach hooks to intercept and react during the upload lifecycle:

8. Framework Integration Guides

Vanilla PHP Web Form

Laravel Integration

In your Laravel Controller:

Symfony Integration

In your Symfony Controller:

Phalcon Integration

In your Phalcon Controller:

Slim / PSR-7 Frameworks

9. Internationalization & Error Codes Catalog

Setting the Active Locale

The default locale is English (en); Vietnamese (vi) ships with the library. Missing keys fall back to the active locale → en → the error code itself.

Messages returned by SingleResult::getErrorMessage() are translated with the active locale. Exceptions thrown inside the library always carry an English message; it is kept in getErrors()['context']['reason'] for logging. Unexpected internal errors are reported as ERR_INTERNAL with a generic message so that paths and internals never leak to end users.

Standardized Error Codes

The full message catalog lives in src/I18n/vi.php; both always contain the same keys (enforced by tests). Placeholders such as {extension} are filled from the error context.

10. Security Best Practices & Server Hardening

1. Store Uploads Outside the Web Root: Always store private files outside the public document root (e.g., /storage/uploads instead of /public/uploads) and serve them via a secure streaming controller with access authorization.

2. Disable Script Execution in Upload Folders: If serving directly from Nginx, disable PHP execution in the public upload directory:

   For Apache, place an .htaccess file inside your upload directory:

3. Always Whitelist Extensions: Never use blacklists. Attackers continuously discover new executable suffixes (e.g., .php7, .pht, .shtml, .inc). Always pass explicit whitelists via ->allowedExtensions(['jpg', 'png', 'pdf']).

11. Feature Comparison with verot/class.upload.php

12. Using with AI Coding Agents

If you use AI coding assistants (Claude Code, GitHub Copilot, Cursor, ChatGPT, Codex) in your project, you can provide them with machine-optimized context files:

• Quick LLM Guide: vendor/phatnt93/php-upload-helper/llms.txt (API summary and common copy-paste recipes)
• Deep Technical Reference: vendor/phatnt93/php-upload-helper/llms-full.txt (complete class signatures, 100% error catalog, extensibility interfaces)
• Standalone Examples: examples/ (executable reference scripts covering single file, batch upload, variants, and security)

Prompt Example for Your Project Rules

Add this line to your project's .cursorrules, CLAUDE.md, or AGENTS.md:

"When implementing file uploads or image processing in PHP, use phatnt93/php-upload-helper. Refer to vendor/phatnt93/php-upload-helper/llms.txt for fluent API usage and validation recipes."

13. Callback Signatures & Extension Contracts

All callback signatures in php-upload-helper are strictly typed and committed to backwards-compatibility within major versions:

Custom Extension Interfaces

To extend the library with custom logic:

• Custom Actions: Implement UploadHelper\Contracts\ActionInterface (getName(): string, execute(UploadedFile $file, ActionContext $context): UploadedFile).
• Custom Malware Scanners: Implement UploadHelper\Contracts\ScannerInterface (scan(string $filePath): bool, getThreatName(): ?string).
• Custom Storage Backends: Implement UploadHelper\Contracts\StorageInterface (save(...), delete(...), exists(...)).
• Custom Image Drivers: Implement UploadHelper\Contracts\ImageDriverInterface.

14. FAQ & Troubleshooting

Q: Why do I get an empty $_FILES or immediate UPLOAD_ERR_INI_SIZE?

A: The file exceeds either upload_max_filesize or post_max_size in your active php.ini. Note that post_max_size must always be larger than or equal to upload_max_filesize. For multi-file uploads, post_max_size must be large enough to contain the sum of all files in the batch request.

Q: Why does toWebp() or toAvif() fail on my server?

A: Check if your PHP GD build was compiled with WebP or AVIF support:

If false, install libwebp-dev or libavif-dev and recompile/install the PHP GD extension.

Q: How do I create both a large preview and a small thumbnail from the same uploaded file?

A: Use the built-in multi-variant pipeline:

15. Automated Testing & Code Quality

Run the automated quality and test suites:

16. License & Credits

• License: Licensed under the MIT License.
• Author: Phat Nguyen ([email protected]).
• Inspiration: Special thanks to Colin Verot for the historical verot/class.upload.php.