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

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.

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"):

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 <info@muhammetsafak.com.tr>

License

Copyright © 2023 InitPHP — released under the MIT License.