Skip to content

Latest commit

 

History

History
176 lines (123 loc) · 6.82 KB

index.md

File metadata and controls

176 lines (123 loc) · 6.82 KB
Raw

Getting started

The OneupUploaderBundle is a Symfony2 bundle developed and tested for versions 2.4+. This bundle does only provide a solid backend for the supported types of Javascript libraries. It does however not provide the assets itself. So in order to use any uploader, you first have to download and integrate it by yourself.

Prerequisites

This bundle is tested using Symfony 3.3+.

With Symfony 2.3
If you want to use the bundle with Symfony 2.3, head over to the documentation for 1.3.x.

With Symfony 2.4.x - 2.8.x
If you want to use the bundle with Symfony 2.4.x - 2.8.x, head over to the documentation for 1.9.x.

Translations

If you wish to use the default texts provided with this bundle, you have to make sure that you have translator enabled in your configuration file.

# app/config/config.yml

framework:
    translator: ~

Installation

Perform the following steps to install and use the basic functionality of the OneupUploaderBundle:

  • Download OneupUploaderBundle using Composer
  • Enable the bundle
  • Configure the bundle
  • Prepare your frontend

Step 1: Download the OneupUploaderBundle

Add OneupUploaderBundle to your composer.json using the following construct:

$ composer require oneup/uploader-bundle

Composer will install the bundle to your project's vendor/oneup/uploader-bundle directory.

Step 2: Enable the bundle

Enable the bundle in the kernel:

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Oneup\UploaderBundle\OneupUploaderBundle(),
    );
}

Step 3: Configure the bundle

This bundle was designed to just work out of the box. The only thing you have to configure in order to get this bundle up and running is a mapping.

# app/config/config.yml

oneup_uploader:
    mappings:
        gallery:
            frontend: dropzone # or any uploader you use in the frontend

To enable the dynamic routes, add the following to your routing configuration file.

#  app/config/routing.yml

oneup_uploader:
    resource: .
    type: uploader

The default directory that is used to upload files to is web/uploads/{mapping_name}. In case you want to avoid a separated mapping folder, you can set root_folder: true and the default directory will be web/uploads.

# app/config/config.yml

oneup_uploader:
    mappings:
        gallery:
            root_folder: true

It was reported that in some cases this directory was not created automatically. Please double check its existance if the upload does not work for you. You can improve the directory structure checking the "Change the directory structure".

If you want to use your own path, for example /data/uploads :

# app/config/config.yml

oneup_uploader:
    mappings:
        gallery:
            storage:
                directory: "%kernel.root_dir%/../data/uploads/"

Step 4: Check if the bundle is working correctly

No matter which JavaScript library you are going to use ultimately, we recommend to test the bundle with Dropzone first, since this one features the easiest setup process:

  1. Install Dropzone
  2. Drag a file onto the dashed rectangle. The upload should start immediately. However, you won't get any visual feedback yet.
  3. Check your web/uploads/gallery directory: If you see the file there, the OneupUploaderBundle is working correctly. If you don't have that folder, create it manually and try again.

Step 5: Prepare your real frontend

Now it's up to you to decide for a JavaScript library or write your own. Be sure to connect the corresponding endpoint property to the dynamic route created from your mapping. To get a url for a specific mapping you can use the oneup_uploader.templating.uploader_helper service as follows:

$helper = $this->container->get('oneup_uploader.templating.uploader_helper');
$endpoint = $helper->endpoint('gallery');

or in a Twig template you can use the oneup_uploader_endpoint function:

{{ oneup_uploader_endpoint('gallery') }}

So if you take the mapping described before, the generated route name would be _uploader_gallery. Follow one of the listed guides to include your frontend:

Next steps

After installing and setting up the basic functionality of this bundle you can move on and integrate some more advanced features.

FAQ

I want to use a frontend library you don't yet support

This is absolutely no problem, just follow the instructions given in the corresponding documentation file. If you think that others could profit of your code, please consider making a pull request. I'm always happy for any kind of contribution.

Why didn't you implement the delete feature provided by Fine Uploader?

FineUploaders delete Feature is using generated unique names we would have to store in order to track down which file to delete. But both the storage and the deletetion of files are tight-coupled with the logic of your very own implementation. This means we leave the delete Feature open for you to implement. Information on how the route must be crafted can be found on the official documentation and on the blog of Fine Uploader.

Why didn't you implement the delete feature provided by another library?

See the answer to the previous question and replace FineUploader by the library you have chosen.