PHPackages mattmy/laravel-file-magic - 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. mattmy/laravel-file-magic ActiveLibrary mattmy/laravel-file-magic ========================= A strongly typed file management package for Laravel. v0.1.0(yesterday)01↑2900%MITPHPPHP ^8.3CI passing Since Jul 30Pushed yesterdayCompare [ Source](https://github.com/mattmy/laravel-file-magic)[ Packagist](https://packagist.org/packages/mattmy/laravel-file-magic)[ RSS](/packages/mattmy-laravel-file-magic/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (16)Versions (2)Used By (0) FileMagic ========= [](#filemagic) [English](README.md) | [繁體中文](README.zh-TW.md) FileMagic is a file-management package built exclusively for Laravel. It provides one consistent workflow for accepting, validating, storing, querying, downloading, and deleting files through Laravel Filesystem and Eloquent. Requirements ------------ [](#requirements) - PHP 8.3 or later - Laravel 12 or 13 - PHP `ext-fileinfo` - A configured Laravel Filesystem disk Composer checks `ext-fileinfo` during installation because FileMagic detects MIME types from actual file contents instead of trusting filenames or client-provided MIME types. Remote HTTP(S) imports through `fromUrl()` additionally need PHP `ext-curl`. Without it, all other features remain available, while storing a remote source throws `RemoteDownloadUnavailable`. Image resizing additionally needs `intervention/image` 4.0 or later and GD or Imagick. ZIP downloads additionally need PHP `ext-zip`. Installation ------------ [](#installation) ``` composer require mattmy/laravel-file-magic php artisan vendor:publish --tag=file-magic-config php artisan vendor:publish --tag=file-magic-migrations php artisan migrate ``` Quick start ----------- [](#quick-start) Store an uploaded file: ``` use Mattmy\FileMagic\Facades\FileMagic; $file = FileMagic::fromUpload($uploadedFile) ->onDisk('local') ->inDirectory('documents') ->named('contract') ->store(); ``` Retrieve it by ID, UUID, model, array, or Laravel Collection: ``` $file = FileMagic::find($uuid)->one(); return FileMagic::find($file)->download(); ``` The same `PendingFile` workflow supports local paths, content, Base64, remote HTTP(S) files, and generated TXT, JSON, and CSV documents: ``` $document = FileMagic::json([ 'message' => 'Hello', ]) ->onDisk('s3') ->inDirectory('exports') ->named('message') ->store(); ``` Highlights ---------- [](#highlights) - Strict content inspection, size limits, MIME allowlists, and safe path handling - Streaming storage, reads, downloads, and bounded ZIP creation - SSRF-resistant URL imports with TLS verification enabled by default - Best-effort image resizing with Intervention Image 4 - Collision policies with recovery for failed overwrite operations - Ordered batch lookup, consistency-aware batch deletion, and storage audits - Custom stored-file model and table support - English and Traditional Chinese documentation `Overwrite` creates a complete backup on the PHP server's local temporary disk before replacing an object. It uses additional disk space and I/O, so it is slower than normal storage; prefer the default `Unique` policy unless the same storage path must be preserved. Documentation ------------- [](#documentation) The complete guide, configuration reference, security notes, examples, and troubleshooting information are available at: **[Read the FileMagic documentation](https://mattmy.github.io/laravel-file-magic-docs/)** - [Getting started](https://mattmy.github.io/laravel-file-magic-docs/guide/getting-started) - [Storing files](https://mattmy.github.io/laravel-file-magic-docs/guide/storing-files) - [Remote files](https://mattmy.github.io/laravel-file-magic-docs/guide/remote-files) - [Documents and images](https://mattmy.github.io/laravel-file-magic-docs/guide/documents-and-images) - [Querying files](https://mattmy.github.io/laravel-file-magic-docs/guide/querying-files) - [ZIP and deletion](https://mattmy.github.io/laravel-file-magic-docs/guide/zip-and-deletion) - [Consistency audits](https://mattmy.github.io/laravel-file-magic-docs/guide/maintenance) - [Models and exceptions](https://mattmy.github.io/laravel-file-magic-docs/guide/models-and-exceptions) - [API reference and troubleshooting](https://mattmy.github.io/laravel-file-magic-docs/guide/reference) Consistency audits ------------------ [](#consistency-audits) `php artisan file-magic:audit` checks whether every database record still has its `disk + path` object. It is read-only by default. Each record causes one filesystem `exists()` call; remote disks such as S3 can therefore add execution time and request charges. `--chunk` limits database memory, not storage requests. The command never lists storage or deletes physical objects. Cleanup requires `--delete-missing-records` and confirmation, or `--force` in non-interactive environments. Cleanup uses one bulk database delete per chunk, does not dispatch per-model Eloquent events, and is not one transaction: if a later chunk fails, earlier chunks may already be deleted. Storage or network errors are treated as unknown and never as proof that an object is missing. Read the [audit guide](https://mattmy.github.io/laravel-file-magic-docs/guide/maintenance)before enabling cleanup or scheduling the command. Security -------- [](#security) Applications must authorize every file operation and retain Laravel request validation at the HTTP boundary. Treat original filenames, client MIME values, remote content, and stored bytes as untrusted. See the [security guide](https://mattmy.github.io/laravel-file-magic-docs/guide/reference#security)before accepting untrusted files or URLs. Report vulnerabilities privately according to [SECURITY.md](SECURITY.md). Consistency audits ------------------ [](#consistency-audits-1) `php artisan file-magic:audit` checks whether every database record still has its `disk + path` object. It is read-only by default. Each record causes one filesystem `exists()` call; remote disks such as S3 can therefore add execution time and request charges. `--chunk` limits database memory, not storage requests. Cleanup requires `--delete-missing-records` and confirmation, or `--force` in non-interactive environments. Cleanup uses one bulk database delete per chunk, does not dispatch per-model Eloquent events, and is not one transaction: if a later chunk fails, earlier chunks may already be deleted. Storage or network errors are treated as unknown and never as proof that an object is missing. Read the [audit guide](https://mattmy.github.io/laravel-file-magic-docs/guide/maintenance)before enabling cleanup or scheduling the command. License ------- [](#license) FileMagic is open-source software licensed under the [MIT License](LICENSE). Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request. Releases follow [Semantic Versioning](https://semver.org/) and are documented in [CHANGELOG.md](CHANGELOG.md). ### Health Score 38 — LowBetter than 83% of packages Maintenance100 Actively maintained with recent releases Popularity2 Limited adoption so far Community8 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 96.6% 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 1d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/35b29e408d21b77a39e71ecf41c7021763aa6ec1cf7e0a386c33f8a4e6c7290d?d=identicon)[mattmy](/maintainers/mattmy) --- Top Contributors [![mattmy](https://avatars.githubusercontent.com/u/167904136?v=4)](https://github.com/mattmy "mattmy (28 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") --- Tags composerfile-managementfile-processingfile-storagefile-validationlaravellaravel-filesystemlaravel-packagephp ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/mattmy-laravel-file-magic/health.svg) ``` [![Health](https://phpackages.com/badges/mattmy-laravel-file-magic/health.svg)](https://phpackages.com/packages/mattmy-laravel-file-magic) ``` ### Alternatives [moonshine/moonshine Laravel administration panel 1.3k253.1k86](/packages/moonshine-moonshine)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[laravel/ai The official AI SDK for Laravel. 1.0k3.2M256](/packages/laravel-ai)[psalm/plugin-laravel Psalm plugin for Laravel 3345.3M348](/packages/psalm-plugin-laravel)[illuminate/queue The Illuminate Queue package. 20432.6M1.7k](/packages/illuminate-queue) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)