PHPackages                             rossriley/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. rossriley/upload

ActiveLibrary[File & Storage](/categories/file-storage)

rossriley/upload
================

Framework agnostic upload library - Forked from siriusphp for PHP 5.3 compatibility

1.2.0(11y ago)318.2k1MITPHPPHP >=5.3

Since Mar 23Pushed 11y ago1 watchersCompare

[ Source](https://github.com/rossriley/upload)[ Packagist](https://packagist.org/packages/rossriley/upload)[ RSS](/packages/rossriley-upload/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (3)Versions (4)Used By (0)

Sirius\\Upload
==============

[](#siriusupload)

[![Build Status](https://camo.githubusercontent.com/0c132926e07fb3b841f9786c5855ff0bb9e3cefaa23bfdf35d842494974bbc10/68747470733a2f2f7472617669732d63692e6f72672f7369726975737068702f75706c6f61642e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/siriusphp/upload)[![Coverage Status](https://camo.githubusercontent.com/3cfbe4a5ab0bd904b531aeb186a6cb9c88e81db675868f867c6adc904282d93e/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f7369726975737068702f75706c6f61642f62616467652e706e673f6272616e63683d6d6173746572)](https://coveralls.io/r/siriusphp/upload?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/d5c0bfdc29cbd7852c200d2ba3ae73aeeb1ab8d3107d576c5fa3cda9764d478d/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f7369726975737068702f75706c6f61642f6261646765732f7175616c6974792d73636f72652e706e673f733d38343038653336633165613032653566383465656336353139643363336631393732623334653363)](https://scrutinizer-ci.com/g/siriusphp/upload/)[![Latest Stable Version](https://camo.githubusercontent.com/07a48a0ed9d0a51d27f1432b4d5a2ec42cabd2c2ff1b4ced7102fd887ea80180/68747470733a2f2f706f7365722e707567782e6f72672f7369726975737068702f75706c6f61642f76657273696f6e2e706e67)](https://packagist.org/packages/siriusphp/upload)[![License](https://camo.githubusercontent.com/cea1460665796c5e5de01e393c082dbce001b171c394cc60421abde7ca8a59b3/68747470733a2f2f706f7365722e707567782e6f72672f7369726975737068702f75706c6f61642f6c6963656e73652e706e67)](https://packagist.org/packages/siriusphp/upload)

Framework agnostic upload handler library.

Features
--------

[](#features)

1. Validates files agains usual rules: extension, file size, image size (wdith, height, ratio). It uses [Sirius Validation](http://github.com/siriusphp/validation) for this purpose.
2. Moves valid uploaded files into containers. Containers are usually local folders but you can implement your own or use other filesystem abstractions like [Gaufrette](https://github.com/KnpLabs/Gaufrette) or [Flysystem](https://github.com/FrenkyNet/Flysystem).

Elevator pitch
--------------

[](#elevator-pitch)

```
use Sirius\Upload\Handler as UploadHandler;
$uploadHandler = new UploadHandler('/path/to/local_folder');

// optional configuration
$uploadHandler->setOverwrite(false); // do not overwrite existing files (default behaviour)
$uploadHandler->setPrefix('subdirectory/append_'); // string to be appended to the file name
$uploadHandler->setAutoconfirm(false); // disable automatic confirmation (default behaviour)

// validation rules
$uploadHandler->addRule('extension', ['allowed' => 'jpg', 'jpeg', 'png'], '{label} should be a valid image (jpg, jpeg, png)', 'Profile picture');
$uploadHandler->addRule('filesize', ['max' => '20M'], '{label} should have less than {max}', 'Profile picture');
$uploadHandler->addRule('imageratio', ['ratio' => 1], '{label} should be a sqare image', 'Profile picture');

$result = $uploadHandler->process($_FILES['picture']); // ex: subdirectory/my_headshot.png

if ($result->isValid()) {
	// do something with the image like attaching it to a model etc
	try {
		$profile->picture = $result->name;
		$profile->save();
		$result->confirm(); // this will remove the uploaded file and it's .lock file
	} catch (\Exception $e) {
		// something wrong happened, we don't need the uploaded picture anymore
		$result->clear();
		throw $e;
	}
} else {
	// image was not moved to the container, where are error messages
	$messages = $result->getMessages();
}
```

One aggregator to rule them all
-------------------------------

[](#one-aggregator-to-rule-them-all)

Sometimes your form may upload multiple files to the server. To reduce the number of `process()`, `clear()` and `confirm()` calls you can use an "upload handler aggregate"

```
use Sirius\Upload\HandlerAggregate as UploadHandlerAggregate;
$uploadHandlerAggregate = new UploadHandlerAggregate();
$uploadHandlerAggregate->addHandler('picture', $previouslyCreatedUploadHandlerForTheProfilePicture);
$uploadHandlerAggregate->addHandler('resume', $previouslyCreatedUploadHandlerForTheResume);

$result = $uploadHandlerAggregate->process($_FILES);

if ($result->isValid()) {
	// do something with the image like attaching it to a model etc
	try {
		$profile->picture = $result['picture']->name;
		$profile->resume = $result['resume']->name;
		$profile->save();
		$result->confirm(); // this will remove the uploaded file and it's .lock file
	} catch (\Exception $e) {
		// something wrong happened, we don't need the uploaded files anymore
		$result->clear();
		throw $e;
	}
} else {
	// image was not moved to the container, where are error messages
	$messages = $result->getMessages();
}
```

You can see the aggregator and handlers in action in the [tests/web/index.php](/siriusphp/upload/blob/master/tests/fixitures/sample_file.jpg)

How it works
------------

[](#how-it-works)

1. Uploaded file is validated against the rules. By default the library will check if the upload is valid (ie: no errors during upload)
2. The name of the uploaded file is sanitized (keep only letters, numbers and underscore and lowercase the result). You may implement your own sanitization function if you want.
3. If overwrite is not allowed, and a file with the same name already exists in the container, the library will prepend the timestamp to the filename.
4. Moves the uploaded file to the container. It also create a lock file (filename + '.lock') so that we know the upload is not confirmed
5. If something wrong happens in your app and you want to get rid of the uploaded file you can `clear()` the uploaded file which will remove the file and its `.lock` file. Only files that have a coresponding `.lock` file attached can be cleared
6. If everything is in order you can `confirm` the upload. This will remove the `.lock` file attached to the upload file.

#### What is "locking"?

[](#what-is-locking)

Usualy application accept file uploads to store them for future use (product images, people resumes etc). But from the time an uploaded file is moved to its container until the actual data is saved there are things that can go wrong (eg: the database goes down). For this reason the `locking` functionality was implemented. This way, even if you're not able to execute the `clear()` method you will be able to look into the container in "spot" the unused files. This feature must be used with care

1. If you want to take advantage of this feature you must use `confirm`
2. If you don't like it, use `$uploadHandler->setAutoconfirm(true)` and all uploaded files will automatically confirmed

Using different containers
--------------------------

[](#using-different-containers)

If you want to store uploaded files in different locations your containers must implement the `Sirius\Upload\Container\ContainerInterface`.

```
$amazonBucket = new AmazonBucket();
$container = new AmazonContainer($amazonBucket);
$uploadHandler = new UploadHandler($container);
```

You can easily create upload containers on top of [Gaufrette](https://github.com/KnpLabs/Gaufrette) or [Flysystem](https://github.com/FrenkyNet/Flysystem).

Important notes
---------------

[](#important-notes)

##### 1. The library makes no assumptions about the "web availability" of the uploaded file.

[](#1-the-library-makes-no-assumptions-about-the-web-availability-of-the-uploaded-file)

Most of the times once you have a valid upload the new file will be reachable on the internet. You may upload your files to `/var/www/public/images/users/` and have the files accessible at `//cdn.domain.com/users/`. It's up to you to make your app work with the result of the upload.

##### 2. You can handle multiple uploads at once if they have the same name

[](#2-you-can-handle-multiple-uploads-at-once-if-they-have-the-same-name)

If you upload multiple files with the same name (eg: ``) but you have to keep in mind that the `process()` and `getMessages()` methods will return arrays

```
$result = $uploadHandler->process($_FILES['pictures']);
// will return a collection of files which implements \Iterator interface
$messages = $result->getMessages();
// may return if the second file is not valid
array(
	'1' => 'File type not accepted'
);
```

In this case the library normalizes the `$_FILES` array as PHP messes up the upload array. It is up to you to decide what you want to do when some files fail to upload (eg: keep the valid files and continue or display error messages for the invalid images)

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity24

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 73.3% 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 ~46 days

Total

3

Last Release

4346d ago

PHP version history (2 changes)1.0.0PHP >=5.4

1.2.0PHP >=5.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/5082?v=4)[Ross Riley](/maintainers/rossriley)[@rossriley](https://github.com/rossriley)

---

Top Contributors

[![rossriley](https://avatars.githubusercontent.com/u/5082?v=4)](https://github.com/rossriley "rossriley (11 commits)")[![adrianmiu](https://avatars.githubusercontent.com/u/1293017?v=4)](https://github.com/adrianmiu "adrianmiu (4 commits)")

---

Tags

validationfileuploadform

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/rossriley-upload/health.svg)

```
[![Health](https://phpackages.com/badges/rossriley-upload/health.svg)](https://phpackages.com/packages/rossriley-upload)
```

###  Alternatives

[kartik-v/yii2-widget-fileinput

An enhanced FileInput widget for Bootstrap 3.x, 4.x & 5.x with file preview, multiple selection, and more features (sub repo split from yii2-widgets)

2286.8M95](/packages/kartik-v-yii2-widget-fileinput)[delight-im/file-upload

Simple and convenient file uploads — secure by default

7210.7k2](/packages/delight-im-file-upload)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)