Download the PHP package weldist/spatie-medialibrary-uuid-path-generator without Composer

weldist/spatie-medialibrary-uuid-path-generator

A UUID-based path generator for spatie/laravel-medialibrary.

A weld.ist project.

Unofficial plugin. Not affiliated with Spatie.

The Problem

spatie/laravel-medialibrary's default DefaultPathGenerator stores media files in a flat structure based on the primary key (ID):

This works fine for small applications, but causes serious issues as the number of media files grows:

• File system performance degradation: File systems like ext4 and NTFS slow down directory listings when thousands of subdirectories exist under a single parent.
• Predictable URLs: The sequential ID-based structure makes media file URLs trivially easy to enumerate.
• Operational overhead: Bulk-moving, backing up, or migrating files to a CDN becomes harder with a flat layout.

The Solution

This package distributes files by turning the leading characters of each media UUID into a sharded directory hierarchy. You pick the shard depth that fits your catalog size:

Conversions and responsive images are placed in dedicated subdirectories under the UUID folder:

Benefits:

• Performance: Each shard level holds at most 256 subdirectories, spreading the file system load evenly.
• Security: The UUID-based random structure makes file paths unpredictable and resistant to enumeration.
• Uniqueness: Every media file gets its own UUID directory, eliminating any risk of path collisions.

Picking a shard depth

The package ships four path generators. They share the same layout — xx/.../xx/<uuid>/ — and differ only in how many two-character shard levels they prepend. Pick the smallest depth that still keeps leaf directories under control for your catalog size:

When in doubt, start with Level2 — it handles up to ~10 million files comfortably and keeps cascade cleanup, LIST traversal, and path readability all in a sensible range. Migrating to a deeper layout later is cheaper than overshooting now and dragging around millions of mostly-empty intermediate directories.

Requirements

• PHP ^8.3
• spatie/laravel-medialibrary ^11.0

Installation

Setup

Publish the spatie/laravel-medialibrary config (if you haven't already) and set the path_generator option:

In config/media-library.php, pick the depth you want and wire up the matching path generator together with the cascade-aware file remover:

Swap UuidLevel2PathGenerator for UuidLevel1PathGenerator, UuidLevel3PathGenerator, or UuidLevel4PathGenerator if you need a different shard depth. The file remover and the artisan commands shipped with this package introspect this config and automatically follow the depth you chose — there is no separate setting to keep in sync.

Why UuidFileRemover? The default file remover deletes the UUID directory but leaves the empty shard parent directories (55/0e/84/00/) behind. UuidFileRemover cascades upward and removes each shard level when it becomes empty.

Migrating from DefaultPathGenerator

If your project already has media files stored with spatie's default ID-based structure (1/photo.jpg, 2/photo.jpg), you can migrate them to the UUID path structure.

1. Switch media-library.path_generator to one of this package's UUID generators (pick the depth that suits your catalog — see Picking a shard depth):

The migration command reads this config to decide where files land and refuses to run unless it points to a UUID generator. Switching file_remover_class to UuidFileRemover is optional at this stage — it only affects future deletions (cascade-cleanup of empty shard parents) and can be flipped any time.

2. Run the migration:

It moves all files (including conversions and responsive images), deletes the old ID directories, and is safe to re-run — it skips media whose old directory no longer exists.

Heads up — read window during migration. As soon as Step 1 lands, the application starts resolving media URLs through the UUID generator while the actual files still sit at their ID-based paths. Any read between Step 1 and Step 2 will 404. Schedule the two steps back-to-back during low traffic, or use --dry-run first to estimate the move duration.

Options:

Reverting to DefaultPathGenerator

If you need to undo the migration and put files back under spatie's ID-based layout, run the inverse command before switching the config away from the UUID generator:

1. With media-library.path_generator still pointing at a UUID generator, run:

It moves each media's main file, conversions, and responsive images from the UUID shard path back to the ID-based path, then cascade-cleans empty shard parents.

2. Switch media-library.path_generator back to Spatie\MediaLibrary\Support\PathGenerator\DefaultPathGenerator (and file_remover_class back to Spatie\MediaLibrary\Support\FileRemover\DefaultFileRemover if you swapped that earlier).

Heads up — read window during reverse migration. Symmetric to the forward migration: while files are being moved, URLs still resolved through the UUID generator (because the config hasn't flipped yet) keep working, but as soon as you flip the config in Step 2 any URL not yet served from the new ID path returns the new layout. Schedule the two steps back-to-back, ideally during low traffic.

Options:

Cleaning Orphaned Directories

spatie's built-in media-library:clean command identifies orphaned directories using an is_numeric() check, which only works for the default ID-based path structure. This package ships a UUID-aware replacement:

Options:

Testing

License

This package is open-sourced software licensed under the MIT license.