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):

1/photo.jpg
2/photo.jpg
3/photo.jpg
...

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:

# Level 2 (recommended default — see "Picking a shard depth" below)
55/0e/550e8400-e29b-41d4-a716-446655440000/photo.jpg

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

55/0e/550e8400-e29b-41d4-a716-446655440000/conversions/
55/0e/550e8400-e29b-41d4-a716-446655440000/responsive-images/

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

composer require x-laravel/spatie-media-library-uuid-path

Setup

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

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config"

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

'path_generator' => XLaravel\Spatie\MediaLibrary\UuidPathGenerator\PathGenerators\UuidLevel2PathGenerator::class,

'file_remover_class' => XLaravel\Spatie\MediaLibrary\UuidPathGenerator\UuidFileRemover::class,

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:

php artisan media:migrate-to-uuid

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

'path_generator' => XLaravel\Spatie\MediaLibrary\UuidPathGenerator\PathGenerators\UuidLevel2PathGenerator::class,
'file_remover_class' => XLaravel\Spatie\MediaLibrary\UuidPathGenerator\UuidFileRemover::class,

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:

php artisan media:clean-uuid

Options:

Testing

# Build first (once per PHP version)
DOCKER_BUILDKIT=0 docker compose --profile php83 build

# Run tests
docker compose --profile php83 up
docker compose --profile php84 up
docker compose --profile php85 up

License

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