Home

InitPHP Upload — Wiki

Welcome to the official documentation for initphp/upload — a small, adapter-based file-upload library for PHP 8.0+.

It validates an uploaded (or local) file and stores it on local disk, an FTP/FTPS server, or Amazon S3 through one consistent API. Swap the backend without touching your upload code.

composer require initphp/upload

use InitPHP\Upload\Upload;
use InitPHP\Upload\File;
use InitPHP\Upload\Adapters\LocalAdapter;

$upload = new Upload(new LocalAdapter([
    'dir' => __DIR__ . '/uploads/',
    'url' => 'https://example.com/uploads/',
], [
    'allowed_extensions' => ['jpg', 'png', 'webp'],
    'allowed_max_size'   => 2 * 1024 * 1024, // 2 MB
]));

foreach (File::setPost('photos') as $file) {
    $stored = $upload->setFile($file)->to();

    if ($stored !== false) {
        echo $stored->getURL(); // https://example.com/uploads/<name>
    }
}

The package in one table

Symbol	Role
File	A value object describing one file to upload. Build a list from $_FILES with File::setPost(), or wrap a path with File::setPath().
Upload	A thin, type-safe decorator over an adapter — the object you call setFile() and to() on.
LocalAdapter / FTPAdapter / S3Adapter	Storage backends. Same API, different credentials.
UploadException	Base exception for validation and storage failures.

Start here

• New to the package? Read Installation, then Quick Start.
• Want the mental model? Core Concepts explains File, adapters, the Upload decorator and the $target argument.
• Restricting what can be uploaded? Validation covers extensions, MIME types and size limits.
• Picking a backend? Local, FTP and S3 each have a dedicated page.
• Looking for a specific method? The full API Reference lists every public member.
• Securing uploads? Security Best Practices is required reading before going to production.

What you get

• One API, three backends. Local disk, FTP/FTPS and Amazon S3 all implement the same UploadAdapterInterface. Your code only changes which adapter it constructs.
• Real validation. Restrict by extension (case-insensitive), by the real MIME type detected with finfo (not the spoofable client header), and by size. See Validation.
• Correct file handling. The extension comes from the original client name, not the temporary path; HTTP uploads are moved, path-loaded files are copied; destination directories are created automatically.
• Multi-file ready. File::setPost() normalizes single- and multi-file form fields into one File[].
• One exception family. Validation and backend failures throw UploadException; a single catch covers them all.

At a glance — behaviour

You write	What happens
File::setPost('avatar')	$_FILES['avatar'] → File[] (single or multiple)
$upload->setFile($file)->to()	validate, then store at the destination root
->to('avatars/2026')	store under the avatars/2026/ path/key prefix
$file->rename('profile')	store as profile.<originalExtension>
store succeeds	returns the File, with getURL() set
store write fails	returns false
validation fails	throws UploadException

Package metadata

• License: MIT
• Minimum PHP: 8.0
• Required extensions: ext-fileinfo
• Optional: ext-ftp (FTP adapter), aws/aws-sdk-php (S3 adapter)
• Packagist: initphp/upload
• Source: github.com/InitPHP/Upload
• Issues: github.com/InitPHP/Upload/issues
• Discussions: github.com/orgs/InitPHP/discussions

If something in this wiki is unclear, wrong, or out of date, open an issue — documentation fixes are merged eagerly.