README

This code is part of the SymfonyContrib community.

Symfony2 FileFieldBundle

Provides an advanced file upload form field.

###Extended by:

ImageFieldBundle

###Features:

Highly extensible & customizable.
Single and Multiple uploads.
Use custom forms to collect data about the file.
Events fired before, during, and after upload(s).
Allows integration of external asset management systems, S3, CDNs, etc.
Provides file icons.
Ajax uploads.
Progress bars.
Uses jQuery File Upload
...and more.

Installation

Installation is similar to a standard bundle. http://symfony.com/doc/current/cookbook/bundles/installation.html

Add bundle to composer.json: https://packagist.org/packages/symfonycontrib/filefield-bundle
Add bundle to AppKernel.php:

new SymfonyContrib\Bundle\FileFieldBundle\FileFieldBundle(),

Include the routing file:

# app/config/routing.yml
filefield:
    resource: "@FileFieldBundle/Resources/config/routing.yml"

jQuery is required but not provided by this bundle.
Include JS files (order is important):
- 'bundles/filefield/js/vendor/jquery.ui.widget.js' (only required if jQuery UI is not installed)
- 'bundles/filefield/js/jquery.iframe-transport.js'
- 'bundles/filefield/js/jquery.fileupload.js'
- 'bundles/filefield/js/jquery.fileupload-process.js'
- 'bundles/filefield/js/jquery.fileupload-validate.js'
- 'bundles/filefield/js/jquery.filefield-ui.js'
- 'bundles/filefield/js/filefield.js'
Include CSS file
- 'bundles/filefield/css/jquery.fileupload-ui.css'

Configure

By default the bundle loads a form template to theme the default fields. If you want to customize filefield themeing, you can disable loading of the default template by setting

# app/config/parameters.yml
filefield.load_form_template: false

Usage Examples

More examples

Simple single file upload backed by an array:

// Only URI is required.
$data = [
    'name'      => 'examplefile.txt',
    'mime_type' => 'text/plain',
    'size'      => 50,
    'uri'       => '/uploads/examplefile.txt',
];

...

// These are the only two required options but there are many more.
$builder->add('file', 'filefield', [
    'upload_dir' => '/absolute/system/path/to/upload/dir/web/uploads',
    'uri'        => '/uploads/',
]);

Simple multi-file upload backed by an array of File objects.

$data = [
    new File('/path/to/file'),
    new File('/path/to/file'),
];

...

$builder->add('files', 'filefield', [
    'upload_dir'   => '/absolute/system/path/to/upload/dir/web/uploads',
    'uri'          => '/uploads/',
    'multiple'     => true,
    'limit'        => 2,
    'allow_add'    => true,
    'allow_delete' => true,
]);

Architecture

At its core, FileFieldBundle only takes care of uploading the file from the browser to a server. This means that most of the display portion of the file in the form is offloaded to some other form that is used as a sub-form very much like the core collection form field.

However, FileFieldBundle does provide a simple display form type that is used by default if no other form type is provided. This form type simply displays the filename(linked to the file), a file icon representing the mime type, and the file size.

Field Options

multiple: (boolean) (Default: false) Whether this field allows more than 1 upload.
limit: (int) (Default: 1) Number of files allowed to upload if multiple is set to true.
upload_dir: (string) (Default: '') System path to upload the file to.
uri: (string) (Default: '') The URI the browser will use to access the file.
js_options: (array) (Default: []) Array of options to pass to jQuery File Upload.
preview_type: (string) (Default: null) Name of preview template to use.
type: (string) (Default: 'filefield_simple') Name of form type to use for display.
options: (array) (Default: []) Array of options to pass to sub-form type.
include_filefield_options: (boolean) (Default: true) Whether to include all of the parent filefield options in the sub-form options.
allow_add: (boolean) (Default: false) Whether to allow adding of files when multiple is set to true.
allow_delete: (boolean) (Default: false) Whether to allow removing of files when multiple is set to true.
string_transformer: (boolean) (Default: true) Whether to use the string to array transformer with single fields.

symfonycontrib / filefield-bundle

Maintainers

Details