文件上传

#简介

文件上传字段基于 Filepond。

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')

#配置存储磁盘及目录

默认情况下，文件会上传到配置文件中定义的存储磁盘中。你也可以设置 FILESYSTEM_DISK 环境变量来修改他。

要修改特定字段的磁盘和目录，以及文件的可见度，请使用 disk()、directory() 和 visibility() 方法。默认情况下，文件以 private 可见度上传到你的存储磁盘，除非你将该磁盘设置为 public：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->disk('s3')
    ->directory('form-attachments')
    ->visibility('public')

As well as allowing static values, the disk(), directory() and visibility() methods accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#上传多个文件

You may also upload multiple files. This stores URLs in JSON:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()

Optionally, you may pass a boolean value to control if multiple files can be uploaded at once:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple(FeatureFlag::active())

As well as allowing a static value, the multiple() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

If you’re saving the file URLs using Eloquent, you should be sure to add an array cast to the model property:

use Illuminate\Database\Eloquent\Model;

class Message extends Model
{
    protected $casts = [
        'attachments' => 'array',
    ];

    // ...
}

#控制最大并行上传数

You can control the maximum number of parallel uploads using the maxParallelUploads() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->maxParallelUploads(1)

This will limit the number of parallel uploads to 1. If unset, we’ll use the default FilePond value which is 2.

As well as allowing a static value, the maxParallelUploads() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#控制文件名

By default, a random file name will be generated for newly-uploaded files. This is to ensure that there are never any conflicts with existing files.

#Security implications of controlling file names

Before using the preserveFilenames() or getUploadedFileNameForStorageUsing() methods, please be aware of the security implications. If you allow users to upload files with their own file names, there are ways that they can exploit this to upload malicious files. This applies even if you use the acceptedFileTypes() method to restrict the types of files that can be uploaded, since it uses Laravel’s mimetypes rule which does not validate the extension of the file, only its mime type, which could be manipulated.

This is specifically an issue with the getClientOriginalName() method on the TemporaryUploadedFile object, which the preserveFilenames() method uses. By default, Livewire generates a random file name for each file uploaded, and uses the mime type of the file to determine the file extension.

Using these methods with the local or public filesystem disks will make your app vulnerable to remote code execution if the attacker uploads a PHP file with a deceptive mime type. Using an S3 disk protects you from this specific attack vector, as S3 will not execute PHP files in the same way that your server might when serving files from local storage.

If you are using the local or public disk, you should consider using the storeFileNamesIn() method to store the original file names in a separate column in your database, and keep the randomly generated file names in the file system. This way, you can still display the original file names to users, while keeping the file system secure.

On top of this security issue, you should also be aware that allowing users to upload files with their own file names can lead to conflicts with existing files, and can make it difficult to manage your storage. Users could upload files with the same name and overwrite the other’s content if you do not scope them to a specific directory, so these features should in all cases only be accessible to trusted users.

#保留原始文件名

To preserve the original filenames of the uploaded files, use the preserveFilenames() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->preserveFilenames()

Optionally, you may pass a boolean value to control if the original file names should be preserved:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->preserveFilenames(FeatureFlag::active())

As well as allowing a static value, the preserveFilenames() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#生成自定义文件名

You may completely customize how file names are generated using the getUploadedFileNameForStorageUsing() method, and returning a string from the closure based on the $file that was uploaded:

use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;

FileUpload::make('attachment')
    ->getUploadedFileNameForStorageUsing(
        fn (TemporaryUploadedFile $file): string => (string) str($file->getClientOriginalName())
            ->prepend('custom-prefix-'),
    )

You can inject various utilities into the function passed to getUploadedFileNameForStorageUsing() as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
File	Livewire\Features\SupportFileUploads\TemporaryUploadedFile	$file	The temporary file object being uploaded.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#独立保存原始文件名

You can keep the randomly generated file names, while still storing the original file name, using the storeFileNamesIn() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->storeFileNamesIn('attachment_file_names')

attachment_file_names will now store the original file names of your uploaded files, so you can save them to the database when the form is submitted. If you’re uploading multiple() files, make sure that you add an array cast to this Eloquent model property too.

As well as allowing a static value, the storeFileNamesIn() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#头像模式

You can enable avatar mode for your file upload field using the avatar() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('avatar')
    ->avatar()

This will only allow images to be uploaded, and when they are, it will display them in a compact circle layout that is perfect for avatars.

This feature pairs well with the circle cropper.

#图片编辑器

You can enable an image editor for your file upload field using the imageEditor() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()

You can open the editor once you upload an image by clicking the pencil icon. You can also open the editor by clicking the pencil icon on an existing image, which will remove and re-upload it on save.

Optionally, you may pass a boolean value to control if the image editor is enabled:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor(FeatureFlag::active())

As well as allowing a static value, the imageEditor() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Allowing users to crop images to aspect ratios

You can allow users to crop images to a set of specific aspect ratios using the imageEditorAspectRatios() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatios([
        '16:9',
        '4:3',
        '1:1',
    ])

You can also allow users to choose no aspect ratio, “free cropping”, by passing null as an option:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatios([
        null,
        '16:9',
        '4:3',
        '1:1',
    ])

As well as allowing a static value, the imageEditorAspectRatios() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#设置图片编辑器模式

You can change the mode of the image editor using the imageEditorMode() method, which accepts either 1, 2 or 3. These options are explained in the Cropper.js documentation:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorMode(2)

As well as allowing a static value, the imageEditorMode() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Customizing the image editor’s empty fill color

By default, the image editor will make the empty space around the image transparent. You can customize this using the imageEditorEmptyFillColor() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorEmptyFillColor('#000000')

As well as allowing a static value, the imageEditorEmptyFillColor() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#设置图片编辑器视窗大小

You can change the size of the image editor’s viewport using the imageEditorViewportWidth() and imageEditorViewportHeight() methods, which generate an aspect ratio to use across device sizes:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorViewportWidth('1920')
    ->imageEditorViewportHeight('1080')

As well as allowing static values, the imageEditorViewportWidth() and imageEditorViewportHeight() methods also accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Allowing users to crop images as a circle

You can allow users to crop images as a circle using the circleCropper() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->avatar()
    ->imageEditor()
    ->circleCropper()

This is perfectly accompanied by the avatar() method, which renders the images in a compact circle layout.

Optionally, you may pass a boolean value to control if the circle cropper is enabled:

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->avatar()
    ->imageEditor()
    ->circleCropper(FeatureFlag::active())

As well as allowing a static value, the circleCropper() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Cropping and resizing images without the editor

Filepond allows you to crop and resize images before they are uploaded, without the need for a separate editor. You can customize this behavior using the imageCropAspectRatio(), imageResizeTargetHeight() and imageResizeTargetWidth() methods. imageResizeMode() should be set for these methods to have an effect - either force, cover, or contain.

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageResizeMode('cover')
    ->imageCropAspectRatio('16:9')
    ->imageResizeTargetWidth('1920')
    ->imageResizeTargetHeight('1080')

As well as allowing static values, the imageResizeMode(), imageCropAspectRatio(), imageResizeTargetHeight() and imageResizeTargetWidth() methods also accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Altering the appearance of the file upload area

You may also alter the general appearance of the Filepond component. Available options for these methods are available on the Filepond website.

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->imagePreviewHeight('250')
    ->loadingIndicatorPosition('left')
    ->panelAspectRatio('2:1')
    ->panelLayout('integrated')
    ->removeUploadedFileButtonPosition('right')
    ->uploadButtonPosition('left')
    ->uploadProgressIndicatorPosition('left')

As well as allowing static values, these methods also accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Displaying files in a grid

You can use the Filepond grid layout by setting the panelLayout():

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->panelLayout('grid')

As well as allowing a static value, the panelLayout() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Reordering files

You can also allow users to re-order uploaded files using the reorderable() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->reorderable()

When using this method, FilePond may add newly-uploaded files to the beginning of the list, instead of the end. To fix this, use the appendFiles() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->reorderable()
    ->appendFiles()

Optionally, the reorderable() and appendFiles() methods accept a boolean value to control if the files can be reordered and if new files should be appended to the end of the list:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->reorderable(FeatureFlag::active())
    ->appendFiles(FeatureFlag::active())

As well as allowing a static value, the reorderable() and appendFiles() methods also accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Opening files in a new tab

You can add a button to open each file in a new tab with the openable() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->openable()

Optionally, you may pass a boolean value to control if the files can be opened in a new tab:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->openable(FeatureFlag::active())

As well as allowing a static value, the openable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#下载文件

If you wish to add a download button to each file instead, you can use the downloadable() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->downloadable()

Optionally, you may pass a boolean value to control if the files can be downloaded:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->downloadable(FeatureFlag::active())

As well as allowing a static value, the downloadable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#预览文件

By default, some file types can be previewed in FilePond. If you wish to disable the preview for all files, you can use the previewable(false) method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->previewable(false)

As well as allowing a static value, the previewable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Moving files instead of copying when the form is submitted

By default, files are initially uploaded to Livewire’s temporary storage directory, and then copied to the destination directory when the form is submitted. If you wish to move the files instead, providing that temporary uploads are stored on the same disk as permanent files, you can use the moveFiles() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->moveFiles()

Optionally, you may pass a boolean value to control if the files should be moved:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->moveFiles(FeatureFlag::active())

As well as allowing a static value, the moveFiles() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Preventing files from being stored permanently

If you wish to prevent files from being stored permanently when the form is submitted, you can use the storeFiles(false) method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->storeFiles(false)

When the form is submitted, a temporary file upload object will be returned instead of a permanently stored file path. This is perfect for temporary files like imported CSVs.

As well as allowing a static value, the storeFiles() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Orienting images from their EXIF data

By default, FilePond will automatically orient images based on their EXIF data. If you wish to disable this behavior, you can use the orientImagesFromExif(false) method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->orientImagesFromExif(false)

As well as allowing a static value, the orientImagesFromExif() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Hiding the remove file button

It is also possible to hide the remove uploaded file button by using deletable(false):

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->deletable(false)

As well as allowing a static value, the deletable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Preventing pasting files

You can disable the ability to paste files via the clipboard using the pasteable(false) method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->pasteable(false)

As well as allowing a static value, the pasteable() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#Preventing file information fetching

While the form is loaded, it will automatically detect whether the files exist, what size they are, and what type of files they are. This is all done on the backend. When using remote storage with many files, this can be time-consuming. You can use the fetchFileInformation(false) method to disable this feature:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->fetchFileInformation(false)

As well as allowing a static value, the fetchFileInformation() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#自定义上传信息

You may customize the uploading message that is displayed in the form’s submit button using the uploadingMessage() method:

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->uploadingMessage('Uploading attachment...')

As well as allowing a static value, the uploadingMessage() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#文件上传验证

As well as all rules listed on the validation page, there are additional rules that are specific to file uploads.

Since Filament is powered by Livewire and uses its file upload system, you will want to refer to the default Livewire file upload validation rules in the config/livewire.php file as well. This also controls the 12MB file size maximum.

#文件类型验证

You may restrict the types of files that may be uploaded using the acceptedFileTypes() method, and passing an array of MIME types.

use Filament\Forms\Components\FileUpload;

FileUpload::make('document')
    ->acceptedFileTypes(['application/pdf'])

As well as allowing static values, the acceptedFileTypes() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

You may also use the image() method as shorthand to allow all image MIME types.

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()

#自定义 MIME 类型映射

上传文件时，有些文件格式可能无法被浏览器正确识别。Filament 允许你使用 mimeTypeMap() 方法手动定义特定文件后缀的 MIME 类型：

use Filament\Forms\Components\FileUpload;

FileUpload::make('designs')
    ->acceptedFileTypes([
        'x-world/x-3dmf',
        'application/vnd.sketchup.skp',
    ])
    ->mimeTypeMap([
        '3dm' => 'x-world/x-3dmf',
        'skp' => 'application/vnd.sketchup.skp',
    ]);

As well as allowing static values, the mimeTypeMap() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#文件大小验证

你也可以限制上传文件的大小(以 KB 为计量单位)：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->minSize(512)
    ->maxSize(1024)

As well as allowing static values, the minSize() and maxSize() methods also accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#上传大文件

如果你在上传大文件时遇到问题，比如浏览器控制台中显示 HTTP 请求失败(状态码 422)，你可能需要调整你的配置。

在服务器的 php.ini 文件中，增加最大上传文件大小或许可以解决该问题：

post_max_size = 120M
upload_max_filesize = 120M

Livewire 也会在文件上传前验证文件大小。要发布 Livewire 配置文件，请运行：

php artisan livewire:publish --config

在 temporary_file_upload 的 rules 键中可以调整最大上传文件大小。本例中，规则中使用了 KB，120MB 是 122880KB：

'temporary_file_upload' => [
    // ...
    'rules' => ['required', 'file', 'max:122880'],
    // ...
],

#文件数验证

使用 minFiles() 和 maxFiles() 方法，你可以自定义文件上传的数量：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->minFiles(2)
    ->maxFiles(5)

As well as allowing static values, the minFiles() and maxFiles() methods also accept functions to dynamically calculate them. You can inject various utilities into the functions as parameters.

Learn more about utility injection.

Utility	Type	Parameter	Description
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion