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.