Поле формы «File upload» (Загрузка файла) в Filament Form Builder

• Обзор
• Настройка диска и каталога хранения
• Загрузка нескольких файлов
• Управление именами файлов
  • Сохранение оригинальных имен файлов
  • Создание пользовательских имен файлов
  • Независимое хранение оригинальных имен файлов
• Режим аватара
• Редактор изображений
  • Обрезка изображений в соответствии с соотношением сторон
  • Настройка режима редактора изображений
  • Настройка цвета прозрачности заливки редактора изображений
  • Установка размера области просмотра редактора изображений
  • Позволяет обрезать изображения в виде круга
  • Обрезка и изменение размера изображений без редактора
• Изменение внешнего вида области загрузки файлов
• Упорядочивание файлов
• Открытие файлов в новой вкладке
• Загрузка файлов
• Предварительный просмотр файлов
• Перемещение файлов вместо копирования при отправке формы
• Предотвращение постоянного хранения файлов
• Ориентация изображений на основе их EXIF-данных
• Скрытие кнопки удаления файла
• Предотвращение получения информации о файле
• Настройка уведомления о загрузке
• Проверка корректности загружаемых файлов
  • Проверка типа файла
  • Проверка размера файла
  • Проверка количества файлов

Обзор

Поле для загрузки файлов в Filament работает на Filepond.

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')

Filament также поддерживает spatie/laravel-medialibrary. Более подробную информацию можно найти в документации к этому плагину.

Настройка диска и каталога хранения

По умолчанию файлы будут открыто загружаться на диск, указанный в конфигурационном файле. Чтобы изменить это, можно задать переменную окружения FILAMENT_FILESYSTEM_DISK.

Для корректного превью изображений и других файлов FilePond требует, чтобы файлы передавались из того же домена, что и приложение, или чтобы присутствовали соответствующие CORS-заголовки. Убедитесь, что переменная окружения APP_URL верна, или измените настройки драйвера файловой системы, чтобы установить правильный URL. Если файлы размещаются на отдельном домене, например S3, убедитесь, что настроены CORS-заголовки.

Чтобы изменить диск и каталог для определенного поля, а также видимость файлов, используйте методы disk(), directory() и visibility():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->disk('s3')
    ->directory('form-attachments')
    ->visibility('private')

Ответственность за удаление этих файлов с диска лежит на разработчике, поскольку Filament не знает, зависят ли они от чего-либо еще. Один из способов сделать это автоматически — наблюдение за событиями модели.

Загрузка нескольких файлов

Предусмотрена возможность загрузки нескольких файлов. В этом случае URL-адреса хранятся в JSON:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()

Если вы сохраняете URL-адреса файлов с помощью Eloquent, не забудьте добавить array cast к свойству модели:

use Illuminate\Database\Eloquent\Model;
 
class Message extends Model
{
    protected $casts = [
        'attachments' => 'array',
    ];
 
    // ...
}

Управление именами файлов

По умолчанию для вновь загружаемых файлов генерируется случайное имя. Это делается для того, чтобы не возникало конфликтов с существующими именами файлов.

Сохранение оригинальных имен файлов

Чтобы сохранить оригинальные имена загружаемых файлов, используется метод preserveFilenames():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->preserveFilenames()

Создание пользовательских имен файлов

Чтобы настроить генерирование имен файлов, можно использовать метод getUploadedFileNameForStorageUsing(), который возвращает строку из замыкания, построенную на основе $file, который был загружен:

use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
 
FileUpload::make('attachment')
    ->getUploadedFileNameForStorageUsing(
        fn (TemporaryUploadedFile $file): string => (string) str($file->getClientOriginalName())
            ->prepend('custom-prefix-'),
    )

Независимое хранение оригинальных имен файлов

С помощью метода storeFileNamesIn() можно сохранить случайно сгенерированные имена файлов, сохранив при этом оригинальное имя файла:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->storeFileNamesIn('attachment_file_names')

attachment_file_names теперь будет хранить оригинальное имя/имена загруженных файлов, чтобы их можно было сохранить в базе данных при отправке формы. Если загружается несколько файлов multiple(), убедитесь, что в это свойство модели Eloquent также добавлен array cast.

Режим аватара

Вы можете включить режим аватара для поля загрузки файла с помощью метода avatar():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('avatar')
    ->avatar()

Это позволит загружать только изображения, а когда они будут загружены, отобразит их в виде круга, который идеально подходит для аватаров.

Эта функция хорошо сочетается с функцией обрезки картинок в виде круга.

Редактор изображений

С помощью метода imageEditor() можно включить редактор изображений для поля загрузки файла:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageEditor()

Редактор можно открыть после загрузки изображения, нажав на значок карандаша. Редактор также открывается при нажатии на значок карандаша на существующем изображении, что приведет к его удалению и повторной загрузке при сохранении.

Обрезка изображений в соответствии с соотношением сторон

С помощью метода imageEditorAspectRatios() возможно разрешить пользователям обрезать изображения до определенного соотношения сторон:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatios([
        '16:9',
        '4:3',
        '1:1',
    ])

Кроме того, можно разрешить пользователям не выбирать соотношение сторон, "свободное кадрирование" (free cropping), передав в качестве параметра null:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatios([
        null,
        '16:9',
        '4:3',
        '1:1',
    ])

Настройка режима редактора изображений

Сменить режим редактора изображений можно с помощью метода imageEditorMode(), который принимает значения 1, 2 или 3. Эти параметры описаны в документации Cropper.js:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorMode(2)

Настройка цвета прозрачности заливки редактора изображений

По умолчанию редактор изображений делает пустое пространство вокруг изображения прозрачным. Его цвет можно изменить с помощью метода imageEditorEmptyFillColor():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorEmptyFillColor('#000000')

Установка размера области просмотра редактора изображений

С помощью методов imageEditorViewportWidth() и imageEditorViewportHeight() можно изменить размер области просмотра редактора изображений, которые генерируют соотношение сторон для использования на разных устройствах:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorViewportWidth('1920')
    ->imageEditorViewportHeight('1080')

Позволяет обрезать изображения в виде круга

С помощью метода circleCropper() можно разрешить пользователям обрезать изображения в виде круга:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->avatar()
    ->imageEditor()
    ->circleCropper()

Он прекрасно сочетается с методом avatar(), который отображает изображения в виде компактного круга.

Обрезка и изменение размера изображений без редактора

Filepond позволяет обрезать и изменять размер изображений перед их загрузкой, без необходимости использования отдельного редактора. Это можно настроить с помощью методов imageCropAspectRatio(), imageResizeTargetHeight() и imageResizeTargetWidth(). imageResizeMode() должен быть установлен для того, чтобы эти методы имели эффект – либо force, либо cover, либо contain.

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()
    ->imageResizeMode('cover')
    ->imageCropAspectRatio('16:9')
    ->imageResizeTargetWidth('1920')
    ->imageResizeTargetHeight('1080')

Изменение внешнего вида области загрузки файлов

Также можно изменить общий вид компонента Filepond. Доступные параметры для этих методов можно найти в документации Filepond.

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->imagePreviewHeight('250')
    ->loadingIndicatorPosition('left')
    ->panelAspectRatio('2:1')
    ->panelLayout('integrated')
    ->removeUploadedFileButtonPosition('right')
    ->uploadButtonPosition('left')
    ->uploadProgressIndicatorPosition('left')

Упорядочивание файлов

С помощью метода reorderable() можно также разрешить пользователям изменять порядок загруженных файлов при загрузке нескольких файлов:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->reorderable()

При использовании этого метода FilePond может добавлять вновь загруженные файлы в начало списка, а не в конец. Чтобы исправить это, используйте метод appendFiles():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->reorderable()
    ->appendFiles()

Открытие файлов в новой вкладке

С помощью метода openable() можно добавить кнопку для открытия каждого файла в новой вкладке:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->openable()

Загрузка файлов

Если требуется добавить кнопку загрузки к каждому файлу, можно использовать метод downloadable():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->downloadable()

Предварительный просмотр файлов

По умолчанию некоторые типы файлов могут быть предварительно просмотрены в FilePond. Если нужно отключить предварительный просмотр для всех файлов, можно использовать метод previewable(false):

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->previewable(false)

Перемещение файлов вместо копирования при отправке формы

По умолчанию файлы сначала загружаются в каталог временного хранения Livewire, а затем копируются в целевой каталог при отправке формы. Если требуется переместить файлы вместо этого, при условии, что временные файлы хранятся на том же диске, что и постоянные, можно использовать метод moveFiles():

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->moveFiles()

Предотвращение постоянного хранения файлов

Если необходимо запретить постоянное сохранение файлов при отправке формы, можно использовать метод storeFiles(false):

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->storeFiles(false)

При отправке формы вместо постоянно хранимого пути к файлу будет возвращен временный объект загрузки файла. Это идеально подходит для временных файлов, таких как импортированные CSV.

Ориентация изображений на основе их EXIF-данных

По умолчанию FilePond автоматически ориентирует изображения, основываясь на их EXIF-данных. Если требуется отключить это поведение, можно воспользоваться методом orientImagesFromExif(false):

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->orientImagesFromExif(false)

Скрытие кнопки удаления файла

Также можно скрыть кнопку удаления загруженного файла с помощью функции deletable(false):

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->deletable(false)

Предотвращение получения информации о файле

Пока форма загружается, она автоматически определяет, существуют ли файлы, каков их размер и тип. Все это делается на сервере. При использовании удаленного хранилища с большим количеством файлов это может занять много времени. Чтобы отключить эту функцию, можно использовать метод fetchFileInformation(false):

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->fetchFileInformation(false)

Настройка уведомления о загрузке

С помощью метода uploadingMessage() можно настроить сообщение о загрузке, которое будет отображаться в кнопке отправки формы:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->uploadingMessage('Uploading attachment...')

Проверка корректности загружаемых файлов

Помимо всех правил, перечисленных на странице валидации, есть дополнительные правила, специфичные для загрузки файлов.

Поскольку Filament работает на базе Livewire и использует его систему загрузки файлов, необходимо также обратиться к правилам проверки загрузки файлов Livewire по умолчанию в файле config/livewire.php. Они также задают по умолчанию максимальный размер файла 12 МБ.

Проверка типа файла

С помощью метода acceptedFileTypes() и передачи массива MIME-типов можно ограничить типы загружаемых файлов.

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('document')
    ->acceptedFileTypes(['application/pdf'])

Также можно использовать метод image(), чтобы разрешить все MIME-типы изображений.

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('image')
    ->image()

Проверка размера файла

Можно также ограничить размер загружаемых файлов в килобайтах:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachment')
    ->minSize(512)
    ->maxSize(1024)

Проверка количества файлов

С помощью методов minFiles() и maxFiles() можно настроить количество загружаемых файлов:

use Filament\Forms\Components\FileUpload;
 
FileUpload::make('attachments')
    ->multiple()
    ->minFiles(2)
    ->maxFiles(5)

Перевод с английского официальной документации Filament:
https://filamentphp.com/docs/3.x/forms/fields/file-upload

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)