PHPackages x-laravel/spatie-media-library-uuid-path - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. x-laravel/spatie-media-library-uuid-path Abandoned → [x-laravel/spatie-medialibrary-uuid-path-generator](/?search=x-laravel%2Fspatie-medialibrary-uuid-path-generator)Library[Utility & Helpers](/categories/utility) x-laravel/spatie-media-library-uuid-path ======================================== A UUID-based path generator for spatie/laravel-medialibrary. v1.0.0(1mo ago)17↓100%MITPHPPHP ^8.2CI passing Since Apr 22Pushed 1mo agoCompare [ Source](https://github.com/x-laravel/spatie-media-library-uuid-path)[ Packagist](https://packagist.org/packages/x-laravel/spatie-media-library-uuid-path)[ RSS](/packages/x-laravel-spatie-media-library-uuid-path/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependenciesVersions (2)Used By (0) spatie-media-library-uuid-path ============================== [](#spatie-media-library-uuid-path) [![Tests](https://github.com/x-laravel/spatie-media-library-uuid-path/actions/workflows/tests.yml/badge.svg)](https://github.com/x-laravel/spatie-media-library-uuid-path/actions/workflows/tests.yml)[![PHP](https://camo.githubusercontent.com/187240af044d09d5b14a1d9d9ebdf3f7a993e4c7bc09bdb46b4ba661a891bf5b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c7565)](https://www.php.net)[![Laravel](https://camo.githubusercontent.com/42e62a9adb05b6cb16993782fd4b04b64a76be3ff5704d170001885eb70c8448/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d726564)](https://laravel.com)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE.md) A UUID-based path generator for [spatie/laravel-medialibrary](https://github.com/spatie/laravel-medialibrary). The Problem ----------- [](#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 ------------ [](#the-solution) This package distributes files evenly by turning the first 8 characters of each media UUID into a four-level directory hierarchy: ``` 55/0e/84/00/550e8400-e29b-41d4-a716-446655440000/photo.jpg ``` Conversions and responsive images are placed in dedicated subdirectories under the UUID folder: ``` 55/0e/84/00/550e8400-e29b-41d4-a716-446655440000/conversions/ 55/0e/84/00/550e8400-e29b-41d4-a716-446655440000/responsive-images/ ``` Benefits: - **Performance:** Each directory 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. Requirements ------------ [](#requirements) - PHP ^8.2 - spatie/laravel-medialibrary ^11.0 Installation ------------ [](#installation) ``` composer require x-laravel/spatie-media-library-uuid-path ``` Setup ----- [](#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`: ``` 'path_generator' => \XLaravel\SpatieMediaLibraryUuidPath\UuidPathGenerator::class, 'file_remover_class' => \XLaravel\SpatieMediaLibraryUuidPath\UuidFileRemover::class, ``` > **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 ----------------------------------- [](#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: ``` 'path_generator' => \XLaravel\SpatieMediaLibraryUuidPath\UuidPathGenerator::class, 'file_remover_class' => \XLaravel\SpatieMediaLibraryUuidPath\UuidFileRemover::class, ``` The command 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: OptionDescription`disk`Disk to migrate (defaults to `media-library.disk_name` config)`--dry-run`Preview what would be moved without touching any files`--force`Skip the production confirmation promptCleaning Orphaned Directories ----------------------------- [](#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: OptionDescription`disk`Disk to clean (defaults to `media-library.disk_name` config)`--dry-run`List orphaned directories without deleting them`--force`Skip the production confirmation promptRunning Tests ------------- [](#running-tests) ``` # Locally vendor/bin/phpunit # Via Docker (specific PHP version) docker compose --profile php82 run --rm php82 docker compose --profile php83 run --rm php83 docker compose --profile php84 run --rm php84 docker compose --profile php85 run --rm php85 ``` ### Health Score 39 — LowBetter than 84% of packages Maintenance90 Actively maintained with recent releases Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 48d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2bdb64c6c087c331b8bd5906bb1aa7eb06bc83af3654a48ba8ab9da365976651?d=identicon)[X-Adam](/maintainers/X-Adam) --- Top Contributors [![x-adam](https://avatars.githubusercontent.com/u/60411758?v=4)](https://github.com/x-adam "x-adam (3 commits)") --- Tags spatielaraveluuidmedia librarypath-generator ### Embed Badge ![Health badge](/badges/x-laravel-spatie-media-library-uuid-path/health.svg) ``` [![Health](https://phpackages.com/badges/x-laravel-spatie-media-library-uuid-path/health.svg)](https://phpackages.com/packages/x-laravel-spatie-media-library-uuid-path) ``` ### Alternatives [spatie/laravel-data Create unified resources and data transfer objects 1.8k33.0M871](/packages/spatie-laravel-data)[spatie/laravel-onboard A Laravel package to help track user onboarding steps 827388.5k5](/packages/spatie-laravel-onboard)[spatie/laravel-livewire-wizard Build wizards using Livewire 4111.1M6](/packages/spatie-laravel-livewire-wizard)[spatie/laravel-screenshot Take screenshots of web pages in Laravel apps 8158.6k3](/packages/spatie-laravel-screenshot)[victord11/ssl-certification-health-check A Laravel Health check to SSL certification 17153.0k](/packages/victord11-ssl-certification-health-check)[spatie/filament-simple-stats Opinionated prebuilt stat widgets to quickly add to your Filament dashboards. 2621.7k](/packages/spatie-filament-simple-stats) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)