PHPackages                             ns/file-upload-bundle - 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. ns/file-upload-bundle

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

ns/file-upload-bundle
=====================

This bundle provides a simple file upload bundle

2.0.0(6mo ago)29.8kMITPHPPHP >=8.3

Since Aug 22Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/NobletSolutions/FileUploadBundle)[ Packagist](https://packagist.org/packages/ns/file-upload-bundle)[ RSS](/packages/ns-file-upload-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (8)Versions (16)Used By (0)

File Upload Bundle
==================

[](#file-upload-bundle)

A simple bundle to handle file uploads and url generation.

Install
-------

[](#install)

Via Composer

```
$ composer require ns/file-upload-bundle
```

Configuration
-------------

[](#configuration)

### Define a configuration

[](#define-a-configuration)

Configurations are defined as services. For each naming / file location define a tagged service. You can choose any of the provided file namers, or implement your own. Only one of the second or third parameters are required, however both can be used as well.

```
# services.yml
ns_file.applicant_uploads:
  class: NS\FileUploadBundle\Handler\Config
  arguments: [ "@ns_file.namer.default", "applicant-uploads", "@ns_file.directory_namer.hash" ]
  tags:
    - { name: ns_file.config, config_name: applicant }

```

Given the above configuration. A file uploaded using this configuration would be stored in web/uploads/applicant-uploads/HASH/ClientOriginalName\_RANDSTR.ext

You are free to implement your own file and/or directory namers. Simply implement the NS\\FileUploadBundle\\Namer\\FileNamerInterface or NS\\FileUploadBundle\\Namer\\DirectoryNamerInterface.

The bundle comes with the following file naming strategies.

#### OriginalNamer

[](#originalnamer)

This stores the uploaded file using the name provided by the client when uploaded. Service id **@ns\_file.namer.client\_original**

#### OriginalRandomNamer

[](#originalrandomnamer)

Similar to the OriginalNamer, this will keep the original filename, but inserts random characters and numbers after the name but before the file extension. This is the **default** file namer. Service id **@ns\_file.namer.original\_random**

#### RandomNamer

[](#randomnamer)

This renames the file to a random string but keeps the original file extension. Service id **@ns\_file.namer.random**

#### UniqueHashNamer

[](#uniquehashnamer)

This performs a sha1 hash of the original client name and uses that plus the original file extension. Service id **@ns\_file.namer.unique\_hash**

Usage
-----

[](#usage)

When handling a file upload. Simply request the upload handler service. Pass it the instance of the UploadedFile, the configuration and optionally any additional data that the directory namer will use.

#### Upload Handling

[](#upload-handling)

```
    // $applicantEmailAddress = 'user@example.com';
    // instanceof UploadedFile with clientOriginalName 'funny-cat-image.jpg'
    $sourceFile = $form['somefile']->getData();
    $handler = $this->get('ns_file.upload_handler');

    $destinationFile = $handler->upload('applicant', $sourceFile, $applicantEmailAddress);
```

Based on our example configuration above will take the source file and place it in web/uploads/applicant-uploads/63a710569261a24b3766275b7000ce8d7b32e2f7/funny-cat-image\_xx12xa.jpg. It will then return a File instance for this. You can save the filename however you'd like.

#### Downloads / Twig

[](#downloads--twig)

There is a twig helper which will allow the generation of download urls for any given file.

```
    Download
```

Provides a link to this file.

License
-------

[](#license)

MIT, see LICENSE.

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance66

Regular maintenance activity

Popularity25

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity86

Battle-tested with a long release history

 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 ~239 days

Recently: every ~459 days

Total

15

Last Release

203d ago

Major Versions

0.4.0 → 1.0.02024-05-16

1.0.0 → 2.0.02025-10-27

PHP version history (4 changes)0.1.0PHP >=5.5

0.1.8PHP >=5.5.9|>=7.0.8

1.0.0PHP >=8.1

2.0.0PHP >=8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/bdde326649ba5e420cda4f48355ac3d7f93e0c9b183818fcfc409cbcf51a961d?d=identicon)[gnat](/maintainers/gnat)

---

Top Contributors

[![gnat42](https://avatars.githubusercontent.com/u/325591?v=4)](https://github.com/gnat42 "gnat42 (48 commits)")

---

Tags

bundlefile-uploadphpsymfonysymfony-bundle

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ns-file-upload-bundle/health.svg)

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

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k16.7M310](/packages/easycorp-easyadmin-bundle)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[helios-ag/fm-elfinder-bundle

ElFinder bundle, adds ElFinder file manager to your Symfony project

2814.8M27](/packages/helios-ag-fm-elfinder-bundle)[sonata-project/media-bundle

Symfony SonataMediaBundle

4625.5M71](/packages/sonata-project-media-bundle)[artgris/filemanager-bundle

FileManager is a simple Multilingual File Manager Bundle for Symfony

182420.8k9](/packages/artgris-filemanager-bundle)

PHPackages © 2026

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