---
url: /reference/events.md
description: >-
  The three events Media Library Pro dispatches: MediaItemUploaded,
  MediaItemDeleted and MediaItemReplaced, with payload and listener examples.
---

# Events

All events live in `Hoceineel\FilamentMediaLibrary\Events` and carry one public property, `$item`, the `MediaItem` model. They use `Dispatchable` and `SerializesModels`, so a queued listener works.

| Event | Fired when | Payload |
|---|---|---|
| `MediaItemUploaded` | A file is stored in the library, by upload, URL import, the picker or `media-library:import`. | `public MediaItem $item` |
| `MediaItemDeleted` | Files are deleted from the browser, including a move to the trash. It fires once per item. | `public MediaItem $item` |
| `MediaItemReplaced` | A file's content is swapped: replace file, save an edit over the original, or restore a version. | `public MediaItem $item` |

`MediaItemDeleted` also fires for a soft delete, so check `$event->item->trashed()` to tell trash from permanent removal. `media-library:prune` removes files directly and does not fire it.

## Listening

Laravel discovers listeners by their type-hinted `handle` method:

```php
namespace App\Listeners;

use Hoceineel\FilamentMediaLibrary\Events\MediaItemUploaded;
use Illuminate\Contracts\Queue\ShouldQueue;

class NotifyAssetTeam implements ShouldQueue
{
    public function handle(MediaItemUploaded $event): void
    {
        logger()->info('New asset', [
            'name' => $event->item->name,
            'size' => $event->item->humanSize(),
            'uploaded_by' => $event->item->uploaded_by,
        ]);
    }
}
```

Or register one explicitly:

```php
use Hoceineel\FilamentMediaLibrary\Events\MediaItemReplaced;
use Illuminate\Support\Facades\Event;

Event::listen(MediaItemReplaced::class, function (MediaItemReplaced $event): void {
    Cache::forget("asset-{$event->item->getKey()}");
});
```

Use `MediaItemReplaced` to clear CDN or page caches, because the file URL stays the same when the content changes.