mohamedsamy902 / advanced-file-upload
A comprehensive file upload package for Laravel with cloud storage and image processing
Installs: 12
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
pkg:composer/mohamedsamy902/advanced-file-upload
Requires
- php: ^8.0
- intervention/image: ^2.7
- laravel/framework: ^9.0|^10.0|^11.0|^12.0
- league/flysystem-aws-s3-v3: ^3.0
- pion/laravel-chunk-upload: ^1.5
- spatie/laravel-google-cloud-storage: ^2.0
Requires (Dev)
- orchestra/testbench: ^7.0
- phpunit/phpunit: ^9.5
This package is auto-updated.
Last update: 2025-09-29 08:32:36 UTC
README
A comprehensive file upload package for Laravel, supporting local and cloud storage, image processing, file compression, format conversion, and much more.
🚀 Features
- ✅ API & HTML Uploads — Seamless integration for both API endpoints and HTML forms.
- ☁️ Cloud Storage Support — S3, Google Cloud Storage, and any Laravel-supported disk.
- 🖼️ Image Processing — Resize, watermark, apply filters, convert to WebP/AVIF (via Intervention Image).
- 🖼️ Automatic Thumbnails — Generate thumbnails in custom sizes.
- 🗜️ File Compression — Compress PDFs, DOCX, and other docs (requires external tools).
- 📦 Chunked Uploads — Handle large files with Pion Laravel Chunk Upload.
- 📊 Quota System — Set storage limits per user.
- 🔗 CDN Support — Serve files via your preferred CDN.
- 🧩 Database Integration — Store metadata for uploaded files (optional).
- 🧪 Unit Testing — PHPUnit coverage included.
📦 Requirements
- PHP >= 8.0
- Laravel >= 9.0
- Composer
⚙️ Installation
-
Install the package via Composer:
composer require mohamedsamy902/advanced-file-upload:dev-main
-
Publish the config file:
php artisan vendor:publish --tag=config
-
(Optional) Publish and run the migration:
php artisan vendor:publish --tag=migrations php artisan migrate
-
Configure your
.env
file:FILE_UPLOAD_DISK=s3 FILE_UPLOAD_DB_ENABLED=true FILE_UPLOAD_CDN_ENABLED=true FILE_UPLOAD_CDN_URL=https://your-cdn.com
🔧 Configuration
Edit config/file-upload.php
to customize:
Section | Description |
---|---|
Storage | Choose disk (local, s3, gcs), base path, and organization structure. |
Validation | Define file rules by type: image, video, document, etc. |
Image Handling | Enable resizing, filters, watermarks, format conversion (e.g., WebP). |
Thumbnails | Set custom sizes (e.g., small , medium , large ). |
Compression | Enable file compression by MIME type or extension. |
Quota | Set storage limits per user ID. |
CDN | Enable CDN URLs and base path for serving uploaded assets. |
💡 Usage
Upload via Controller
use MohamedSamy902\AdvancedFileUpload\Facades\FileUpload; public function uploadFile(Request $request) { $result = FileUpload::upload($request, 'profile_picture', [ 'convert_to' => 'webp', ]); return response()->json($result); }
Download Image Or Video By Url
public function download() { $result = FileUpload::upload([], [ 'url' => 'http://Example.com/vwdio.mp4', ]); return response()->json($result); }
Delete a File
public function deleteFile($idOrPath) { $result = FileUpload::delete($idOrPath); return response()->json($result); }
🧾 HTML Form Example
<form action="/upload" method="POST" enctype="multipart/form-data"> @csrf <input type="file" name="profile_picture" /> <button type="submit">Upload</button> </form>
🧪 API Example
curl -X POST http://your-app.com/upload \
-F "profile_picture=@/path/to/image.jpg"
Response
{ "path": "uploads/2025/06/23/uuid.jpg", "url": "https://your-cdn.com/uploads/2025/06/23/uuid.jpg", "thumbnail_urls": { "small": "https://your-cdn.com/uploads/2025/06/23/thumb_small_uuid.jpg", "medium": "https://your-cdn.com/uploads/2025/06/23/thumb_medium_uuid.jpg" }, "mime_type": "image/jpeg" }
🧪 Testing
Run PHPUnit tests:
vendor/bin/phpunit
🤝 Contributing
Contributions are welcome!
Please submit pull requests or open issues via GitHub Issues.
📄 License
This package is open-sourced software licensed under the MIT license.
📘 Usage Guide (Arabic)
طريقة الاستخدام
1. إنشاء الباكدج
- أنشئ مجلدًا باسم
advanced-file-upload
. - ضع الملفات ضمن الهيكلية المناسبة.
- استبدل
your-vendor
باسمك أو اسم شركتك في الملفات وcomposer.json
.
2. نشر الباكدج
- أنشئ مستودع GitHub.
- اربطه مع Packagist لنشر الباكدج.
- حدّث
composer.json
باسمك كمزود.
3. تثبيت الباكدج في مشروع Laravel
composer require your-vendor/advanced-file-upload
4. إعداد التخزين السحابي
- أضف تعريف S3 أو GCS في
config/filesystems.php
. - ضبّط بيانات الاعتماد في
.env
.
5. اختبار الباكدج
vendor/bin/phpunit
🧩 الميزات التفصيلية
الميزة | الوصف |
---|---|
التخزين السحابي | يدعم S3، Google Cloud، وغيرها عبر Laravel Filesystem. |
معالجة الصور | تغيير الحجم، العلامة المائية، فلاتر، تحويل إلى WebP/AVIF. |
الصور المصغرة | إنشاء تلقائي لأحجام متعددة. |
ضغط الملفات | ضغط ملفات PDF و DOCX (يتطلب أدوات خارجية). |
نظام الكوتا | تعيين حدود تخزين لكل مستخدم. |
دعم CDN | تقديم الملفات عبر شبكة CDN. |
قاعدة البيانات | تخزين بيانات الملفات اختياريًا في جدول مرتبط. |
الرفع المجزأ | دعم رفع الملفات الكبيرة باستخدام Pion Laravel Chunk Upload . |
New
AdvancedFileUpload for Laravel
A comprehensive file upload package for Laravel, supporting local and cloud storage, image processing, file compression, format conversion, chunked uploads, ready-to-use Blade UI, and more.
🚀 Features
- ✅ API & HTML Uploads — Seamless integration for both API endpoints and HTML forms.
- ☁️ Cloud Storage Support — S3, Google Cloud Storage, and any Laravel-supported disk.
- 🖼️ Image Processing — Resize, watermark, apply filters, convert to WebP/AVIF (via Intervention Image).
- 🖼️ Automatic Thumbnails — Generate thumbnails in custom sizes.
- 🗜️ File Compression — Compress PDFs, DOCX, and other docs (requires external tools).
- 📦 Chunked Uploads — Handle large files with Pion Laravel Chunk Upload.
- 📊 Quota System — Set storage limits per user.
- 🔗 CDN Support — Serve files via your preferred CDN.
- 🧩 Database Integration — Store metadata for uploaded files (optional).
- 🎨 Ready Blade UI — Plug-and-play Blade upload form with chunked JS & CSS, easily customizable.
- 🧪 Unit Testing — PHPUnit coverage included.
📦 Requirements
- PHP >= 8.0
- Laravel >= 9.0
- Composer
⚙️ Installation
-
Install the package via Composer:
composer require mohamedsamy902/advanced-file-upload:dev-main
-
Publish the config file:
php artisan vendor:publish --tag=config
-
(Optional) Publish and run the migration:
php artisan vendor:publish --tag=migrations php artisan migrate
-
(Optional) Publish Blade, JS, and CSS for customization:
php artisan vendor:publish --tag=views php artisan vendor:publish --tag=public
-
Configure your
.env
file:FILE_UPLOAD_DISK=public FILE_UPLOAD_DB_ENABLED=true FILE_UPLOAD_CDN_ENABLED=false FILE_UPLOAD_CDN_URL=
🔧 Configuration
Edit config/file-upload.php
to customize:
Section | Description |
---|---|
Storage | Choose disk (local, s3, gcs), base path, and organization structure. |
Validation | Define file rules by type: image, video, document, etc. |
Image Handling | Enable resizing, filters, watermarks, format conversion (e.g., WebP). |
Thumbnails | Set custom sizes (e.g., small , medium , large ). |
Compression | Enable file compression by MIME type or extension. |
Quota | Set storage limits per user ID. |
CDN | Enable CDN URLs and base path for serving uploaded assets. |
💡 Usage & Examples
1. Upload via Controller (Single File)
use MohamedSamy902\AdvancedFileUpload\Facades\FileUpload; public function upload(Request $request) { $result = FileUpload::upload($request); return response()->json($result); }
HTML Form:
<form action="{{ route('upload') }}" method="POST" enctype="multipart/form-data"> @csrf <input type="file" name="file"> <button type="submit">رفع</button> </form>
2. Upload Multiple Files
public function upload(Request $request) { $result = FileUpload::upload($request, ['field_name' => 'files']); return response()->json($result); }
HTML:
<form action="{{ route('upload') }}" method="POST" enctype="multipart/form-data"> @csrf <input type="file" name="files[]" multiple> <button type="submit">رفع</button> </form>
3. Upload from URL
$result = FileUpload::upload([], [ 'url' => 'https://example.com/image.jpg', ]);
4. Use the Ready Blade Upload UI
Just add in your Blade view:
@include('advanced-file-upload::upload')
Or after publishing:
@include('vendor.advanced-file-upload.upload')
- This will include the ready HTML, JS, and CSS for chunked uploads and progress bar.
- You can customize the UI by editing the published files.
5. Chunked Upload with JS (Large Files)
The included JS (advanced-file-upload.js
) supports chunked uploads out of the box.
You can use it directly or customize it after publishing.
Example:
<input type="file" id="afu-fileInput"> <button onclick="afuUploadFile({ uploadUrl: '/upload' })">رفع</button> <div class="afu-progress-bar"><div class="afu-progress-bar-inner" id="afu-progress-bar-inner"></div></div> <div id="afu-status"></div> <link rel="stylesheet" href="{{ asset('vendor/advanced-file-upload/advanced-file-upload.css') }}"> <script src="{{ asset('vendor/advanced-file-upload/advanced-file-upload.js') }}"></script>
6. Customize Validation, Processing, or Storage
$result = FileUpload::upload($request, [ 'convert_to' => 'webp', 'validation_rules' => [ 'file' => 'required|image|max:2048' ], 'folder_name' => 'avatars' ]);
7. Delete Files
// Delete by path FileUpload::delete('uploads/default/uuid.jpg'); // Delete by database ID (if DB enabled) FileUpload::delete(5); // Delete multiple files FileUpload::delete(['uploads/default/uuid1.jpg', 'uploads/default/uuid2.jpg']);
8. Access Thumbnails
$result = FileUpload::upload($request); $thumbUrl = $result['thumbnail_urls']['small'] ?? null;
9. CDN Support
If you enable CDN in your config:
// config/file-upload.php 'cdn' => [ 'enabled' => true, 'url' => 'https://your-cdn.com', ],
All returned URLs will use your CDN domain.
10. Database Integration
If enabled, every upload will be saved in the file_uploads
table.
You can access file metadata using the model:
use MohamedSamy902\AdvancedFileUpload\Models\FileUpload; $files = FileUpload::where('user_id', auth()->id())->get();
11. Quota System
Set per-user quota in config:
// config/file-upload.php 'quota' => [ 'enabled' => true, 'max_size_per_user' => 1073741824, // 1GB ],
If a user exceeds their quota, an exception will be thrown.
12. Customize Blade, JS, and CSS
After publishing:
php artisan vendor:publish --tag=views php artisan vendor:publish --tag=public
- Edit
resources/views/vendor/advanced-file-upload/upload.blade.php
- Edit
public/vendor/advanced-file-upload/advanced-file-upload.css
- Edit
public/vendor/advanced-file-upload/advanced-file-upload.js
🧪 Testing
Run PHPUnit tests:
vendor/bin/phpunit
🤝 Contributing
Contributions are welcome!
Please submit pull requests or open issues via GitHub Issues.
📄 License
This package is open-sourced software licensed under the MIT license.
📘 Usage Guide (Arabic)
أمثلة الاستخدام
رفع ملف من فورم HTML
<form action="{{ route('upload') }}" method="POST" enctype="multipart/form-data"> @csrf <input type="file" name="file"> <button type="submit">رفع</button> </form>
رفع ملف من رابط
$result = FileUpload::upload([], ['url' => 'https://example.com/image.jpg']);
استخدام واجهة Blade الجاهزة
@include('advanced-file-upload::upload')
حذف ملف
FileUpload::delete('uploads/default/uuid.jpg');
تخصيص الاستايل
بعد النشر:
- عدل CSS/JS في
public/vendor/advanced-file-upload/
- عدل Blade في
resources/views/vendor/advanced-file-upload/
🧩 الميزات التفصيلية
الميزة | الوصف |
---|---|
التخزين السحابي | يدعم S3، Google Cloud، وغيرها عبر Laravel Filesystem. |
معالجة الصور | تغيير الحجم، العلامة المائية، فلاتر، تحويل إلى WebP/AVIF. |
الصور المصغرة | إنشاء تلقائي لأحجام متعددة. |
ضغط الملفات | ضغط ملفات PDF و DOCX (يتطلب أدوات خارجية). |
نظام الكوتا | تعيين حدود تخزين لكل مستخدم. |
دعم CDN | تقديم الملفات عبر شبكة CDN. |
قاعدة البيانات | تخزين بيانات الملفات اختياريًا في جدول مرتبط. |
الرفع المجزأ | دعم رفع الملفات الكبيرة باستخدام Pion Laravel Chunk Upload . |
Blade UI | واجهة Blade جاهزة وقابلة للتخصيص. |
تخصيص كامل | CSS/JS/Blade قابل للنشر والتعديل بسهولة. |