Download the PHP package mohamedsamy902/advanced-file-upload without Composer

Laravel Media Vault

A highly scalable, production-ready file and media management package for Laravel. It provides unified management for centralized uploads and custom polymorphic model fields, seamlessly handling URL downloads, image processing, massive datasets with robust memory safety, and chunked resumable uploads.

[]()

Table of Contents

1. Features
2. Requirements
3. Installation
4. Configuration
5. Usage Examples
6. Response Format
7. Database Model
8. Dashboard & Media Manager UI
9. Cloud Storage Setup
10. Console Commands
11. ⚠️ Danger Zone / Known Limitations
12. Testing
13. Advanced Security & Performance Features
14. Security
15. Contributing
16. Changelog
17. License

1. Features

• Upload Handlers: Direct File Upload, Multiple (Batch) Uploads, Chunked (Resumable) Uploads, and Uploads from URL.
• Image Processing: On-the-fly resizing, format conversion (e.g. webp), optimization, and watermarking via Intervention Image v3.
• Storage Integration: Out-of-the-box support for Local disks, Amazon S3, Google Cloud Storage, and CDN URL rewriting.
• Multi-Source Media: Auto-discovery of custom Eloquent models via the HasMediaFields trait alongside the central polymorphic repository (HasUploads).
• Database Tracking: Comprehensive file tracking with usage state, polymorphic ownership, and soft deletion.
• Dashboard SPA: Built-in UI to manage files, view statistics, and handle orphans directly.
• Bulk Deletion Safety Net: 2-step verification (Preview → Token → Execute) for mass deletions to prevent catastrophic data loss.
• Security & Quotas: Strict SSRF URL validation, user-level storage quotas, strict MIME binary validation, and SVG entity expansion sanitization.

2. Requirements

3. Installation

1. Install via Composer:

2. Publish Configuration:

3. Run Migrations (Optional, requires database.enabled = true):

4. Configuration

This package is highly customizable through config/media-vault.php. Below is a comprehensive list of every configuration key available.

Storage (storage)

Validation (validation)

Contains standard Laravel validation strings mapped to file types (image, video, audio, document, other, custom_fields). Used internally to validate incoming files based on rules like sizes and MIME types.

URL Upload / Download (url_download & url_upload)

Image Processing (image_driver & processing)

Thumbnails (thumbnails)

Quota Management (quota)

Multi-Source & DB Tracking (media_models, database)

Security & Chunks (security, chunked)

Advanced Features (temp_url, compression, logging)

UI Dashboard (ui)

5. Usage Examples

Single & Multiple File Upload via HTTP Request

Direct Upload with UploadedFile

Upload from Remote URL

Upload Methods & Integration Scenarios

The package supports three distinct integration approaches depending on your application frontend architecture:

Option A: Traditional Blade HTML Form (No JS / Non-Chunked)

For standard Laravel applications submitting traditional HTML forms directly to the backend:

Blade Template (resources/views/upload.blade.php):

Laravel Controller:

Option B: Resumable Chunked Uploads (Blade + JS Client)

For web applications requiring client-side progress bars and auto-resumption across page refreshes or network drops:

Blade Template (resources/views/resumable-upload.blade.php):

Frontend JS Client Capabilities (media-vault.js)

• Per-File LocalStorage Fingerprint: Each file is uniquely hashed by afu_upload_${file.name}_${file.size}_${file.lastModified}.
• Incremental Persistence: Updates localStorage after every successful chunk and purges state when complete.
• Concurrent Multi-File Transfers: Supports uploading multiple files in parallel (afuUploadFiles([file1, file2])).
• Auto-Detection on Page Load: Automatically queries the backend for pending sessions on DOMContentLoaded and renders a Resume Card to re-send missing chunks only.

Option C: Mobile Applications & REST APIs (Flutter, React Native, Swift, Kotlin)

For mobile applications or single-page applications (SPAs) connecting via REST endpoints:

1. Send Chunks Sequentially

Upload binary chunk data to POST /media-vault/upload (or your custom API endpoint):

Response (First Chunk):

Mobile App stores sessionId in local storage (SharedPreferences / AsyncStorage / Hive).

2. Query Session Ground Truth on Re-Open / Resume

If the mobile app crashes or network disconnects, query the session status to get the exact missing chunk indices:

Response:

3. Send Missing Chunks & Complete Assembly

The mobile app sends only the indices listed in missing_chunks along with the sessionId. When the final chunk arrives, the server returns the completed UploadResult JSON object.

Using Central DB Tracking (HasUploads)

Use the HasUploads trait to link files to your models polymorphically via the file_uploads table.

Multi-Source Media Setup (HasMediaFields)

Use the HasMediaFields trait on models where you want to store file paths directly in the model's table columns, bypassing the central file_uploads table tracking while retaining the package UI, URL resolution, and scanners.

Run php artisan media-vault:discover-models to auto-register this model in your configuration cache.

Generating Thumbnails & Watermarks

Thumbnails and watermarks are generated automatically based on config/media-vault.php.

Warning: Watermarking is a destructive operation. It overrides the original image.

Deleting Files

Bulk Deletion Guard

Available in the BulkDeletionGuard utility service. Always preview a massive deletion action and generate a secure token to proceed.

6. Response Format

All successful uploads return an UploadResult object. It seamlessly implements ArrayAccess and JsonSerializable.

Failed items in a batch upload will return an array:

7. Database Model

If database.enabled is true, all uploads go to the file_uploads table. The FileUpload model includes powerful query scopes:

8. Dashboard & Media Manager UI

The package provides a built-in Single Page Application (SPA) dashboard to manage files, view sessions, configure settings, and scan for orphaned files.

• Route: your-app.com/media-vault (Changeable via ui.route_prefix).
• Security Warning: You must attach the auth middleware (or a custom admin middleware) in config/media-vault.php under ui.middleware. Without this, your entire media library is public.
• Features include real-time cache scans, orphaned file detection, token-based bulk forces deletions, and system statistics.

9. Cloud Storage Setup

To use Amazon S3 or Google Cloud Storage, you must require their Flysystem adapters. The package will intelligently throw a clear exception if they are missing.

• S3: composer require league/flysystem-aws-s3-v3:^3.0
• GCS: composer require spatie/laravel-google-cloud-storage:^2.0

10. Console Commands

The package registers several utilities to simplify file management:

• php artisan media-vault:discover-models — Scans the app/Models directory for HasMediaFields usage and caches them.
• php artisan media-vault:regenerate-thumbnails {--force} — Iterates over the file_uploads table and regenerates missing sizes based on config.
• php artisan media-vault:import-orphans {disk?} — Scans a physical disk and imports untracked files into the file_uploads table to prevent them from being considered orphans.
• php artisan media-vault:prune-unused {--days=30} {--force} {--dry-run} — Irreversibly deletes files that have been marked as unused for N days.
• php artisan media-vault:prune-sessions — Removes expired UploadSession records and their physical incomplete temporary chunks.

11. ⚠️ Danger Zone / Known Limitations

[!CAUTION] Pay strict attention to these operational warnings to prevent data loss in a production environment:

1. Thumbnails Backfill Limitation: The command media-vault:regenerate-thumbnails works flawlessly for the central file_uploads repository. However, it does NOT support Custom Models (Multi-Source) currently. Enabling thumbnails.enabled retroactively will not backfill thumbnails for custom models.
2. Watermarks are Destructive: Enabling watermark.enabled prints the watermark directly onto the original image. There is no backfill, and there is no way to remove a watermark once applied.
3. Removing Custom Models = Data Loss Risk: If you remove a model from media_models in the config after files have been uploaded, the scanner will immediately classify its files as "Orphaned". Running the Orphan Deletion will permanently wipe them. Always migrate or empty tables before changing configuration topology.
4. Custom Sources Pagination: To prevent Server Crashes (OOM) on huge DB tables, the Dashboard pagination for Custom Sources operates on Database Rows, not individual files. A JSON array of 5 images counts as 1 row in pagination.
5. Caching: If you register a new model or trait, you must run php artisan config:clear so the Dashboard recognizes it.

12. Testing

The package includes a comprehensive test suite. We specifically isolate heavy tests (Benchmarks) to prevent CI timeouts.

Run Unit & Feature Tests:

Run Memory & Performance Benchmarks:

(Current Test Count: 177 Passing/Skipped Tests).

13. Advanced Security & Performance Features

🛡️ Virus Scanning (ClamAV Integration)

The package includes built-in automated virus and malware scanning via ClamAV before any file is saved to storage.

• CLI Executable: Executes via local clamscan binary path configured in security.virus_scan.path.
• EICAR Detection: Industry-standard test signature EICAR-STANDARD-ANTIVIRUS-TEST-FILE is detected out-of-the-box in development and production environments.

⚡ File & Image Compression

Pipeline-integrated file compression reduces storage footprint for non-image document formats.

• Scope: Document formats (pdf, doc, docx, xls, xlsx, ppt, pptx).
• Execution: Runs directly inside the StorageManager write pipeline using quality parameters based on compression.quality.

⏱️ Dual-Layer Rate Limiting

The package distinguishes between two distinct rate limiting safeguards:

1. Package API Route Limiting (throttle:media-vault-api): Protects your application's endpoints (POST /media-vault/upload, POST /media/bulk-destroy, etc.) from abuse and denial-of-service attacks.

   When exceeded, endpoints return HTTP 429 Too Many Requests with { "status": false, "message": "Too Many Requests. Rate limit exceeded for file operations." }.

2. External Remote URL Throttling (UrlDownloader): Handles HTTP 429 status responses gracefully when downloading assets from remote third-party CDNs during URL uploads, failing fast with informative error messages.

14. Security

If you discover any security-related issues (such as bypasses for SSRF, traversal attacks, or token leaks in the Bulk Deletion Guard), please email [email protected] directly instead of opening a public issue. Alternatively, you can use GitHub Security Advisories if enabled on the repository.

15. Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Ensure all tests pass (composer test).
5. Push to the branch (git push origin feature/amazing-feature).
6. Open a Pull Request.

16. Changelog

Please see the CHANGELOG.md for more information on what has changed recently.

17. License

The MIT License (MIT). Please see License File for more information.