floppy / bundle
Floppy is a file storage library. This library adds fine support to use FloppyServer instance to Symfony2 apps.
Requires
- doctrine/doctrine-bundle: *
- doctrine/orm: ~2.0
- floppy/client: >=0.1.0,<0.2.0
- symfony/form: ~2.1
- symfony/framework-bundle: ~2.1
- symfony/twig-bridge: ~2.1
This package is not auto-updated.
Last update: 2024-11-05 02:53:35 UTC
README
FloppyBundle provides few additional integration points with FloppyServer library. Before reading this documentation, you should read documentation for FloppyServer and FloppyClient first.
The main goal of Floppy-family libraries is to make dealing with every aspect of files as easy as possible. Floppy-family libraries improve dealing with: file uploading, file storing, generating various file versions (thumbnails, watermarks etc.), representing files in Entities and more.
Documentation
ToC
Quick tour
-
Configure your floppy server (shown in floppy-server doc)
-
Add floppy/bundle to your composer and register this bundle in AppKernel:
composer.json (stable version is recommended, "*" as a version is only an example).
"require": {
...
"zineinc/floppy-bundle": "*"
...
}
app/AppKernel.php:
public function registerBundles() { return array( //... new Floppy\Bundle\FloppyBundle(), //... ); }
...config.yml floppy: endpoint: protocol: http host: your-floppy-server-host.com path: / secret_key: your-super-secret-key-the-same-key-as-in-server #similar syntax as in LiipImagineBundle / AvalancheImagineBundle #the same filters and options available as in LiipImagineBundle filter_sets: some_thumbnail: quality: 95 thumbnail: size: [50, 50] #add form theme for form fields defined by this bundle twig: form: resources: - "FloppyBundle::form.html.twig" ...routing.yml FloppyBundle: resource: "@FloppyBundle/Resources/config/routing.yml" prefix: "/floppy"
And that's all, next points explain how to use features of this bundle.
- Define your form model or entity:
namespace ... use Floppy\Common\FileId; use Doctrine\ORM\Mapping as ORM; class Document { /** * @ORM\Column(type='floppy_file') */ private $file; public function setFile(FileId $fileId = null) { $this->file = $fileId; } public function getFile() { return $fileId; } }
- Use
floppy_file
in your form type:
class DocumentFormType extends .... { public function buildForm(...) { $builder->add('file', 'floppy_file'); } //...rest ommited }
-
Create your action to handle this form
-
In action template you should add css and javascripts for this form:
{% block stylesheets %} {{ parent() }} {# default styles for form field #} <link href="{{ asset("bundles/floppy/css/style.css") }}" rel="stylesheet" type="text/css" media="all" /> {% endblock %} {% block javascripts %} {{ parent() }} {# jquery is required #} <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script> {# default supported javascript library to file uploading is plupload #} <script src="http://rawgithub.com/moxiecode/plupload/master/js/plupload.full.min.js"></script> {# bundle specific javascript #} <script src="{{ asset("bundles/floppy/js/FloppyFileFormType.js") }}"></script> {% endblock %} {# block content #} {# render form #} {{ form_widget(form) }} {# ... #} {# endblock #}
- Use your already created entity object and render file url:
{# document variable is object of Document class defined in step 3 #} {{ floppy_url(document.fileId.with( { "name": "some name" })) }} {# if you know the file is image you can render url to thumbnail with given sizes #} {{ floppy_url(document.fileId.with({ "thumbnail": { "size": [80, 80] } }), "image") }} {# you can use filter set defined in app/config/config.yml file in ["filter_sets" section](#config-yml) #} {{ floppy_url(document.fileId|floppy_filter("some_thumbnail")}, "image") }} {# add custom options to filter set - for example add thumbnail mode #} {{ floppy_url(document.fileId|floppy_filter("some_thumbnail", { "thumbnail": { "mode": "inset" } } )}, "image") }}
Integration points
FloppyClient library adds two integration points with FloppyServer:
- url generation for files stored on FloppyServer
- client for file upload on FloppyServer
FloppyBundle adds additional 3 integration points:
- form type: floppy_file
- doctrine column type: floppy_file
- twig floppy_url() function and floppy_filter filter
Form
floppy_file form type allows you to upload and assign file to your entity object. The form type uses plupload library as javascript uploader by default. To set up floppy_file, you should include floppy styles (css file), jquery, plupload and FloppyFileFormType.js in your layout.
Example:
//form definition class DocumentFormType extends .... { public function buildForm(...) { $builder->add('file', 'floppy_file'); } //...rest ommited }
{% block stylesheets %} {{ parent() }} {# default styles for form field #} <link href="{{ asset("bundles/floppy/css/style.css") }}" rel="stylesheet" type="text/css" media="all" /> {% endblock %} {% block javascripts %} {{ parent() }} {# jquery is required #} <script src="http://code.jquery.com/jquery-1.11.0.min.js"></script> {# default supported javascript library to file uploading is plupload #} <script src="http://rawgithub.com/moxiecode/plupload/master/js/plupload.full.min.js"></script> {# bundle specific javascript #} <script src="{{ asset("bundles/floppy/js/FloppyFileFormType.js") }}"></script> {% endblock %} {# block content #} {# render form #} {{ form_widget(form) }} {# ... #} {# endblock #}
#app/config/config.yml file #enable form theme twig: form: resources: - "FloppyBundle::form.html.twig" #app/config/routing.yml file #enable routing for floppy - it is used to generate file previews FloppyBundle: resource: "@FloppyBundle/Resources/config/routing.yml" prefix: "/floppy"
floppy_file has few options, the most important are:
- file_types - what file types that will be visible in file chooser dialog. This file types don't cause validation on server side, to validate file type you should use credentials. File types in this context are not exactly the same as file handler names (more about file handlers you can read in FloppyServer and FloppyClient docs). File types have following structure: { name: "Human readable name", extensions: [ "txt" ] }. You can define aliases to predefined file types in bundle configuration (floppy.form.file_type_aliases option, see more in "Configuration" section)
- transport_types - what javascript file transport should be used. Allowed values: html5, flash, silverlight and html4. Default value are all in the order as mentioned before. The order is important, because when browser doesn't support for example html5 transport, next transport on the list will be used.
- credentials - credentials for file uploading. Supported options for credentials are: expiration (upload request expiration timestamp), file_types (allowed file types - it will be validated on server side), access (public/private, should file be stored in public or in private storage). More about credentials you can find in FloppyServer and FloppyClient docs.
Doctrine column type
floppy_file column type simplify dealing with files in your entities. File in entity is represented by Floppy\Common\FileId object. The most interesting properties of FileId are:
- id - file hash + file extension, example: 5c7cd2fd39958b18a79f3c7e504d7cb2.jpg
- info - information about file (file size, mime type, image dimensions etc.), it only contains this information when FileId
comes from "floppy_file" form or
Floppy\Client\FloppyClient
::upload
() method, so you can in setter method store this additional info in other properties of entity
Example:
namespace ... use Floppy\Common\FileId; use Doctrine\ORM\Mapping as ORM; class Document { /** * @ORM\Column(type='floppy_file') */ private $file; /** * @ORM\Column(type='string', length=50) */ private $mimeType; public function setFile(FileId $fileId = null) { $this->file = $fileId; //you can store additional info in custom properties if($fileId !== null && $fileId->info()->get('mime-type')) { $this->mimeType = $fileId->info()->get('mime-type'); } } public function getFile() { return $fileId; } }
Twig
After upload file (thanks to floppy_file form type) and store it in your entity (thanks to floppy_file doctrine column type) you may want to display url to the file. floppy_url twig function is able to generate url to the file.
Examples of floppy_url usage:
{# url to original file #} {{ floppy_url(document.file) }} {# url to thumbnail, we assume the file is image #} {{ floppy_url(document.file.with({ "thumbnail": { "size": [50, 50] } })) }} {# as before, but file type is passed explicitly #} {{ floppy_url(document.file.with({ "thumbnail": { "size": [50, 50] } }), "image") }} {# add credentials to url #} {{ floppy_url(document.file, { "expiration": date().timestamp + 60 }) }} {# floppy_url with all arguments: file, file type and credentials #} {{ floppy_url(document.file.with({ "name": "some name" }), "file", { "expiration": date().timestamp + 60 }) }} {# if you want to use filter set definied in your app/config/config.yml file, you should use floppy_filter twig filter #} {{ floppy_url(document.file|floppy_filter("some_thumbnail")) }} {# filter set + credentials #} {{ floppy_url(document.file|floppy_filter("some_thumbnail"), { "expiration": date().timestamp + 60 }) }} {# filter set + custom options #} {{ floppy_url(document.fileId|floppy_filter("some_thumbnail", { "thumbnail": { "mode": "inset" } } )}) }}
Configuration
Only two options are required: floppy.endpoint.host and floppy.secret_key. There is a list of all configuration options:
floppy: endpoint: #Required host: ~ protocol: http path: "" filter_sets: #default filter set for image preview in floppy_file form type. It is always automatically added even if you #overwrite filter_sets _preview: quality: 95 thumbnail: size: [80, 80] #Required #secret key that is used as salt to generate checksums, this value should be the same as in FloppyServer secret_key: ~ #checksum is used for security checks, -1 means full checksum will be used in security checks checksum_length: -1 default_credentials: #credentials for upload (used by floppy_file form and FloppyClient class) that will be used if credentials are empty upload: {} #credentials for download (used by floppy_url twig function) that will be used when credentials are empty download: {} #configuration for filepath generator. This values should be the same as in FloppyServer filepath_chooser: dir_count: 2 chars_for_dir: 3 orig_file_dir: orig variant_file_dir: v #name of the file post variable. This value should be the same as in FloppyServer, you shouldn't probably change this value file_key: file #enable doctrine floppy_file column or not enable_doctrine_file_type: true #name of doctrine column, you can change it doctrine_file_type_name: floppy_file #extensions for file types (this should be compatible with FloppyServer configuration, "file" file type can be omitted) #values for "image" will be automatically used in floppy.form.file_type_aliases.image.extensions and floppy.form.preview.image.supported_extensions, #so you don't have to repeat this values file_type_extensions: { image: [ "jpg", "jpeg", "png", "gif" ] } form: #aliases for file_types form option file_type_aliases: { image: { name: "Images", extensions: [ "jpg", "jpeg", "png", "gif" ] } } #urls for flash and silverlight scripts plupload: swf: %%request_base_path%%/bundles/floppy/plupload/Moxie.swf xap: %%request_base_path%%/bundles/floppy/plupload/Moxie.xap #configuration for file previews preview: image: #filter set used to generate image preview in form filter_set: "_preview" #by default as same as floppy.file_type_extensions.image supported_extensions: [ "jpg", "jpeg", "png", "gif" ] file: name: "n-a"
License
This project is under MIT license.