dmalta/laravel-filepond

FilePond 的 Laravel 后端支持，简单直接

维护者

详细信息

github.com/dmalta/laravel-filepond

主页

源代码

安装次数：2,682

依赖关系: 0

建议者: 0

安全性: 0

星级: 0

关注者: 0

分支: 31

v1.4.9 2022-01-19 03:44 UTC

Requires

Requires (Dev)

MIT 991e254991f94a283b27549319a02277485c6b08

  • Rahul Haque <rahulhaque07.woop@gmail.com>

filepondfilepond-laravellaravel-filepond

This package is auto-updated.

Last update: 2024-09-21 07:14:17 UTC

README

Latest Version on Packagist Total Downloads

为 Laravel 应用程序提供对 FilePond 文件上传 JavaScript 库的直接后端支持。此包跟踪所有上传的文件，并为用户提供一个更简单的界面来与文件交互。它目前具有以下功能：

  • 单个和多个文件上传。
  • 第三方存储支持。
  • 分块上传，具有上传恢复功能。
  • 对临时文件的全局服务器端验证。
  • 在将文件移动到永久位置之前，在控制器级别进行验证。
  • Artisan 命令在临时文件和文件夹过期后进行清理。

注意：使用版本低于 1.3.8 的人，在升级时请更新 ./config/filepond.php 文件，因为新版本包含重大更改。

安装

使用 composer 安装此包

composer require rahulhaque/laravel-filepond

Laravel 7 用户使用小于 1.x 版本。

composer require rahulhaque/laravel-filepond "~0"

发布配置和迁移文件。

php artisan vendor:publish --provider="RahulHaque\Filepond\FilepondServiceProvider"

运行迁移。

php artisan migrate

快速入门

在开始之前，请先将 FilePond 库集成到您的项目中，您可以选择任何您喜欢的方式。

我们将为初学者创建一个场景，以便他们可以立即开始使用 FilePond。

让我们假设我们要更新用户头像及其画廊，如下所示。

<form action="{{ route('avatar') }}" method="post">
    @csrf
    <!--  For single file upload  -->
    <input type="file" name="avatar" required/>
    <p class="help-block">{{ $errors->first('avatar') }}</p>

    <!--  For multiple file uploads  -->
    <input type="file" name="gallery[]" multiple required/>
    <p class="help-block">{{ $errors->first('gallery.*') }}</p>

    <button type="submit">Submit</button>
</form>

<script>
    // Set default FilePond options
    FilePond.setOptions({
        server: {
            url: "{{ config('filepond.server.url') }}",
            headers: {
                'X-CSRF-TOKEN': "{{ @csrf_token() }}",
            }
        }
    });

    // Create the FilePond instance
    FilePond.create(document.querySelector('input[name="avatar"]'));
    FilePond.create(document.querySelector('input[name="gallery[]"]'), {chunkUploads: true});
</script>

现在使用 FilePond 输入字段选择文件，将立即在上传临时目录并将隐藏输入附加到表单中。提交表单以在控制器中处理上传的文件，如下所示。

在 UserAvatarController.php 中，通过调用 Filepond 门面的 moveTo() 方法获取并处理提交的文件，该方法将返回移动的文件信息并从临时存储中删除文件。

use Illuminate\Http\Request;
use Illuminate\Routing\Controller;
use RahulHaque\Filepond\Facades\Filepond;

class UserAvatarController extends Controller
{
    /**
     * Update the avatar for the user.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function update(Request $request)
    {
        // For single file validation
        Filepond::field($request->avatar)
            ->validate(['avatar' => 'required|image|max:2000']);

        // For multiple file validation
        Filepond::field($request->gallery)
            ->validate(['gallery.*' => 'required|image|max:2000']);
    
        $avatarName = 'avatar-' . auth()->id();
    
        $fileInfo = Filepond::field($request->avatar)
            ->moveTo('avatars/' . $avatarName);

        // dd($fileInfo);
        // [
        //     "id" => 1,
        //     "dirname" => "avatars",
        //     "basename" => "avatar-1.png",
        //     "extension" => "png",
        //     "filename" => "avatar-1",
        //     "location" => "avatars/avatar-1.png",
        //     "url" => "https:///storage/avatars/avatar-1.png",
        // ];

        $galleryName = 'gallery-' . auth()->id();

        $fileInfos = Filepond::field($request->gallery)
            ->moveTo('galleries/' . $galleryName);
    
        // dd($fileInfos);
        // [
        //     [
        //         "id" => 1,
        //         "dirname" => "galleries",
        //         "basename" => "gallery-1-1.png",
        //         "extension" => "png",
        //         "filename" => "gallery-1-1",
        //         "location" => "galleries/gallery-1-1.png",
        //         "url" => "https:///storage/galleries/gallery-1-1.png",
        //     ],
        //     [
        //         "id" => 2,
        //         "dirname" => "galleries",
        //         "basename" => "gallery-1-2.png",
        //         "extension" => "png",
        //         "filename" => "gallery-1-2",
        //         "location" => "galleries/gallery-1-2.png",
        //         "url" => "https:///storage/galleries/gallery-1-2.png",
        //     ],
        //     [
        //         "id" => 3,
        //         "dirname" => "galleries",
        //         "basename" => "gallery-1-3.png",
        //         "extension" => "png",
        //         "filename" => "gallery-1-3",
        //         "location" => "galleries/gallery-1-3.png",
        //         "url" => "https:///storage/galleries/gallery-1-3.png",
        //     ],
        // ]
    }
}

这是开始的最快方式。此包已经为您实现了所有类和控制器。接下来，我们将讨论所有可用的细节。

重要：如果您已安装 Laravel debugbar，请确保在 ./config/debugbar.php 的 except 数组中添加 filepond* 以忽略附加调试信息。

配置

首先查看 ./config/filepond.php 以了解所有开箱即用的选项。以下列出了一些重要的选项。

永久存储

默认情况下，此包使用 Laravel 的公共文件系统驱动程序进行永久文件存储。将 disk 选项更改为您喜欢的永久存储选项。等等！但我正在为不同的上传使用不同的磁盘。别担心。您可以使用 copyTo() 和 moveTo() 方法动态更改磁盘名称。

临时存储

默认情况下，此包使用 Laravel 的本地文件系统驱动程序进行临时文件存储。将 temp_disk 和 temp_folder 名称更改为指向临时文件存储的目录。

注意：将临时文件存储设置为第三方将直接上传文件到云端。另一方面，由于文件不会在您的应用服务器中可用，您将失去使用控制器级别验证的能力。

验证规则

默认的全局服务器端验证规则可以通过修改 ./config/filepond.php 中的 validation_rules 数组来更改。这些规则将适用于 FilePond 的 /process 路由的所有文件上传。

中间件

默认情况下，所有 Filepond 的路由都由 web 和 auth 中间件保护。如有必要，请更改它。

软删除

默认情况下，soft_delete 设置为 true 以跟踪用户上传的所有文件。如果您想通过删除请求删除文件，请将其设置为 false。

表

默认情况下，Filepond 模型映射到表 fileponds。如果您在数据库迁移中创建了一个具有不同名称的表，请更改它。

命令（清理）

此包包括一个 php artisan filepond:clear 命令，用于清理临时存储中的过期文件。在配置文件中可以设置 expiration 分钟，默认为 30 分钟。将此命令添加到您的计划任务列表中，以便每日运行。有关任务调度的更多信息，请参阅 - 调度 Artisan 命令

此命令接受一个 --all 选项，该选项将截断 Filepond 模型并删除临时存储中的所有内容，无论它们是否已过期。这在您失去了对上传文件的跟踪并希望从头开始时非常有用。

如果您发现即使一切设置正确，文件仍未被删除，那么可能是因为目录权限问题。尝试将 filepond 的临时目录权限设置为 775，使用 sudo chmod -R 775 ./storage/app/filepond/。然后运行 php artisan filepond:clear --all 以从头开始（可选）。对于类似 Amazon S3 的第三方存储，请确保您已设置了正确的策略。

方法

field()

Filepond::field($field) 是一个必需的方法，它告诉库要使用哪个 FilePond 表单字段。按照需要链接其他方法。

validate()

调用 Filepond::field()->validate($rules) 方法将在移动或复制之前验证临时存储的文件。支持单个和多个文件验证，就像 Laravel 的默认表单验证一样。

注意：当第三方存储设置为您的临时存储时，此方法不可用。文件将直接上传到您的第三方存储，且在本地不可用于任何进一步的修改。在此条件下调用此方法将引发错误，表明文件找不到。

copyTo()

调用 Filepond::field()->copyTo($pathWithFilename) 方法将文件从临时存储复制到提供的路径，包括文件名。它将 自动 设置文件扩展名。默认情况下，文件将复制到与配置的 disk 选项相关的目录中。如果您想覆盖该设置，也可以传递一个磁盘名称作为 第二个参数。此方法将返回复制的文件信息以及 Filepond 模型 ID。对于多文件上传，它将返回复制的文件信息数组。请注意，多个文件将以 尾随增量值 的形式复制，例如 $filename-{$i}。

moveTo()

调用Filepond::field()->moveTo($pathWithFilename)方法与copyTo()方法的工作方式相同。默认情况下，文件将被移动到配置的disk选项的相对目录。如果您想覆盖它，也可以传递一个磁盘名称作为第二个参数。它为您额外做的一件事是在复制后删除临时文件，同时尊重配置的soft_delete选项，针对Filepond模型。

delete()

调用Filepond::field()->delete()方法将删除临时文件，同时尊重Filepond模型的软删除配置。当您手动处理文件并使用getFile()方法时，此方法很有用。

APIs

如果您需要更细粒度的方法并且了解这个包的来龙去脉，您可以使用以下API来获取底层文件对象和文件模型，以便进一步与之交互。

getFile()

Filepond::field()->getFile()方法返回与Laravel的$request->file()对象相同的文件对象。对于多个上传，它将返回上传文件对象数组。然后您可以按照所需的方式手动处理文件。

手动处理文件对象不会更新用于跟踪上传文件的关联Filepond模型。然而，过期文件将像往常一样由定时命令清理。建议您在处理完成后，要么调用delete()方法，要么通过调用getModel()方法来更新底层模型。

注意：当第三方存储设置为您的临时存储时，此方法不可用。文件将直接上传到您的第三方存储，且在本地不可用于任何进一步的修改。在此条件下调用此方法将引发错误，表明文件找不到。

getModel()

Filepond::field()->getModel()方法返回给定字段的底层Laravel Filepond模型。当您需要更新已发布的迁移文件中的一些自定义字段时，这很有用。

Traits

有一个名为HasFilepond的特质可用于获取用户上传的临时文件。

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use RahulHaque\Filepond\Traits\HasFilepond;

class User extends Authenticatable
{
    use HasFilepond;
}

现在您可以像这样获取单个用户上传的所有文件信息。

User::find(1)->fileponds;

Testing

composer test

Changelog

有关最近更改的更多信息，请参阅变更日志。

Contributing

有关详细信息，请参阅贡献指南。

安全性

如果您发现任何安全相关的问题，请通过电子邮件rahulhaque07@gmail.com报告，而不是使用问题跟踪器。

Credits

License

MIT许可证（MIT）。有关更多信息，请参阅许可文件。