Laravel Storage Dedupler: Stop Duplicate File Uploads | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://msaied.com) - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [About](https://msaied.com#about) [ Contact](https://msaied.com#contact) Menu Menu ---- Close - [HomeStart here](https://msaied.com) - [ProjectsCase studies](https://msaied.com/projects) - [ArticlesEngineering notes](https://msaied.com/articles) - [CertificatesCredentials](https://msaied.com/certificates) - [AboutHow I work](https://msaied.com#about) - [ContactGet in touch](https://msaied.com#contact) [Start a conversation](https://msaied.com#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://msaied.com) 2. / 3. [Articles](https://msaied.com/articles) 4. / 5. [Laravel](https://msaied.com/articles?category=laravel) 6. / 7. Prevent Duplicate File Uploads With Laravel Storage Dedupler [Laravel](https://msaied.com/articles?category=laravel) [Composer Pacakge](https://msaied.com/articles?category=composer-pacakge) Prevent Duplicate File Uploads With Laravel Storage Dedupler ============================================================= Laravel Storage Dedupler uses SHA-1 hashing to detect and skip duplicate file writes, letting multiple models share one stored file while each keeps its own attachment record. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://msaied.com#person) Published 3 Nov 2026 · Updated 8 Nov 2026 · 3 min read ShareCopy linkCopied ![Prevent Duplicate File Uploads With Laravel Storage Dedupler](https://cdn.msaied.com/819/3c1bb5eb13679baf8274303d250566c1.png) On this page +1. [Stop Storing the Same File Twice](#stop-storing-the-same-file-twice) 2. [Storing Files Without Duplicates](#storing-files-without-duplicates) 3. [Attaching Files to Eloquent Models](#attaching-files-to-eloquent-models) 4. [Detaching and Cleanup](#detaching-and-cleanup) 5. [Analysing a Legacy Directory](#analysing-a-legacy-directory) 6. [Key Takeaways](#key-takeaways) Stop Storing the Same File Twice -------------------------------- Every time a user uploads an identical document to multiple posts, your disk grows without good reason. [Laravel Storage Dedupler](https://github.com/maxkhim/laravel-storage-dedupler), created by Khimusov Maxim, solves this by computing a SHA-1 hash of each incoming file and checking for an existing `UniqueFile` record before writing anything to disk. If the hash already exists, the package returns the existing record instead of creating a duplicate. The package supports PHP `^8.2` and Laravel 10 through 13. Install it with Composer and run the bundled Artisan command: ```bash composer require maxkhim/laravel-storage-dedupler php artisan dedupler:install ``` The install command runs the package migrations and checks your storage configuration. The default disk is named `deduplicated` and maps to a private local path at `storage/app/deduplicated`. You can point it at a remote disk such as S3 by adjusting your `filesystems.php` config. Storing Files Without Duplicates -------------------------------- The `Dedupler` facade accepts uploaded files, local paths, or raw string content: ```php use Maxkhim\Dedupler\Facades\Dedupler; $content = 'Notes for the November release.'; $first = Dedupler::storeFromContent($content, 'release-notes.txt'); $second = Dedupler::storeFromContent($content, 'notes-copy.txt'); $first->id === $second->id; // true — one file, two references ``` The SHA-1 hash doubles as the `UniqueFile` record's primary key. A matching hash returns the existing record regardless of the incoming filename. All three storage methods — `storeFromContent()`, `storeFromUploadedFile()`, and `storeFromPath()` — can return `null` on an invalid source or a storage error, so always check the result before accessing its properties. Attaching Files to Eloquent Models ---------------------------------- Add the `Deduplable` trait to any model that needs file attachments: ```php use Illuminate\Database\Eloquent\Model; use Maxkhim\Dedupler\Traits\Deduplable; class Post extends Model { use Deduplable; } ``` Then store and attach in your controller: ```php $post = Post::findOrFail($postId); $file = $post->storeUploadedFile($request->file('attachment')); if ($file === null) { throw new RuntimeException('Could not store the attachment.'); } // A second post references the same physical file $anotherPost = Post::findOrFail($anotherPostId); $anotherPost->attachUniqueFile($file->id); ``` The attachment table records the model type and ID, so different model classes can share the same underlying file. The trait also exposes `storeLocalFile()` and `storeContentFile()`. When attaching by hash with `attachUniqueFile()`, you can pass the original filename as a second argument because the method does not copy it automatically. Detaching and Cleanup --------------------- Remove an attachment with: ```php $post->detachUniqueFile($file->id); ``` Dedupler keeps the file as long as at least one other model references it. Detaching the last reference deletes both the stored file and its `UniqueFile` record by default. If your application must retain files after all attachments are removed, review this behaviour before adopting the detach method. Analysing a Legacy Directory ---------------------------- Before migrating an existing upload folder, you can run a read-only scan: ```bash php artisan dedupler:analyse-legacy /absolute/path/to/legacy/storage/directory ``` The command scans subdirectories for matching SHA-1 hashes, reports duplicate counts, and estimates potential space savings. It does not move or delete any files. Key Takeaways ------------- - SHA-1 hashing prevents duplicate writes; the hash is also the `UniqueFile` primary key. - The `Dedupler` facade handles uploads, local paths, and raw content. - The `Deduplable` trait wires file storage and attachment directly onto Eloquent models. - Multiple models — even of different types — can share one physical file. - Detaching the last reference deletes the file and its database record by default. - A legacy analysis command estimates savings without touching existing files. - Supports PHP 8.2+ and Laravel 10, 11, 12, and 13. --- *Source: [Prevent Duplicate File Uploads With Laravel Storage Dedupler — Laravel News](https://laravel-news.com/laravel-storage-dedupler)* - [Laravel](https://msaied.com/articles?search=Laravel) - [File Storage](https://msaied.com/articles?search=File%20Storage) - [Deduplication](https://msaied.com/articles?search=Deduplication) - [Composer Package](https://msaied.com/articles?search=Composer%20Package) - [Eloquent](https://msaied.com/articles?search=Eloquent) Frequently asked questions --------------------------- Does installing Laravel Storage Dedupler affect existing Laravel storage calls or remove duplicate files already on disk?No. Deduplication only applies to files stored through the Dedupler facade or the Deduplable trait. Installing the package does not modify existing calls to Laravel's storage methods and does not remove duplicate files that are already on disk. What happens when the last model detaches a shared file?By default, Dedupler deletes both the physical file from disk and its UniqueFile database record when the final attachment is removed. If your application needs to retain files after all attachments are gone, you should review this behaviour before using the detach method. How can I check an existing upload directory for duplicates before migrating to Dedupler?Run `php artisan dedupler:analyse-legacy /absolute/path/to/directory`. The command scans the directory and its subdirectories for matching SHA-1 hashes, reports duplicate counts, and estimates potential space savings without moving or deleting any files. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://msaied.com#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://msaied.com#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleFlock: A Free, Native Laravel Herd Alternative for macOS, Windows, and Linux](https://msaied.com/articles/flock-a-free-native-laravel-herd-alternative-for-macos-windows-and-linux) [Next articlePost Mortem: How Laravel Patched PHP and Node.js Vulnerabilities Across Its Entire Fleet](https://msaied.com/articles/post-mortem-how-laravel-patched-php-and-nodejs-vulnerabilities-across-its-entire-fleet) On this page ------------- 1. [Stop Storing the Same File Twice](#stop-storing-the-same-file-twice) 2. [Storing Files Without Duplicates](#storing-files-without-duplicates) 3. [Attaching Files to Eloquent Models](#attaching-files-to-eloquent-models) 4. [Detaching and Cleanup](#detaching-and-cleanup) 5. [Analysing a Legacy Directory](#analysing-a-legacy-directory) 6. [Key Takeaways](#key-takeaways) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://msaied.com#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/818/b17de0c62dc689581d4135b9cb797240.png) Laravel · 4 min read### Laravel Herd 2: Coding Agents, Workspaces, and Cloud Deploys 5 Nov 2026 ](https://msaied.com/articles/laravel-herd-2-coding-agents-workspaces-and-cloud-deploys) [ ![](https://cdn.msaied.com/817/1f6e0273ce6e6ecf37ad8c7616c60135.png) Laravel · 4 min read### Post Mortem: How Laravel Patched PHP and Node.js Vulnerabilities Across Its Entire Fleet 4 Nov 2026 ](https://msaied.com/articles/post-mortem-how-laravel-patched-php-and-nodejs-vulnerabilities-across-its-entire-fleet) [ ![](https://cdn.msaied.com/816/a5801f7786d2c70f010c322468e7d2b0.png) Laravel · 4 min read### Flock: A Free, Native Laravel Herd Alternative for macOS, Windows, and Linux 3 Nov 2026 ](https://msaied.com/articles/flock-a-free-native-laravel-herd-alternative-for-macos-windows-and-linux) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://msaied.com#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://msaied.com) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://msaied.com/sitemap.xml)