Download the PHP package waad/media without Composer

Media Files Package

A Laravel package for managing media files across multiple storage drivers (local, S3, and any Laravel filesystem disk) with Eloquent model relationships. An alternative to spatie/laravel-medialibrary.

Authors

• Waad Mawlood
• [email protected]

Requirements

• PHP >= 8.1
• Laravel 9, 10, 11, 12, or 13

Installation

1. Install via Composer:

2. Publish the configuration and migration files:

3. Edit the config file at config/media.php

4. Run the migrations:

5. (Optional) Create storage symbolic links:

Usage

Setup the Trait

Add the HasMedia trait to any Eloquent model:

Uploading Media

The upload service works with any Laravel filesystem disk — local, S3, or any custom driver. Just set the disk() and it handles the rest.

Media Collections

Register custom collections in your model to define specific media groups with their own storage configuration:

When uploading to a registered collection, its disk, bucket, and label are applied automatically:

Retrieving Media

Ordering Media by Index

Use orderByIndexMedia() to order media results by the index column. This is enabled by default, so media is automatically sorted by index unless explicitly disabled. default value for orderByIndexMedia() method is true so you can remove it when you want to order by index.

The orderByIndexMedia() method is fluent and can be chained with any media retrieval method that returns a collection or query result.

Syncing Media

Use syncMedia() when you want to remove existing rows in a collection and optionally upload replacements. Deletes run before the new upload, and only affect the active collection (the default collection, or the one set with collection() on the chain, or the $collection argument passed to upload()). Media in other collections on the same model is left alone.

Remove specific records, then upload

Pass database IDs of Media rows to soft-delete before new files are stored. IDs that do not belong to the active collection are ignored (no rows removed).

Replace everything in the collection

If you omit the second argument (or pass an empty array), existing media in that collection is removed first, then new files are uploaded. This is useful for a full “replace gallery” flow.

Additive uploads (no removal)

To upload new files without running the sync removal step, use syncMediaWithoutDettached() or chain setIsWithDettachedSync(false) after syncMedia():

You can still combine with collection(), disk(), and the rest of the fluent API as with addMedia().

Deleting Media

Approving Media

File Utilities

The upload service provides disk-aware utility methods that work with any storage driver:

Filament

To use waad/media inside Filament admin panels, install the companion package waad/filament-media. It provides a MediaUpload form component that lines up with HasMedia and registerCollections() (single vs multiple files, disks, reordering via index, and sync behavior).

• Plugin page (docs & requirements): Media Library — Filament
• This package (filament plugin): waad/filament-media

See the Filament plugin documentation for setup, MediaUpload::make(...), and table previews with getCollectionUrls().

Configuration

Customize the package in config/media.php:

Media Model Attributes

Artisan Commands

Features

• Multiple file upload support
• Works with any Laravel filesystem disk (local, S3, etc.)
• Collection management with per-collection disk/bucket configuration
• Soft deletes with withTrashed support
• File approval system
• Automatic image metadata extraction (width, height)
• File utilities (exists, size, metadata, delete, temporary URL)
• Automatic file cleanup via media:prune
• Polymorphic media relationships
• File statistics (total size, total count) — global and per-collection
• Customizable date serialization format
• syncMedia() with collection-scoped deletes (by ID or full collection replace), plus additive uploads via syncMediaWithoutDettached() or setIsWithDettachedSync(false)
• orderByIndexMedia() for index-based media ordering across all retrieval methods

Testing

License

MIT © Waad Mawlood