README

Laravel Artifact is a lightweight package for media management in Laravel applications. It makes file uploads, storage, and retrieval easy — with support for public/private disks, signed URLs, and automatic deduplication.

✨ Features

• Simple file upload and storage management
• Support for multiple storage disks (local, S3, etc.)
• Automatic deduplication to prevent duplicate files
• Signed URLs for secure file access
• Clean one-to-one and one-to-many file relationships
• Automatic metadata tracking (filename, MIME type, size)

???? Installation

Install via Composer:

composer require laraveljutsu/laravel-artifact

Publish the configuration and run migrations:

php artisan vendor:publish --tag="laravel-artifact"

???? Usage

1. Configure the package

Configure the package in the config/artifact.php file.

return [ 'model' => LaravelJutsu\Artifact\Artifact::class, 'table_name' => 'artifacts', 'routes' => [ 'prefix' => env('ARTIFACT_ROUTE_PREFIX', 'artifacts'), 'middleware' => ['web'], ], 'signed_url' => [ 'expiration_minutes' => env('ARTIFACT_SIGNED_URL_EXPIRATION', 60), ], ]; // .env ARTIFACT_ROUTE_PREFIX=artifacts ARTIFACT_SIGNED_URL_EXPIRATION=60

After configuring the package, run the migrations:

php artisan optimize php artisan migrate

2. Add the trait to your model

<?php use LaravelJutsu\Artifact\Concerns\HasArtifacts; use Illuminate\Database\Eloquent\Model; class User extends Model { use HasArtifacts; // Single file relationship public function avatar() { return $this->singleArtifact('avatar'); } // Multiple files relationship public function documents() { return $this->manyArtifacts('documents'); } }

3. Store files

$user = User::find(1); $file = request()->file('avatar'); // Single file (one-to-one) $artifact = $user->avatar()->store($file); // Multiple files (one-to-many) $artifacts = $user->documents()->store(request()->file('documents')); // Specify storage disk $artifact = $user->avatar()->store($file); // Uses default disk $artifacts = $user->documents()->store($files, 'public');

4. Access files and metadata

$avatar = $user->avatar; if ($avatar) { // Get URLs echo $avatar->rawUrl(); // Direct URL (public disks only) echo $avatar->streamUrl(); // Streaming URL (works for all disks) echo $avatar->signedUrl(); // Permanent signed URL echo $avatar->temporarySignedUrl(60); // Expiring signed URL (60 minutes) // Access metadata echo $avatar->file_name; // Original filename echo $avatar->mime_type; // File MIME type echo $avatar->size; // File size in bytes echo $avatar->disk; // Storage disk name } // Working with multiple files foreach ($user->documents as $document) { echo $document->file_name . ' (' . $document->size . ' bytes)'; echo $document->streamUrl(); }

???? Requirements

• PHP 8.2+
• Laravel 10+

???? License

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