README

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

单文件和多文件上传。
支持第三方存储。
分块上传，支持上传中断后继续。
对临时文件进行全局服务器端验证。
在将文件移动到永久位置之前，在控制器级别进行验证。
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，请确保将 filepond* 添加到 ./config/debugbar.php 的 except 数组中，以忽略附加 debugbar 信息。

配置

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

永久存储

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

临时存储

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

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

验证规则

默认的全局服务器端验证规则可以通过修改 validation_rules 数组在 ./config/filepond.php 中进行更改。这些规则将适用于 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 以从头开始（可选）。对于像亚马逊 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() 方法手动处理文件时非常有用。

API

如果您需要更精细的方法并且了解这个包的内部结构，您可以使用以下API来获取底层的文件对象和文件模型以进一步交互。

getFile()

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

手动处理文件对象不会更新关联的 Filepond 模型，该模型用于跟踪上传的文件。但是，过期的文件将像往常一样由计划任务清理。建议您在处理完成后调用 delete() 方法或通过调用 getModel() 方法更新底层模型。

注意：当第三方存储设置为您的临时存储时，此方法不可用。文件将直接上传到您的第三方存储，且不可用于任何进一步修改。在这种情况下调用此方法将抛出找不到文件的错误。

getModel()

Filepond::field()->getModel() 方法返回给定字段的底层 Laravel Filepond 模型。这在您需要在发布的迁移文件中添加一些自定义字段以供更新时非常有用。

特质

有一个可用的 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;

测试

composer test

变更日志

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

贡献

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

安全性

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

鸣谢

许可证

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

infoti-idefix / laravel-filepond

维护者

详细信息