alareqi/smart-upload

Laravel package for mobile file uploads with Livewire-style temporary storage.

v1.3 2026-04-25 16:06 UTC

Requires

• php: ^8.4
• ankitpokhrel/tus-php: ^2.4
• illuminate/contracts: ^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Ayman Alareqi

• laravel
• alareqi
• smart-upload

README

Laravel package for mobile file uploads with temporary storage - no database required.

This package provides a simple way to handle file uploads from mobile apps. Files are uploaded to a temporary location, then moved to their final destination when the form is submitted.

Installation

composer require alareqi/smart-upload

No migrations needed - this package uses file-based temporary storage.

How It Works

┌─────────────┐     /upload-file ┌─────────────┐
│ Mobile App  │ ────────────▶ │   Laravel  │
│             │               │   Server   │
│ 1.Select   │ ◀─────────── │ 2.Return  │
│    file    │    upload   │   signed  │
│             │     URL    │    URL   │
│ 3.Upload   │ ────────────▶ │          │
│    to URL   │  4.Upload  │          │
│             │    file   │          │
│5.Submit     │ ────────────▶ │6.Move to │
│    form    │   form     │ final    │
│             │   data    │ location │
└─────────────┘             └─────────────┘

API Endpoints

Method	Endpoint	Description
POST	/api/upload-file	Upload file

Upload File

Upload a file directly to the endpoint:

POST /api/upload-file
Content-Type: multipart/form-data

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

[file content]
------WebKitFormBoundary--

Response:

{
    "uuid": "abc-123-uuid",
    "path": "tmp/abc-123.jpg",
    "original_name": "photo.jpg",
    "size": 1024,
    "mime_type": "image/jpeg",
    "temp_url": "https://yourapp.com/storage/tmp/abc-123.jpg",
    "expires_at": "2024-01-01T12:00:00Z"
}

Laravel Controller Usage

Use the HasFileUploads trait in your controller:

use Alareqi\SmartUpload\Concerns\HasFileUploads;
use Illuminate\Http\Request;

class PostController extends Controller
{
    use HasFileUploads;

    public function store(Request $request)
    {
        // Convert temporary upload to permanent storage
        $path = $this->convertUpload(
            $request->image_uuid,  // UUID from mobile
            'posts/images'        // Final directory
        );

        // Save to database
        Post::create([
            'title' => $request->title,
            'image' => $path,
        ]);
    }
}

Multiple Files

For multiple file uploads, pass an array of UUIDs:

use Alareqi\SmartUpload\Concerns\HasFileUploads;
use Illuminate\Http\Request;

class PostController extends Controller
{
    use HasFileUploads;

    public function store(Request $request)
    {
        $imagePaths = [];

        // $request->image_uploads is array: ['uuid1', 'uuid2', 'uuid3']
        foreach ($request->image_uploads as $uuid) {
            $imagePaths[] = $this->convertUpload(
                $uuid,
                'posts/images'
            );
        }

        // Save to database
        Post::create([
            'title' => $request->title,
            'images' => json_encode($imagePaths),
        ]);
    }
}

Or convert each with custom filename:

foreach ($request->images as $index => $uuid) {
    $path = $this->convertUpload(
        $uuid,
        'posts/images',
        'post_' . $post->id . '_image_' . $index . '.jpg'  // Custom filename
    );
}

Configuration

Edit config/smart-upload.php:

return [
    // Final storage disk
    'disk' => env('SMART_UPLOAD_DISK', 'local'),

    // Temporary directory
    'temp_directory' => env('SMART_UPLOAD_TEMP_DIR', 'smart-upload-tmp'),

    // Hours until temp file expires (also used as cache TTL)
    'expiration_hours' => 24,

    // Max file size in KB
    'max_file_size' => 10240,

    // Allowed mimes
    'allowed_mimes' => ['jpg', 'jpeg', 'png', 'gif', 'pdf'],

    // Cache driver for metadata
    'cache' => [
        'driver' => env('SMART_UPLOAD_CACHE_DRIVER', 'file'),
    ],

    // Temporary upload settings
    'temporary_file_upload' => [
        'disk' => 'local',
        'directory' => 'tmp',
    ],
];

Cleanup Command

Run cleanup to delete expired temporary files:

php artisan smart-upload:cleanup

Schedule it in app/Console/Kernel.php:

protected function schedule(Schedule $schedule)
{
    $schedule->command('smart-upload:cleanup')->hourly();
}

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ayman Alareqi
• All Contributors

License

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