PHPackages initphp/upload - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [File & Storage](/categories/file-storage) 4. / 5. initphp/upload ActiveLibrary[File & Storage](/categories/file-storage) initphp/upload ============== Validate and store uploaded files on local disk, FTP/FTPS or Amazon S3 through a single adapter-based API. v2.0.0(3w ago)0391MITPHPPHP >=8.0CI passing Since Feb 19Pushed 3w ago1 watchersCompare [ Source](https://github.com/InitPHP/Upload)[ Packagist](https://packagist.org/packages/initphp/upload)[ RSS](/packages/initphp-upload/feed)WikiDiscussions main Synced today READMEChangelog (2)Dependencies (3)Versions (6)Used By (1) InitPHP Upload ============== [](#initphp-upload) Validate and store uploaded files on local disk, FTP/FTPS or Amazon S3 through a single, adapter-based API. [![CI](https://github.com/InitPHP/Upload/actions/workflows/ci.yml/badge.svg)](https://github.com/InitPHP/Upload/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/49805dc93ac9ed91f25b28d0cfc5e2ffecbb562ae2628adb3b2edb8bab309f26/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f75706c6f61642f76)](https://packagist.org/packages/initphp/upload) [![Total Downloads](https://camo.githubusercontent.com/63d3be5c401a24567ec7dd28f71e130510f5ea28d5c6f839eb1271abbb4f8afa/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f75706c6f61642f646f776e6c6f616473)](https://packagist.org/packages/initphp/upload) [![License](https://camo.githubusercontent.com/0a0fe3c97d6f3523c41e50b77004f1908bc028da540a9f58f95b509608cffde2/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f75706c6f61642f6c6963656e7365)](https://packagist.org/packages/initphp/upload) [![PHP Version Require](https://camo.githubusercontent.com/533c1408b22af36cf594a2ed62d3f9b9c83c2ad836c70020c079a6888fafca46/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f75706c6f61642f726571756972652f706870)](https://packagist.org/packages/initphp/upload) Requirements ------------ [](#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`](https://packagist.org/packages/aws/aws-sdk-php) — only for the S3 adapter Installation ------------ [](#installation) ``` composer require initphp/upload ``` For S3 uploads, also install the AWS SDK: ``` composer require aws/aws-sdk-php ``` Quick start ----------- [](#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`](docs/exceptions.md). Loading files ------------- [](#loading-files) CallReturnsPurpose`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 -------- [](#adapters) All three adapters share the same API — only the credentials differ. The optional second constructor argument is the validation options, identical across adapters. AdapterCredentialsNotes[`LocalAdapter`](docs/local-adapter.md)`dir`, `url`Creates missing destination directories.[`FTPAdapter`](docs/ftp-adapter.md)`host`, `port`, `username`, `password`, `timeout`, `url`, `passive`, `ssl`Binary mode, passive by default, optional FTPS.[`S3Adapter`](docs/s3-adapter.md)`key`, `secret_key`, `region`, `bucket`, `ACL`, `version`Requires `aws/aws-sdk-php`.### The `to($target)` argument [](#the-totarget-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 → `/avatars/2026/` - FTP → `/avatars/2026/` (directories created as needed) - S3 → object key `avatars/2026/` in the configured bucket Call `to()` with no argument to store the file at the destination root. Validation options ------------------ [](#validation-options) Pass these as the second constructor argument of any adapter (an empty array or `0` means "no restriction"): OptionTypeMeaning`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 -------- [](#renaming) ``` $file->rename('profile'); // keeps the original extension $upload->setFile($file)->to(); // stored as profile.jpg ``` Documentation ------------- [](#documentation) Full guides with examples live in [`docs/`](docs/README.md): - [Getting started](docs/getting-started.md) - [The `File` object](docs/the-file-object.md) - [Validation](docs/validation.md) - [Local adapter](docs/local-adapter.md) - [FTP adapter](docs/ftp-adapter.md) - [S3 adapter](docs/s3-adapter.md) - [Exceptions](docs/exceptions.md) Contributing ------------ [](#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 ------- [](#credits) - [Muhammet ŞAFAK](https://www.muhammetsafak.com.tr) <> License ------- [](#license) Copyright © 2023 InitPHP — released under the [MIT License](./LICENSE). ### Health Score 43 — FairBetter than 89% of packages Maintenance95 Actively maintained with recent releases Popularity7 Limited adoption so far Community9 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~402 days Total 4 Last Release 25d ago Major Versions v1.x-dev → v2.0.02026-06-08 PHP version history (2 changes)1.0PHP >=7.4 v2.0.0PHP >=8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/4b6b34f3ac8938d8ee52ba3bd260680855dc5715c7b2929d9380de30d15a67dd?d=identicon)[muhammetsafak](/maintainers/muhammetsafak) --- Top Contributors [![muhammetsafak](https://avatars.githubusercontent.com/u/104234499?v=4)](https://github.com/muhammetsafak "muhammetsafak (3 commits)") --- Tags adapteraws-s3file-uploadfilesystemftpftpsinitphpphps3uploadftpfilesystems3awsadapteruploadfile-uploadinitphp ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/initphp-upload/health.svg) ``` [![Health](https://phpackages.com/badges/initphp-upload/health.svg)](https://phpackages.com/packages/initphp-upload) ``` ### Alternatives [league/flysystem File storage abstraction for PHP 13.6k679.9M2.5k](/packages/league-flysystem)[league/flysystem-aws-s3-v3 AWS S3 filesystem adapter for Flysystem. 1.7k285.7M1.0k](/packages/league-flysystem-aws-s3-v3)[creocoder/yii2-flysystem The flysystem extension for the Yii framework 2931.7M63](/packages/creocoder-yii2-flysystem)[league/flysystem-async-aws-s3 AsyncAws S3 filesystem adapter for Flysystem. 2812.1M44](/packages/league-flysystem-async-aws-s3)[eddturtle/direct-upload Composer Package to build an AWS Signature ready to Direct Upload to S3 88756.7k2](/packages/eddturtle-direct-upload)[silverstripe/s3 Adds SilverStripe support for using the S3 adapter for Flysystem 19355.2k1](/packages/silverstripe-s3) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)