raisenow/symfony3-file-uploader-bundle

为Symfony2提供的多文件上传组件，基于BlueImp上传器。同时支持上传图片的缩放。

维护者

详细信息

github.com/raisenow/symfony3-file-uploader-bundle

主页

源代码

安装: 579

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 3

分支: 86

类型：symfony-bundle

v0.3.0 2019-02-08 15:20 UTC

Requires

MIT 45a2635adee188aae50d92168f88cb1c8b5aaecd

  • Thomas Boutell <tom.woop@punkave.com>
  • Wes John-Alder <wes.woop@punkave.com>

symfonyfilebundleuploadSymfony BundleImage transformuploadermultiple file uploadblueimppunkavesymfony-2.0symfony-2.1

This package is not auto-updated.

Last update: 2024-09-29 18:59:26 UTC

README

需要维护者！

这个包不再积极更新。它仅维护与Symfony 2.0.x的兼容性问题。如果您有兴趣接管这个包的维护工作，请联系tom@punkave.com。谢谢！

简介

此包提供了基于BlueImp jQuery 文件上传器包的多文件上传功能。在兼容浏览器中，完全支持拖放和多个文件选择。我们选择BlueImp是因为它具有出色的前后浏览器兼容性。

由于BlueImp提供的现有PHP上传器类已经很优秀，并且开箱即用就做了许多优秀的事情，因此此包相当薄。我们提供了一种将其集成到Symfony 2项目中的方法。

上传器将文件发送到您指定的文件夹。如果该文件夹已经包含文件，它们将与新文件并排显示，作为可以删除的现有文件。

该包可以自动将图片缩放到您指定的尺寸。提供的方法使得创建具有“保存”和“取消”操作的表单成为可能，其中附件文件会受到尊重。

关于Internet Explorer的说明

版本低于10的Internet Explorer不支持多文件上传。但是，IE用户每次只能添加一个文件，但仍可以构建一个附件文件集合。

要求

  • Symfony2
  • jQuery
  • jQuery UI
  • Underscore

安装

Symfony 2.0

  1. 将以下行添加到您的Symfony2依赖文件

    [FileUploaderBundle] git=http://github.com/punkave/symfony2-file-uploader-bundle.git target=/bundles/PunkAve/FileUploaderBundle

  2. 使用以下行修改您的AppKernel

    new PunkAve\FileUploaderBundle\PunkAveFileUploaderBundle(),

  3. 如果您还没有，请将以下行添加到您的autoload.php文件中

    'PunkAve' => DIR.'/../vendor/bundles',

  4. 安装您的供应商

    bin/vendors install

Symfony 2.2

  1. 将以下行添加到您的composer.json require块：“punkave/symfony2-file-uploader-bundle”: “dev-master”

    标准的symfony 2.2 composer.json文件有一个分支别名，这会干扰安装此包。您可以通过删除以下行来解决此问题：

 "branch-alias": {
            "dev-master": "2.2-dev"
        }

  1. 使用以下行修改您的AppKernel

    new PunkAve\FileUploaderBundle\PunkAveFileUploaderBundle(),

  2. 执行composer install

用法

您的页面必须包含Underscore模板以渲染文件列表和上传器。您可以使用我们的模板如下

{# Underscore templates for the uploader #}
{% include "PunkAveFileUploaderBundle:Default:templates.html.twig" %}

这样做就足够了，可以在身体中的任何地方。如果您愿意，可以复制并修改templates.html.twig，然后从您自己的目录中包含它。只是不要删除data-*属性。其余的标记取决于您。

在编辑操作中

假设您在控制器中有一个editAction()方法。您有一个表单，您希望在其中包含一个列表附件文件，就像表单中的其他字段一样：您可以添加更多，您可以删除现有文件，但除非用户点击“保存”，否则不会发生任何永久性操作。

FileUploader服务需要为给定对象附加的文件提供一个唯一的文件夹名称。为了对新对象和现有对象都实现这一功能，我们建议您遵循“editId模式”，在该模式中，表单在整个生命周期中（包括必要时多次验证）被分配一个唯一的、随机的“editId”。这使我们能够管理尚未拥有自己id的新对象的文件上传。

此代码在表单首次通过时创建一个editId，并同步现有对象附加的现有文件（如果有的话）。from_folder和to_folder对象指定了附加文件将存储的子目录。稍后我们将看看这些文件夹的父目录是如何确定的。

（获取$ posting并验证用户是否有权编辑该posting由您自己完成。）

$request = $this->getRequest();

$editId = $this->getRequest()->get('editId');
if (!preg_match('/^\d+$/', $editId))
{
    $editId = sprintf('%09d', mt_rand(0, 1999999999));
    if ($posting->getId())
    {
        $this->get('punk_ave.file_uploader')->syncFiles(
            array('from_folder' => 'attachments/' . $posting->getId(),
              'to_folder' => 'tmp/attachments/' . $editId,
              'create_to_folder' => true));
    }
}

如果用户在尝试完成操作的第一次尝试中遇到验证错误（例如，表单验证错误），您希望再次呈现相同的文件列表。因此，使用getFiles方法获取现有文件列表。确保您将此列表传递给您的模板。

$existingFiles = $this->get('punk_ave.file_uploader')->getFiles(array('folder' => 'tmp/attachments/' . $editId));

（请注意，您生成的editId应该是高度随机的，以防止用户控制彼此的附件。）

当用户保存表单并且您刚刚持久化posting对象时，您还应该将关联editId的临时文件夹中的文件同步回与posting的id关联的永久文件夹。由于我们已经完成了临时文件夹，我们要求文件上传服务删除该文件夹。我们还要求服务在必要时创建目标文件夹。

$fileUploader = $this->get('punk_ave.file_uploader');
$fileUploader->syncFiles(
    array('from_folder' => '/tmp/attachments/' . $editId,
    'to_folder' => '/attachments/' . $posting->getId(),
    'remove_from_folder' => true,
    'create_to_folder' => true));

稍后您可以轻松地获取附加到对象的所有文件名称列表

$files = $fileUploader->getFiles(array('folder' => 'attachments/' . $posting->getId()));

然而，访问文件系统会有一定的性能成本。您会发现将附件列表保存在Doctrine表中更有效，尤其是如果您想在列表视图中包含第一个附件的话。只需使用getFiles获取文件名列表，然后根据您的需要将其镜像到您的数据库中。

在您的布局中

为了通过Assetic提供必要的JavaScript（请注意，您必须提供jQuery、jQuery UI和Underscore）

{% javascripts
    '@MyBundle/Resources/public/js/jquery-1.7.2.min.js'
    '@MyBundle/Resources/public/js/jquery-ui-1.8.22.custom.min.js'
    '@MyBundle/Resources/public/js/underscore-min.js'
    '@PunkAveFileUploaderBundle/Resources/public/js/jquery.fileupload.js'
    '@PunkAveFileUploaderBundle/Resources/public/js/jquery.iframe-transport.js'
    '@PunkAveFileUploaderBundle/Resources/public/js/FileUploader.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

您必须包含iframe传输以兼容IE 9及以下版本。

在编辑模板中

假设有一个与编辑操作关联的edit.html.twig模板。这里是一个示例。请注意，您的操作中的渲染调用会传递posting对象、editId、existingFiles数组和isNew标志。

{% extends "MyBundle:Default:layout.html.twig" %}

{% block body %}

{# Underscore templates for the uploader #}
{% include "PunkAveFileUploaderBundle:Default:templates.html.twig" %}

<form class="edit-form" action="{{ path('edit', { id: posting.id, editId: editId }) }}" method="post" {{ form_enctype(form) }}>
    {{ form_widget(form) }}

    {# Hydrated by javascript #}
    <div class="file-uploader"></div>

    <button class="btn btn-primary" type="submit">{{ isNew ? "Save New Listing" : "Save Changes" }}</button>
    <a class="btn" href="{{ cancel }}">Cancel</a>
    {% if not isNew %}
        <a class="btn btn-danger" href="{{ path('delete', { id: posting.id } ) }}">Delete</a>
    {% endif %}

</form>

<script type="text/javascript">

// Enable the file uploader

$(function() {
    new PunkAveFileUploader({
        'uploadUrl': {{ path('upload', { editId: editId }) | json_encode | raw }},
        'viewUrl': {{ ('/uploads/tmp/attachments/' ~ editId) | json_encode | raw }},
        'el': '.file-uploader',
        'existingFiles': {{ punkave_get_files('tmp/attachments/' ~ editId) | json_encode | raw }},
        'delaySubmitWhileUploading': '.edit-form'
    });
});
</script>
{% endblock %}

进度显示

在template.html.twig中有一个简单的旋转器。如果您选择提供自己的Underscore模板，可以替换它。只需确保您有一个具有data-spinner="1"属性的自定义元素。

如果您使用template.html.twig，请注意，您必须按照常规方式发布您的资产，以便旋转器图像可用。

php app/console assets:install web/

作为替代方案，您可以在间隔计时器上编写自己的代码，该计时器检查PunkAveFileUploader对象的uploading属性是否当前设置为true，并根据此显示旋转器。

延迟表单提交直到上传完成

如果上传仍在进行中，让用户提交文件上传服务旨在成为一部分的表单不是一个好主意。您可以通过在创建PunkAveFileUploader JavaScript对象时指定'delaySubmitWhileUploading'选项来轻松地阻止此操作，如上所示。

'delaySubmitWhileUploading': '.edit-form'

或者，您可以在任何时间检查使用new PunkAveFileUploader(...)创建的对象的uploading属性。如果正在上传，它将为true。现有的delaySubmitWhileUploading实现依赖于这一点。

在上传操作中

除了您表单的常规编辑操作外，还必须有一个上传操作来处理文件上传。这个操作将调用服务的handleFileUpload方法，将任务传递给BlueImp的UploadHandler类。由于该类直接在PHP中实现整个REST响应，因此该方法不会返回。

以下是上传操作

/**
 *
 * @Route("/upload", name="upload")
 * @Template()
 */
public function uploadAction()
{
    $editId = $this->getRequest()->get('editId');
    if (!preg_match('/^\d+$/', $editId))
    {
        throw new Exception("Bad edit id");
    }

    $this->get('punk_ave.file_uploader')->handleFileUpload(array('folder' => 'tmp/attachments/' . $editId));
}

这个单一操作实际上实现了一个完整的REST API，其中BlueImp UploadHandler类负责上传和删除文件。

再次强调，handleFileUpload不会返回，因为响应是由BlueImp的UploadHandler类在本地PHP中生成的。

设置允许的文件类型

您可以通过在handleFileUpload方法或parameters.yml中指定它们来指定自定义文件类型，以偏离默认类型（这些类型在Resources/config/services.yml中定义）。

在handleFileUpload中

$this->get('punk_ave.file_uploader')->handleFileUpload(array(
    'folder' => 'tmp/attachments/' . $editId,
    'allowed_extensions' => array('zip', 'rar', 'tar')
));

在这种情况下，FileUploader服务将合并默认扩展名和提供的扩展名，并生成一个单个的正则表达式。使用正则表达式字符可能会导致错误。

parameters.yml：如果您安装了Symfony标准版，您可以在app/config/parameters.yml中指定它们。

file_uploader.allowed_extensions:
    - zip
    - rar
    - tar

这样做将覆盖默认扩展名而不是添加它们！

删除文件

迟早帖子会被删除，并且您希望所有附件也被删除。

您可以这样做：

$this->get('punk_ave.file_uploader')->removeFiles(array('folder' => 'attachments/' . $posting->getId()));

您可能想在管理类或Doctrine事件监听器中这样做，但这不是我们的部门。

删除临时文件

如果您选择遵循我们的editId模式，您可能希望定期清除web/uploads/tmp中超过一定年龄的内容。人们经常离开网站，因此并非每个人都会点击您精心提供的“取消”操作，该操作根据editId模式调用removeFiles()。

请考虑将其作为每晚运行的cron作业安装此shell脚本。此shell脚本删除超过一天旧的文件，然后删除空文件夹

#!/bin/sh
find /path/to/my/project/web/uploads/tmp -mtime +1 -type f -delete
find /path/to/my/project/web/uploads/tmp -mindepth 1 -type d -empty -delete

（由于第二个命令不是递归的，父文件夹可能会多保留一天，但它们将在第二天被删除。）

配置参数

请参阅此包中的Resources/config/services.yml。您可以轻松决定上传的父文件夹以及接受的文件扩展名，以及您想要将图像文件自动缩放到的大小。

上述from_folder、to_folder和folder选项都是在处理文件时附加到file_uploader.file_base_path之后的。

如果file_uploader.file_base_path设置为以下内容（这是默认设置）

file_uploader.file_base_path: "%kernel.root_dir%/../web/uploads"

并且当调用handleFileUpload时将folder选项设置为attachments/5，那么上传的文件将到达

/root/of/your/project/web/uploads/attachments/5/originals

如果这个帖子的唯一附件是botfly.jpg，并且您已经为file_uploader.sizes选项（默认情况下我们提供几个有用的标准大小）配置了一个或多个图像大小，那么您将看到

/root/of/your/project/web/uploads/photos/5/originals/botfly.jpg
/root/of/your/project/web/uploads/photos/5/thumbnail/botfly.jpg
/root/of/your/project/web/uploads/photos/5/medium/botfly.jpg
/root/of/your/project/web/uploads/photos/5/large/botfly.jpg

因此，所有这些都可以通过以下URL轻松访问

/uploads/photos/5/originals/botfly.jpg

等等。

尽可能保留上传文件的原名称和文件扩展名，同时不引入安全风险。

限制上传数量

您可以通过设置max_no_of_files属性来限制上传文件的数量。您可以在parameters.yml中设置如下

parameters:
  file_uploader.max_number_of_files: 4

您可能想要为这种情况添加一个错误处理程序。在初始化PunkAveFileUploader的模板中设置errorCallback

// Enable the file uploader
$(function() {
  new PunkAveFileUploader({
    // ... other required options,

    'errorCallback': function(errorObj) {
      if (errorObj.error == 'maxNumberOfFiles') {
        alert("Maximum uploaded files exceeded!");
      }
    }
  });
});

限制

此包通过glob()函数访问文件系统。它不能与S3流包装器一起使用。

如果您的附件非常大，来回同步文件以遵循editId模式可能不可取。在这种情况下，请不要使用editId模式。一种替代方案是立即在数据库中创建对象，直到您将其标记为实时才在列表视图中显示它们。这样，您的编辑操作可以使用对象的永久ID作为folder选项的一部分，无需进行同步。在这种情况下，您可能需要将附件列表移动到表单下方，以提示用户没有“取消”这些操作的说法。

注意事项

上传组件使用了Bootstrap约定进行样式设计。如果您在项目中使用了Bootstrap，上传组件应该看起来相当美观。

"选择文件"按钮允许多选以及拖放。