PHPackages weldist/spatie-medialibrary-uuid-path-generator - 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. weldist/spatie-medialibrary-uuid-path-generator ActiveLibrary[Utility & Helpers](/categories/utility) weldist/spatie-medialibrary-uuid-path-generator =============================================== A UUID-based path generator for spatie/laravel-medialibrary. v1.0.0(4w ago)110MITPHPPHP ^8.3CI passing Since May 12Pushed 4w agoCompare [ Source](https://github.com/weldist/spatie-medialibrary-uuid-path-generator)[ Packagist](https://packagist.org/packages/weldist/spatie-medialibrary-uuid-path-generator)[ RSS](/packages/weldist-spatie-medialibrary-uuid-path-generator/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependencies (3)Versions (2)Used By (0) weldist/spatie-medialibrary-uuid-path-generator =============================================== [](#weldistspatie-medialibrary-uuid-path-generator) [![Tests](https://github.com/weldist/spatie-medialibrary-uuid-path-generator/actions/workflows/tests.yml/badge.svg)](https://github.com/weldist/spatie-medialibrary-uuid-path-generator/actions/workflows/tests.yml)[![PHP](https://camo.githubusercontent.com/c8d8dad6beb757a2b8acba331d16140813699543b88a37af0a81f20bd35f61de/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332532422d626c7565)](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). > A [weld.ist](https://weld.ist) project. > > Unofficial plugin. Not affiliated with Spatie. 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 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 [](#picking-a-shard-depth) The package ships four path generators. They share the same layout — `xx/.../xx//` — 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: GeneratorLayoutMax leaf directoriesSuited to`UuidLevel1PathGenerator``xx//`256Small catalogs (≲ 250 k files)`UuidLevel2PathGenerator``xx/xx//`65 536Medium catalogs (low millions)**recommended default**`UuidLevel3PathGenerator``xx/xx/xx//`~16.7 MLarge catalogs / busy object stores`UuidLevel4PathGenerator``xx/xx/xx/xx//`~4.3 BVery large pools or remote disks where flat LIST is expensiveWhen 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 ------------ [](#requirements) - PHP ^8.3 - spatie/laravel-medialibrary ^11.0 Installation ------------ [](#installation) ``` composer require weldist/spatie-medialibrary-uuid-path-generator ``` 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`, pick the depth you want and wire up the matching path generator together with the cascade-aware file remover: ``` 'path_generator' => Weldist\Spatie\MediaLibrary\UuidPathGenerator\PathGenerators\UuidLevel2PathGenerator::class, 'file_remover_class' => Weldist\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 ----------------------------------- [](#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](#picking-a-shard-depth)): ``` 'path_generator' => Weldist\Spatie\MediaLibrary\UuidPathGenerator\PathGenerators\UuidLevel2PathGenerator::class, ``` 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: ``` php artisan media-library:migrate-paths-to-uuid ``` 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: 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 promptReverting to DefaultPathGenerator --------------------------------- [](#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: ``` php artisan media-library:migrate-paths-from-uuid ``` 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: 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-library:prune-uuid-paths ``` Options: OptionDescription`disk`Disk to clean (defaults to `media-library.disk_name` config)`--shard=`Limit the scan to the given first-level shards (e.g. `--shard=55 --shard=ab`). Repeatable. Useful for splitting a large sweep into chunks or rerunning a partial scan on a remote disk. Defaults to every shard (`00`..`ff`).`--dry-run`List orphaned directories without deleting them`--force`Skip the production confirmation promptTesting ------- [](#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 ------- [](#license) This package is open-sourced software licensed under the [MIT license](https://opensource.org/license/MIT). ### Health Score 42 — FairBetter than 88% of packages Maintenance94 Actively maintained with recent releases Popularity9 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 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 28d 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 (2 commits)") --- Tags spatielaraveluuidmedialibrarypath-generator ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/weldist-spatie-medialibrary-uuid-path-generator/health.svg) ``` [![Health](https://phpackages.com/badges/weldist-spatie-medialibrary-uuid-path-generator/health.svg)](https://phpackages.com/packages/weldist-spatie-medialibrary-uuid-path-generator) ``` ### Alternatives [spatie/laravel-data Create unified resources and data transfer objects 1.8k33.0M871](/packages/spatie-laravel-data)[spatie/laravel-livewire-wizard Build wizards using Livewire 4111.1M6](/packages/spatie-laravel-livewire-wizard)[tapp/filament-form-builder User facing form builder using Filament components 141.9k2](/packages/tapp-filament-form-builder)[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)