PHPackages                             floppy/bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. floppy/bundle

ActiveLibrary[File & Storage](/categories/file-storage)

floppy/bundle
=============

Floppy is a file storage library. This library adds fine support to use FloppyServer instance to Symfony2 apps.

0.1.2(11y ago)4118MITPHP

Since Jul 5Pushed 11y ago2 watchersCompare

[ Source](https://github.com/zineinc/floppy-bundle)[ Packagist](https://packagist.org/packages/floppy/bundle)[ RSS](/packages/floppy-bundle/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (6)Versions (4)Used By (0)

FloppyBundle
============

[](#floppybundle)

[![Build Status](https://camo.githubusercontent.com/799f3d920dde049cd6c384e74d5ea93cecb41d0566a7fa7e839729a9a16c1eea/68747470733a2f2f7472617669732d63692e6f72672f7a696e65696e632f666c6f7070792d62756e646c652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/zineinc/floppy-bundle)

FloppyBundle provides few additional integration points with [FloppyServer](https://github.com/zineinc/floppy-server) library. Before reading this documentation, **you should read documentation** for [**FloppyServer**](https://github.com/zineinc/floppy-server) and [**FloppyClient**](https://github.com/zineinc/floppy-client) 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
=============

[](#documentation)

ToC
---

[](#toc)

- [Quick tour](#quick-tour)
- [Integration points](#integration-points)
    - [Form](#form)
    - [Doctrine column type](#doctrine)
    - [Twig](#twig)
- [Configuration](#configuration)
- [License](#license)

Quick tour
----------

[](#quick-tour)

1. Configure your floppy server (shown in [floppy-server doc](https://github.com/zineinc/floppy-server#setups))
2. 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(),
            //...
        );
    }
```

3) Configure this bundle:

```
    ...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.

4. 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;
        }
    }
```

5. Use `floppy_file` in your form type:

```
    class DocumentFormType extends .... {
        public function buildForm(...) {
            $builder->add('file', 'floppy_file');
        }

        //...rest ommited
    }
```

6. Create your action to handle this form
7. In action template you should add css and javascripts for this form:

```
    {% block stylesheets %}
        {{ parent() }}
        {# default styles for form field #}

    {% endblock %}

    {% block javascripts %}
        {{ parent() }}

        {# jquery is required #}

        {# default supported javascript library to file uploading is plupload #}

        {# bundle specific javascript #}

    {% endblock %}

    {# block content #}
        {# render form #}
        {{ form_widget(form) }}
        {# ... #}
    {# endblock #}
```

8. 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
------------------

[](#integration-points)

[FloppyClient](https://github.com/zineinc/floppy-client) library adds two integration points with [FloppyServer](https://github.com/zineinc/floppy-server):

- 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

[](#form)

**floppy\_file** form type allows you to upload and assign file to your entity object. The form type uses [plupload](http://www.plupload.com/docs/)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 #}

    {% endblock %}

    {% block javascripts %}
        {{ parent() }}

        {# jquery is required #}

        {# default supported javascript library to file uploading is plupload #}

        {# bundle specific javascript #}

    {% 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

[](#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

[](#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
-------------

[](#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
-------

[](#license)

This project is under **MIT** license.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~61 days

Total

3

Last Release

4213d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/438063?v=4)[Piotr Śliwa](/maintainers/psliwa)[@psliwa](https://github.com/psliwa)

---

Top Contributors

[![psliwa](https://avatars.githubusercontent.com/u/438063?v=4)](https://github.com/psliwa "psliwa (54 commits)")

---

Tags

filesystemimagefilefile-uploadfile storagefloppy

### Embed Badge

![Health badge](/badges/floppy-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/floppy-bundle/health.svg)](https://phpackages.com/packages/floppy-bundle)
```

###  Alternatives

[easycorp/easyadmin-bundle

Admin generator for Symfony applications

4.3k16.7M310](/packages/easycorp-easyadmin-bundle)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[sonata-project/media-bundle

Symfony SonataMediaBundle

4625.5M71](/packages/sonata-project-media-bundle)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[artgris/filemanager-bundle

FileManager is a simple Multilingual File Manager Bundle for Symfony

182420.8k9](/packages/artgris-filemanager-bundle)[ranky/media-bundle

A complete and friendly media file manager for Symfony

681.3k](/packages/ranky-media-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)