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"
php artisan migrate

🚀 Usage

1. 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');
    }
}

2. 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');

3. 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.

laraveljutsu / laravel-artifact

Maintainers

Details