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

x-laravel/spatie-medialibrary-uuid-path-generator

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

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 without any downtime:

1. While your config still points to DefaultPathGenerator, run:

2. Once it completes, switch the config to this package (pick the depth that suits your catalog — see Picking a shard depth):

The command reads media-library.path_generator to decide where files land, so set it to the depth you want before running 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.

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.