Documentation v1.0.0

Overview

Laravel Uploads is a secure, structured library designed to simplify database-linked file storage, dynamic image optimization, private/expiring URL routing, and on-demand streaming proxy pipelines inside Laravel projects.

Installation

Ensure your environment satisfies the minimum requirements (PHP 8.1+ and Laravel 10 through 13). Install the library via Composer:

composer require ghostcompiler/laravel-uploads

Publish configuration settings and the database migration stub:

php artisan install:laravel-uploads

Run your migrations to generate target database tables:

php artisan migrate

php artisan install:laravel-uploads --force

Configuration Reference

The configuration file publishes to config/laravel-uploads.php. Review the technical behavior of all available options below:

Core Manager APIs

The LaravelUploadsManager class contains all methods to upload, retrieve, check, and delete files.

1. File Uploads

Store files on the destination storage disk using the upload() method.

use GhostCompiler\LaravelUploads\Facades\Uploads;

// basic upload (uses default disk and base path)
$upload = Uploads::upload($request->file('avatar'));

// upload into a specific folder sub-path
$upload = Uploads::upload('users/avatars', $request->file('avatar'));

// upload with configuration override options
$upload = Uploads::upload($request->file('avatar'), [
    'visibility' => 'public',
    'expiry' => 120, // override expiration to 2 hours
]);

2. Upload Multiple Files

Store an array of files in a single call using uploadMany().

// returns array of GhostCompiler\LaravelUploads\Models\Upload models
$uploads = Uploads::uploadMany($request->file('photos'), 'galleries');

3. Retrieve Uploads

Find an upload record in the database using the find() helper.

$upload = Uploads::find($uploadId); // returns ?Upload model

4. File Deletion

Delete the database record, clear the URL caches, and delete the physical storage file:

// delete by passing the Upload model, ID integer, or ID string
$success = Uploads::remove($uploadId); // returns bool

Eloquent Integration

Apply the GhostCompiler\LaravelUploads\Concerns\LaravelUploads trait to link files to your tables.

use GhostCompiler\LaravelUploads\Concerns\LaravelUploads;
use Illuminate\Database\Eloquent\Model;

class Document extends Model
{
    use LaravelUploads;

    protected $uploadable = [
        'file_id' => [
            'name' => 'file',
            'type' => 'private',
            'expiry' => 15,
        ],
    ];
}

Eloquent Features

• Automatic Hiding: The raw database key column (e.g. file_id) is automatically hidden in array and JSON serialization if configured.
• Virtual Attribute resolution: Accessing $document->file resolves to the tokenized or public URL directly.
• Eloquent Relation mapping: Retrieve the model relationship directly via:

  $uploadModel = $document->upload('file_id'); // returns BelongsTo relationship

Custom Hook Methods

Intercept and customize resolved URLs by declaring hook methods in the model.

Field-specific Hooks: Pattern matches set{FieldName}UploadableValue.

public function setAvatarUploadableValue($value, string $column, array $options)
{
    // returns the URL customized with URL query parameters
    return $value . '?size=thumbnail';
}

Model-wide Hook: Fallback hook pattern matches setUploadableValue.

public function setUploadableValue($value, string $column, array $options)
{
    return [
        'url' => $value,
        'name' => $options['name'],
        'visibility' => $options['visibility']
    ];
}

Dynamic URL Proxying

The package supports uploading external file URLs. Instead of downloading and saving physical files to local/S3 disks, the database stores the reference and proxies the file in real-time when accessed.

1. Storing URLs

// Store a remote image link as a reference
$upload = Uploads::upload('https://avatar.example.com/profiles/avatar.jpg');

// Storing under custom path/directory settings
$upload = Uploads::upload('avatars', 'https://avatar.example.com/avatar.jpg', [
    'visibility' => 'private'
]);

2. Serving URLs

When resolving URL-based uploads, the package routes the path through the secure package route /_laravel-uploads/file/{token}. The client browser never sees the original remote URL.

Resolving URLs

Resolve file URLs using the manager instances:

// 1. Resolve URL from an Upload instance
$url = Uploads::url($upload, 30); // 30 minutes token expiration

// 2. Resolve URL from an Upload ID database column
$url = Uploads::urlFromId($uploadId, 60); // 60 minutes token expiration

// 3. Register a public URL resolver callback (useful for CDN hosting or Multi-tenant apps)
Uploads::resolvePublicUrlsUsing(function ($upload, $disk, $path) {
    return "https://cdn.my-app.com/{$path}";
});

Artisan Commands

The package registers console commands for maintenance:

Prune Expired Links

Prunes all expired temporary token links from the laravel_uploads_links table:

php artisan ghost:laravel-uploads-clean

Run a dry run execution to review the count of deletable records without pruning them:

php artisan ghost:laravel-uploads-clean --dry-run

Route & Serving Mechanics

Files are served securely through the dynamic endpoint:

Routing Options

Modify route attributes inside config/laravel-uploads.php:

• route.prefix: Customize the serving prefix (default '_laravel-uploads').
• route.name: Customize the route name (default 'laravel-uploads.show').
• route.middleware: Apply middleware checks (e.g., 'auth') to restrict file access to authenticated sessions.

Download Control

Force download disposition on previewable file types (PDFs, images) by appending the query parameter:

GET /_laravel-uploads/file/{token}?download=1

Security Defaults

The package implements multiple default security standards:

• Traversal Prevention: Path segments containing directory modifications (.., .) are parsed and blocked immediately to prevent directory escaping.
• File Type Constraints: PHP files and scripts are restricted globally via the never_allowed_extensions list, preventing remote code execution (RCE).
• SVG Sanitization: Image files matching image/svg+xml are blocked from rendering inline. SVG requests are always forced to download as attachments to prevent stored Cross-Site Scripting (XSS).