initphp/upload

Validate and store uploaded files on local disk, FTP/FTPS or Amazon S3 through a single adapter-based API.

v2.0.0 2026-06-08 18:50 UTC

Requires

• php: >=8.0
• ext-fileinfo: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.65
• phpstan/phpstan: ^1.12 || ^2.1
• phpunit/phpunit: ^9.6

Suggests

• ext-ftp: Required by the FTP adapter (InitPHP\Upload\Adapters\FTPAdapter).
• aws/aws-sdk-php: Required by the S3 adapter (InitPHP\Upload\Adapters\S3Adapter).

MIT

• Muhammet ŞAFAK

• filesystem
• s3
• upload
• adapter
• aws
• ftp
• file-upload
• initphp

README

Validate and store uploaded files on local disk, FTP/FTPS or Amazon S3 through a single, adapter-based API.

Requirements

• PHP 8.0 or higher
• ext-fileinfo (used to detect the real MIME type of a file)
• ext-ftp — only for the FTP adapter
• aws/aws-sdk-php — only for the S3 adapter

Installation

composer require initphp/upload

For S3 uploads, also install the AWS SDK:

composer require aws/aws-sdk-php

Quick start

require 'vendor/autoload.php';

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

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

$upload = new Upload($adapter);

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

    if ($stored !== false) {
        echo 'Uploaded to: ' . $stored->getURL();
    }
}

File::setPost('photos') reads $_FILES['photos'] and returns a normalized File[], whether the field uploaded one file or many. to() validates the file, stores it, and returns the stored File (with its public URL set) or false if the underlying write failed. Any validation or transfer problem is thrown as an UploadException.

Loading files

Call	Returns	Purpose
File::setPost(string $key)	File[]	Normalize $_FILES[$key] (single or multiple) into File objects.
File::setPath(string $path)	File	Wrap an existing file already on disk.

A file loaded with setPath() is copied to its destination (the source is left in place); a real HTTP upload is moved with move_uploaded_file().

Adapters

All three adapters share the same API — only the credentials differ. The optional second constructor argument is the validation options, identical across adapters.

Adapter	Credentials	Notes
LocalAdapter	dir, url	Creates missing destination directories.
FTPAdapter	host, port, username, password, timeout, url, passive, ssl	Binary mode, passive by default, optional FTPS.
S3Adapter	key, secret_key, region, bucket, ACL, version	Requires aws/aws-sdk-php.

The to($target) argument

$target means the same thing in every adapter: a destination path/key prefix. to('avatars/2026') stores the file under that sub-path:

• Local → <dir>/avatars/2026/<name>
• FTP → <remote>/avatars/2026/<name> (directories created as needed)
• S3 → object key avatars/2026/<name> in the configured bucket

Call to() with no argument to store the file at the destination root.

Validation options

Pass these as the second constructor argument of any adapter (an empty array or 0 means "no restriction"):

Option	Type	Meaning
allowed_extensions	string[]	Allowed file extensions, matched case-insensitively against the original file name.
allowed_mime_types	string[]	Allowed MIME types, matched against the real type detected with finfo (not the client-supplied one).
allowed_max_size	int	Maximum size in bytes.

A file that violates any restriction — or whose upload errored — makes to() throw an UploadException.

Renaming

$file->rename('profile');          // keeps the original extension
$upload->setFile($file)->to();     // stored as profile.jpg

Documentation

Full guides with examples live in docs/:

• Getting started
• The File object
• Validation
• Local adapter
• FTP adapter
• S3 adapter
• Exceptions

Contributing

Bug reports and pull requests are welcome. CI runs PHP-CS-Fixer, PHPStan (max level) and PHPUnit across PHP 8.0–8.4; run the same bundle locally with:

composer ci

Credits

• Muhammet ŞAFAK <[e-mail]>

License

Copyright © 2023 InitPHP — released under the MIT License.