Skip to content

🖼 Media Handling & Conversions

Last updated: 2025-10-09 (Europe/Paris)

RawDigs standardizes all first-party assets through Spatie Media Library. This page documents how media is stored, the collections each model exposes, and the conversions we generate for responsive delivery.

🗃 Storage & Table Structure

  • media table (see database/migrations/2025_05_19_104952_create_media_table.php) stores every attachment. Key columns:
  • model_type / model_id: polymorphic owner (e.g., App\Models\User, App\Models\Creators\Artist).
  • collection_name: logical grouping per model (avatar, artist_visuals, etc.).
  • file_name, disk, conversions_disk: raw storage info.
  • generated_conversions: JSON map showing which conversions were produced.
  • Files live on the primary disk defined in config/filesystems.php; conversions can be stored on the same or a dedicated conversions disk.

All media interactions go through model traits implementing Spatie\MediaLibrary\HasMedia.

📦 Model Collections & Conversions

Model Collection Purpose Conversions
App\Models\User avatar Account avatars for supporters, artists, label staff. avatar_thumb (80x80 crop), avatar_small (40x40 crop).
App\Models\Creators\Artist artist_visuals Hero imagery, banners, gallery assets. hero_large (1600x900 cover), hero_medium (960x540), thumb (320x180).
App\Models\Creators\ArtistProfile press_assets Press kit attachments (logo, EPK). press_web (1200px wide), press_thumb (300px).
App\Models\Catalog\Release (planned) release_artwork Cover art for releases/products. cover_large (1400x1400), cover_medium (800x800), cover_thumb (400x400).
App\Models\Catalog\Product (planned) product_images Merch/product imagery. product_large (1200x1200), product_thumb (400x400).

Note: Release/Product collections are planned for the Catalog context; conversions may evolve as storefront requirements finalize.

🛠 Usage Patterns

  • Attaching Media
$user->addMedia($request->file('avatar'))
     ->toMediaCollection('avatar');
  • Registering Conversions
public function registerMediaConversions(Media $media = null): void
{
    $this->addMediaConversion('avatar_thumb')
         ->fit('crop', 80, 80)
         ->nonQueued();

    $this->addMediaConversion('avatar_small')
         ->fit('crop', 40, 40)
         ->nonQueued();
}
  • Serving Assets
$avatarUrl = $user->getFirstMediaUrl('avatar', 'avatar_thumb');
  • Custom Properties Use withCustomProperties() to store metadata (e.g., theme color extracted from the image) for downstream features.
  • docs/contexts/accounts/models.md — Notes on user avatars and media references.
  • docs/contexts/creators/models.md — Visuals and press assets stored through Media Library.
  • docs/contexts/diagrams/index.md — ER diagrams (media table coming soon alongside Catalog context).