ns/file-upload-bundle

This bundle provides a simple file upload bundle

File Upload Bundle

A simple bundle to handle file uploads and url generation., _(*1)

Install

Via Composer, _(*2)

$ composer require ns/file-upload-bundle

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., _(*3)

# 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, _(*4)

You are free to implement your own file and/or directory namers. Simply implement the NS\FileUploadBundle\Namer\FileNamerInterface or NS\FileUploadBundle\Namer\DirectoryNamerInterface., _(*5)

The bundle comes with the following file naming strategies., _(*6)

OriginalNamer

This stores the uploaded file using the name provided by the client when uploaded. Service id @ns_file.namer.client_original, _(*7)

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, _(*8)

RandomNamer

This renames the file to a random string but keeps the original file extension. Service id @ns_file.namer.random, _(*9)

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, _(*10)

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., _(*11)

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., _(*12)

Downloads / Twig

There is a twig helper which will allow the generation of download urls for any given file., _(*13)

    <a href="{{ file_path('applicant', 'funny-cat-image_xx12xa.jpg', 'user@example.com') }}">Download</a>

Provides a link to this file., _(*14)

License

MIT, see LICENSE., _(*15)