Download the PHP package locaine/lcn-file-uploader-bundle without Composer

LcnFileUploaderBundle

Easy ajax file uploads for Symfony 2. MIT License.

Inspired by punkave/symfony2-file-uploaderbundle (no longer maintained)

Introduction

This bundle provides enhanced file upload widgets based on the BlueImp jQuery file uploader package. Both drag and drop and multiple file selection are fully supported in compatible browsers.

The uploader delivers files to a folder that you specify. If that folder already contains files, they are displayed side by side with new files, as existing files that can be removed.

The bundle can automatically scale images to sizes you specify. The provided synchronization methods make it possible to create forms in which attached files respect "save" and "cancel" operations.

Installation

Step 1: Install dependencies

jQuery

Make sure that jQuery is included in your html document:

Underscore.js

Make sure that Underscore.js is included in your html document

Step 2: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 3: Enable the Bundle

Then, enable the bundle by adding the following line in the app/AppKernel.php file of your project:

Usage

Add/Edit/Remove uploads

Controller Code

If you need to upload files to not yet persisted entities (during creation) then you need to deal with temporary editIds which makes things a little bit more complicated.

In this example, we assume that you want to attach one or more uploaded image files to an existing entity.

The LcnFileUploader needs a unique folder for the files attached to a given entity.

Fetching $entity and validating that the user is allowed to edit that particular entity is up to you.

In Your Layout

You can skip this step if you are using LcnIncludeAssetsBundle.

Include these stylesheets and scripts in your html document:

Or you can use assetic in your twig template:

The exact position and order does not matter. However, for best performance you should include the link tags in your head section and the script tag right before the closing body tag.

In the Edit Template

====================

Now include the upload widget anywhere on your page:

Full example:

Retrieving existing Uploads

Retrieve File Names

You can easily obtain a list of the names of all files stored in a given folder:

However, there is a performance cost associated with accessing the filesystem. If you run into performance problems you might want to keep a list of attachments in a Doctrine table or some cache layer.

Retrieve File URLs

You can easily obtain a list of urls of all files stored in a given folder:

However, there is a performance cost associated with accessing the filesystem. If you run into performance problems you might want to keep a list of attachments in a Doctrine table or some cache layer.

Retrieve Thumbnail URLs

If you are dealing with image uploads, you can pass a defined size name:

The image sizes are defined as lcn_file_uploader.sizes parameter:

For advanced image resizing and optimization, you can optionally configure an image proxy (e.g.imgix.net).

~imageUrl~ gets replaced with the url to the uploaded image source. The parameters array is used to pass additional query string parameters. ~max_width~ and ~max_height~ get replaced with the corresponding values defined for the given image size.

If you are using an image proxy, you can remove the folder setting if you do not want to store the resized version on your own disk at all. However, the "original" and "thumbnail" sizes still need a folder setting!

Important: You also need to explicitly enable the image proxy using the parameter lcn_file_uploader.image_proxy_enabled:

This is especially helpful if you only want want to leverage the proxy in prod environments.

Advanced Usage

Setting the allowed file types

You can specify custom file types to divert from the default ones (which are defined in Resources/config/services.yml) by either specifying them in your handleFileUploadAction method or in parameters.yml.

Per Widget in corresponding handleFileUploadAction: $this->get('lcn.file_uploader')->handleFileUpload(array( 'folder' => 'temp-lcn-file-uploader-demo/' . $editId, 'allowed_extensions' => array('zip', 'rar', 'tar') ));

Globally in parameters.yml: If you have the Symfony standard edition installed you can specify them in app/config/parameters.yml:

file_uploader.allowed_extensions:
    - zip
    - rar
    - tar

Removing Files

When an entity gets deleted you should delete all of the attachments, as well.

You can do this as follows:

$this->get('lcn.file_uploader'')->removeFiles(array('folder' => 'lcn-file-uploader-demo/' . $entity->getId()));

You probably might want to do that in a doctrine lifecycle preRemove event listener.

Removing Temporary Files

You should make sure that the temporary files do not eat up your storage.

The following Command Removes all temporary uploads older than 120 minutes

You might want to setup a cronjob that automatically executes that command in a given interval.

Changing the generated file names

This Bundle comes with three predefined FileNamer-Services:

• Sanitize: Make file names url-friendly (Default)
• Original: Use original file names as uploaded
• Hash: generate hash based on the original filename

You can define the FileNamer in the service definition:

Overriding templates

app/Resources/views/Form/lcnFileUploaderWidget.html.twig:

in your edit.html.twig:

More Configuration Parameters

Most of the options can be configured by overriding the parameters defined in Resources/config/services.yml in this bundle.

Limitations

This bundle accesses the file system via the glob() function. It won't work out of the box with an S3 stream wrapper.

Syncing files back and forth to follow the editId pattern might not be agreeable if your attachments are very large. In that case, don't use the editId pattern. One alternative is to create objects immediately in the database and not show them in the list view until you mark them live. This way your edit action can use the permanent id of the object as part of the folder option, and nothing has to be synced. In this scenario you should probably move the attachments list below the form to hint to the user that there is no such thing as "cancelling" those actions.