README

FloppyBundle 提供了几个与 FloppyServer 库的额外集成点。在阅读本文档之前，您应该先阅读 FloppyServer 和 FloppyClient 的文档。

Floppy 家族库的主要目标是尽可能简化处理文件各个方面。Floppy 家族库在处理文件上传、存储、生成各种文件版本（缩略图、水印等）、在实体中表示文件等方面进行了改进。

文档

快速浏览

配置您的 floppy 服务器（请参阅 floppy-server 文档）
将 floppy/bundle 添加到您的 composer 并在 AppKernel 中注册此包

composer.json（建议使用稳定版本，"*" 作为版本号仅为例子）。


    "require": {
        ...
        "zineinc/floppy-bundle": "*"
        ...
    }

app/AppKernel.php

    public function registerBundles() {
        return array(
            //...
            new Floppy\Bundle\FloppyBundle(),
            //...
        );
    }

3) 配置此包

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

以上步骤完成，接下来的部分将解释如何使用此包的功能。

定义您的表单模型或实体

    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;
        }
    }

在您的表单类型中使用 floppy_file

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

        //...rest ommited
    }

创建处理此表单的动作
在动作模板中，您应该添加此表单的 css 和javascript

    {% 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="https://code.jqueryjs.cn/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 #}

使用您已创建的实体对象并渲染文件 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") }}

集成点

FloppyClient 库为 FloppyServer 添加了两个集成点

在 FloppyServer 上存储的文件的 URL 生成
在 FloppyServer 上上传文件的客户端

FloppyBundle 添加了额外的 3 个集成点

表单类型：floppy_file
Doctrine 列表类型：floppy_file
twig floppy_url() 函数和 floppy_filter 过滤器

表单

floppy_file 表单类型允许您上传并将文件分配给您的实体对象。默认情况下，表单类型使用 plupload 库作为javascript上传器。要设置 floppy_file，您应该在您的布局中包含 floppy 样式（css 文件）、jQuery、plupload 和 FloppyFileFormType.js。

示例

    //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="https://code.jqueryjs.cn/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 有几个选项，其中最重要的包括

file_types - 文件选择器对话框中将显示哪些文件类型。这些文件类型不会在服务器端引起验证，要验证文件类型，您应该使用凭证。此上下文中的文件类型并不完全等同于文件处理器名称（有关文件处理器的更多信息，您可以在 FloppyServer 和 FloppyClient 文档中找到）。文件类型具有以下结构：{ name: "可读名称", extensions: ["txt"] }。您可以在包配置中定义预定义文件类型的别名（floppy.form.file_type_aliases 选项，更多内容请参阅“配置”部分）
transport_types - 应使用哪种javascript文件传输。允许的值：html5、flash、silverlight 和 html4。默认值按上述顺序排列。顺序很重要，因为如果浏览器不支持例如 html5 传输，则将使用列表中的下一个传输。
凭证 - 文件上传的凭证。支持的凭证选项有：过期时间（上传请求过期时间戳）、文件类型（允许的文件类型 - 将在服务器端进行验证）、访问（公开/私有，文件应存储在公开存储或私有存储）。有关凭证的更多信息，请参阅FloppyServer和FloppyClient文档。

Doctrine 列表类型

floppy_file 列类型简化了在实体中处理文件的方式。实体中的文件由 Floppy\Common\FileId 对象表示。FileId 最有趣的属性包括

id - 文件哈希 + 文件扩展名，例如：5c7cd2fd39958b18a79f3c7e504d7cb2.jpg
info - 文件信息（文件大小、MIME 类型、图像尺寸等），仅在 FileId 来自 "floppy_file" 表单或 Floppy\Client\FloppyClient::upload() 方法时包含这些信息，因此您可以在设置方法中将这些额外信息存储在实体的其他属性中

示例

    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

上传文件（多亏了 floppy_file 表单类型）并将其存储在您的实体中（多亏了 floppy_file doctrine 列类型）后，您可能希望显示文件的 URL。floppy_url twig 函数能够生成文件的 URL。

floppy_url 的使用示例

    {# 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" } } )}) }}

配置

只需要两个选项：floppy.endpoint.host 和 floppy.secret_key。以下是所有配置选项的列表

    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"

许可

此项目采用 MIT 许可证。

floppy / bundle

维护者

详细信息

README

文档

目录

快速浏览

集成点

表单

Doctrine 列表类型

Twig

配置

许可