symfonycontrib/filefield-bundle

Symfony2 Advanced File Field Bundle

Installs: 56

Dependents: 2

Stars: 2

Watchers: 1

Language: JavaScript

v1.0.0-alpha.4 2015-06-01 16:54 UTC

README

This code is part of the SymfonyContrib community.

Provides an advanced file upload form field.

Extended by:

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

new SymfonyContrib\Bundle\FileFieldBundle\FileFieldBundle(),
  • 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.

How to Extend, Integrate, and Customize