PHPackages jonhassall/has-uploaded-file - 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. [File & Storage](/categories/file-storage) 4. / 5. jonhassall/has-uploaded-file ActiveLibrary[File & Storage](/categories/file-storage) jonhassall/has-uploaded-file ============================ Trait for Laravel Eloquent models that manage uploaded files across storage disks 00PHP Since Jun 15Pushed 1mo agoCompare [ Source](https://github.com/jonhassall/HasUploadedFile)[ Packagist](https://packagist.org/packages/jonhassall/has-uploaded-file)[ RSS](/packages/jonhassall-has-uploaded-file/feed)WikiDiscussions main Synced 2w ago READMEChangelogDependenciesVersions (1)Used By (0) HasUploadedFile =============== [](#hasuploadedfile) A Laravel package that provides a reusable trait for Eloquent models that manage uploaded files. It standardizes upload state, file metadata, download helpers, streaming responses, and automatic cleanup when a model is deleted. Features -------- [](#features) ### HasUploadedFile Trait [](#hasuploadedfile-trait) Attach this trait to any model whose primary responsibility is tracking a stored file. **Key Features:** - **Upload State Tracking**: Consistent `uploaded_at` and `file_size` handling - **Automatic Cleanup**: Deletes the stored file when the model is deleted - **Query Scopes**: Filter uploaded and not-yet-uploaded records - **Download Helpers**: Binary download, inline view, stream download, and storage response helpers - **Storage Agnostic**: Works across local and remote Laravel disks - **Migration Helpers**: Add or remove the standard columns from migrations Requirements ------------ [](#requirements) - **Laravel:** 10.x through 13.x - **PHP:** 8.1 or higher Installation ------------ [](#installation) ### Option 1: Via Packagist [](#option-1-via-packagist) Install the package via Composer: ``` composer require jonhassall/has-uploaded-file ``` ### Option 2: Install Directly from GitHub [](#option-2-install-directly-from-github) Add this to your `composer.json`: ``` { "repositories": [ { "type": "vcs", "url": "https://github.com/jonhassall/HasUploadedFile.git" } ], "require": { "jonhassall/has-uploaded-file": "dev-main" } } ``` Then run: ``` composer install ``` Versioning and Branches ----------------------- [](#versioning-and-branches) - Stable releases use semantic version tags, for example: `v1.0.0` - The `main` branch is the primary development branch - Composer branch alias maps `dev-main` to `1.x-dev` for users tracking development - Patch releases should branch from `main`, then be tagged and pushed Release example: ``` git checkout main git pull origin main git tag -a v1.0.0 -m "Release v1.0.0" git push origin main --tags ``` Full release checklist: [RELEASE\_CHECKLIST.md](RELEASE_CHECKLIST.md) Quick Start ----------- [](#quick-start) ### Step 1: Add the Required Columns [](#step-1-add-the-required-columns) Create or update your migration: ``` use App\Models\Document; use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; Schema::create('documents', function (Blueprint $table) { $table->id(); $table->string('path'); $table->string('disk')->default('public'); Document::addUploadedFileColumns($table); $table->timestamps(); }); ``` ### Step 2: Add the Trait to Your Model [](#step-2-add-the-trait-to-your-model) ``` namespace App\Models; use Illuminate\Database\Eloquent\Casts\Attribute; use Illuminate\Database\Eloquent\Model; use JonHassall\HasUploadedFile\HasUploadedFile; class Document extends Model { use HasUploadedFile; protected $fillable = ['path', 'disk']; protected function filePath(): Attribute { return Attribute::make( get: fn () => $this->path, ); } protected function storageDiskName(): Attribute { return Attribute::make( get: fn () => $this->disk, ); } } ``` Usage Examples -------------- [](#usage-examples) ### Marking Upload State [](#marking-upload-state) ``` $document->markAsUploaded(true); $document->markAsNotUploaded(true); if ($document->is_uploaded) { // File is marked as uploaded } ``` ### Querying Uploaded Records [](#querying-uploaded-records) ``` $uploaded = Document::uploaded()->get(); $pending = Document::notUploaded()->get(); ``` ### Checking Storage State [](#checking-storage-state) ``` if ($document->fileExists()) { // Trust the cached uploaded flag } if ($document->fileExists(true)) { // Check the underlying storage disk } $size = $document->getFileSize(true); $url = $document->getFileUrl(); ``` ### Returning File Responses [](#returning-file-responses) ``` return $document->downloadFile('report.pdf'); return $document->streamDownload('report.pdf'); return $document->viewFile('report.pdf'); return $document->getFileResponse('report.pdf'); ``` ### Moving a File Between Disks [](#moving-a-file-between-disks) ``` $document->moveFileToDisk('s3', function ($model, $targetDisk) { $model->disk = $targetDisk; $model->save(); }); ``` Soft Deletes ------------ [](#soft-deletes) By default, the package does not delete files during a soft delete. Files are deleted when the model is force deleted. If you want files removed on soft delete as well, override this method in your model: ``` protected function deleteUploadedFileOnSoftDelete(): bool { return true; } ``` Notes and Caveats ----------------- [](#notes-and-caveats) - `filePath()` and `storageDiskName()` are required accessors. - The trait expects `uploaded_at` and `file_size` columns on the model table. - `streamWithRanges()` supports byte range streaming for local files automatically. For remote disks, range requests are only honored when the stream is seekable; otherwise it falls back to a normal streamed response. - `getFileResponse()` may load more data into memory depending on the storage driver implementation. Prefer `streamDownload()` or `viewFile()` for larger files. Releasing --------- [](#releasing) Use [RELEASE\_CHECKLIST.md](RELEASE_CHECKLIST.md) for the release workflow. ### Health Score 19 — LowBetter than 9% of packages Maintenance60 Regular maintenance activity Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project 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. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/9570507?v=4)[Jonathan Hassall](/maintainers/jonhassall)[@jonhassall](https://github.com/jonhassall) --- Top Contributors [![jonhassall](https://avatars.githubusercontent.com/u/9570507?v=4)](https://github.com/jonhassall "jonhassall (1 commits)") ### Embed Badge ![Health badge](/badges/jonhassall-has-uploaded-file/health.svg) ``` [![Health](https://phpackages.com/badges/jonhassall-has-uploaded-file/health.svg)](https://phpackages.com/packages/jonhassall-has-uploaded-file) ``` ### Alternatives [qcloud/cos-sdk-v5 PHP SDK for QCloud COS 2051.5M152](/packages/qcloud-cos-sdk-v5)[olivierbon/craft-squeeze Zip one or multiple craft assets on the fly for frontend user to download. 137.5k](/packages/olivierbon-craft-squeeze) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)