README

Standardized package for file uploads to MinIO in Filament projects.

Overview

fariz/filament-minio-uploader provides a small helper trait and form/column/entry helpers to standardize file uploads to MinIO (S3-compatible) in Filament v3 projects. It integrates with a configured S3 disk (commonly named s3) and helps with upload fields, preview columns and infolist entries using presigned/temporary URLs.

Requirements

PHP ^8.1
Laravel ^10.0 || ^11.0
Filament ^3.2
hugomyb/filament-media-action

Installation

Require the package via Composer:

composer require fariz/filament-minio-uploader

Filesystem (MinIO) Configuration

Add or adjust an S3-compatible disk in config/filesystems.php. Example configuration for MinIO:

's3' => [
    'driver' => 's3',
    'key' => env('MINIO_KEY'),
    'secret' => env('MINIO_SECRET'),
    'region' => env('MINIO_REGION', 'us-east-1'),
    'bucket' => env('MINIO_BUCKET'),
    'endpoint' => env('MINIO_ENDPOINT'), // e.g. http://127.0.0.1:9000
    'use_path_style_endpoint' => true,
],

Add these to your .env:

MINIO_KEY=your-minio-access-key
MINIO_SECRET=your-minio-secret
MINIO_REGION=us-east-1
MINIO_BUCKET=your-bucket
MINIO_ENDPOINT=http://127.0.0.1:9000

Note: use_path_style_endpoint => true is often required for MinIO compatibility.

Usage

The package provides two cooperating parts:

Model trait: Fariz\\FilamentMinioUploader\\HasStandardFileUpload — contains data-level helpers such as getPresignedUrl() and normalizePath() and can be used for accessors/mutators or cleanup logic on the model.
Filament UI helpers: Fariz\\FilamentMinioUploader\\Filament\\FileUploadComponents — a small helper class that builds Filament FileUpload, ImageColumn, ImageEntry, TextEntry and RepeatableEntry components. This is the recommended API to use in your Filament Resource classes.

Basic examples (recommended usage — call the helper from your Resource):

1) Form field (Filament Resource form) — recommended:

use Fariz\\FilamentMinioUploader\\Filament\\FileUploadComponents;

public static function form(Form $form): Form
{
    return $form->schema([
        // single file upload
        FileUploadComponents::uploadField('image', 'posts/images', false),

        // multiple files
        FileUploadComponents::uploadField('gallery', 'posts/gallery', true),
    ]);
}

2) Table column preview (Filament Resource table):

use Fariz\\FilamentMinioUploader\\Filament\\FileUploadComponents;

public static function table(Table $table): Table
{
    return $table->columns([
        FileUploadComponents::previewColumn('image'),
    ]);
}

3) Infolist entries / preview actions:

use Fariz\\FilamentMinioUploader\\Filament\\FileUploadComponents;

FileUploadComponents::previewEntry('image'),
FileUploadComponents::singleAttachmentEntry('document_path'),
FileUploadComponents::attachmentListEntry('attachments'),

4) Model-level usage (trait) — keep the trait when you need data-level behaviour (accessors/mutators):

use Fariz\\FilamentMinioUploader\\HasStandardFileUpload;

class Post extends Model
{
    use HasStandardFileUpload;

    // Example accessor that uses the trait helper
    public function getImageUrlAttribute(): ?string
    {
        return self::getPresignedUrl($this->image);
    }
}

Backward compatibility: the previous static methods on the trait (for example makeImageUploadField) still exist and will forward to the new FileUploadComponents helper, but they emit a deprecation notice. Prefer calling the FileUploadComponents methods directly in your Filament resources.

See src/HasStandardFileUpload.php and src/Filament/FileUploadComponents.php for exact method signatures and implementation details.

Error handling & logging

The helper attempts to generate temporary/presigned URLs for preview. If generating temporary URLs fails (for example due to SDK/credential issues), it falls back to using the disk url() when possible. Errors are logged to your application log.

Testing & Debugging

Ensure the configured S3/MinIO disk can generate temporary URLs via the AWS SDK.
Check storage/logs/laravel.log for errors related to presigned URL generation.

fariz / filament-minio-uploader

Maintainers

Details