PHPackages                             waad/filament-media - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. waad/filament-media

ActiveLibrary[Image & Media](/categories/media)

waad/filament-media
===================

Filament integration for waad/media package for Media Upload Locally Or Cloud S3

v1.1.2(2mo ago)219MITPHPPHP ^8.1

Since Apr 2Pushed 2mo agoCompare

[ Source](https://github.com/waadmawlood/filament-media)[ Packagist](https://packagist.org/packages/waad/filament-media)[ Docs](https://github.com/waadmawlood/filament-media)[ RSS](/packages/waad-filament-media/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (3)Dependencies (6)Versions (5)Used By (0)

[![Logo](image1.png)](image1.png)

Filament Media
==============

[](#filament-media)

This package integrates [Filament](https://filamentphp.com) v3/v4/v5 with the [waad/media](https://github.com/waadmawlood/media) manager. It is an alternative to `spatie/laravel-medialibrary` for projects on waad/media. The `MediaUpload` form component aligns with your Eloquent model’s `registerCollections()` (single vs multiple, disks, labels).

Requirements
------------

[](#requirements)

- PHP: `^8.1`
- Filament: `^3.0|^4.0|^5.0`
- Livewire: `^3.5|^4.0`
- [waad/media](https://github.com/waadmawlood/media): `^4.1`

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require waad/filament-media
```

Setup & Usage
-----------------

[](#setup--usage)

Since this package works in tandem with `waad/media`, your Eloquent Models should use the `HasMedia` trait and implement `registerCollections`: [waad/media](https://github.com/waadmawlood/media) Package.

```
php artisan vendor:publish --provider="Waad\Media\MediaServiceProvider"
```

```
use Illuminate\Database\Eloquent\Model;
use Waad\Media\HasMedia;

class Post extends Model
{
    use HasMedia;

    public function registerCollections(array $attributes = []): array
    {
        return [
            'avatar' => [
                'disk' => 's3',
                'bucket' => 'avatars',
                'label' => 'User Avatar',
                'single' => true, // Only keeps one file
            ],
            'gallery' => [
                'disk' => 'public',
                'bucket' => 'photos',
                'label' => 'Photo Gallery',
                'single' => false, // Allows multiple files
            ],
        ];
    }
}
```

`MediaUpload::make('name')` uses the field **name** as the waad/media **collection** by default. Call `->collection(...)` only when the Filament field name should differ from the collection key (string), or when the collection must be resolved at runtime (`Closure`); pass `null` to rely on evaluation falling back to the field name.

Now, in your Filament resource or form:

```
use Waad\FilamentMedia\Forms\Components\MediaUpload;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            // Single file when registerCollections has 'single' => true for this key
            MediaUpload::make('avatar'),

            // Multiple files when 'single' => false; reorderable uses waad/media `index`
            MediaUpload::make('gallery')
                ->reorderable()
                ->image()
                ->maxSize(2048),

            // Single vs multiple follows `registerCollections`; other FileUpload APIs apply as usual
        ]);
}
```

The component loads existing media IDs for previews, syncs new uploads via `syncMedia`, removes files with `deleteMedia`, and persists reorder when only existing items change.

Reordering multiple files (`index`)
-----------------------------------

[](#reordering-multiple-files-index)

For collections with `'single' => false`, you can enable drag-and-drop reordering with Filament’s `reorderable()` (same as `FileUpload`). Order is stored in waad/media’s **`index`** column on the `media` table.

- **Loading the form:** existing files are listed sorted by `index`, then by id, so the UI matches the saved order.
- **Saving the form:** when only existing media are present (no new uploads in that save), the component writes the current list order back to the database as `index` values (`1`, `2`, `3`, …) for that collection.

```
MediaUpload::make('gallery')
    ->reorderable()
    ->image(),
```

Use this together with a multi-file collection in `registerCollections()`. Single-file collections ignore ordering.

Preview images in tables
------------------------

[](#preview-images-in-tables)

In list/table views, use Filament’s `ImageColumn` and resolve URLs from your model with [waad/media](https://github.com/waadmawlood/media)’s `getCollectionUrls()` (provided by `HasMedia`). Pass the same collection name you use in `registerCollections()` and in `MediaUpload::make(...)`.

[![ImageColumn](image2.png)](image2.png)

```
use Filament\Tables\Columns\ImageColumn;

ImageColumn::make('banner')
    ->getStateUsing(fn ($record) => $record->getCollectionUrls('banner')),
ImageColumn::make('gallery')
    ->getStateUsing(fn ($record) => $record->getCollectionUrls('gallery')),
```

- For a **single-file** collection (`'single' => true`), `getCollectionUrls` typically returns one URL string (or an empty value when there is no file).
- For a **multi-file** collection, it returns an array of URLs; `ImageColumn` can show them as a stacked preview when the state is an array.

Adjust the column name (`banner` here) to match your collection key.

Pruning old media
-----------------

[](#pruning-old-media)

[waad/media](https://github.com/waadmawlood/media) registers the `media:prune` Artisan command. It removes media files and database rows according to the retention setting `prune_media_after_day` in your published `config/media.php` (see the waad/media docs for details).

Run it manually or on a schedule (for example Laravel’s scheduler in `routes/console.php`):

```
php artisan media:prune
```

Testing
-------

[](#testing)

This package uses Pest for testing. To run tests:

```
composer test
```

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance84

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

4

Last Release

81d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/44348636?v=4)[Waad Mawlood](/maintainers/waadmawlood)[@waadmawlood](https://github.com/waadmawlood)

---

Top Contributors

[![waadmawlood](https://avatars.githubusercontent.com/u/44348636?v=4)](https://github.com/waadmawlood "waadmawlood (16 commits)")

---

Tags

filamentlaravelmediaspatie-laravel-medialibrarypluginfilesmediapluginsfilamentfilament-pluginfilament-pluginsupload filelaravel-mediaWaad Mawloodmedia-phpfilament mediafilament upload

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/waad-filament-media/health.svg)

```
[![Health](https://phpackages.com/badges/waad-filament-media/health.svg)](https://phpackages.com/packages/waad-filament-media)
```

###  Alternatives

[awcodes/filament-curator

A media picker plugin for FilamentPHP.

437356.9k24](/packages/awcodes-filament-curator)[webplusm/gallery-json-media

a filament media storing in a Json field

196.7k](/packages/webplusm-gallery-json-media)[wotz/filament-media-library

Media Library package for Filament

181.8k12](/packages/wotz-filament-media-library)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)