📸 ItemImage Model

The ItemImage model manages the association between Items and their images, providing image galleries with display ordering and management capabilities.

📊 Model Overview

Property Type Description
Model Name ItemImage Primary image management model
Table Name item_images Database table
Primary Key id (UUID) Unique identifier
Timestamps ✅ Yes created_at, updated_at
Soft Deletes ❌ No Hard deletes only

🏗️ Database Schema

Column Type Constraints Description
id uuid Primary Key Unique identifier (UUID)
item_id uuid Foreign Key, Required References items.id
available_image_id uuid Foreign Key, Required References available_images.id
display_order integer Required, Default: 1 Order for display (1 = first)
backward_compatibility string Nullable Legacy system reference
created_at timestamp Auto-managed Creation timestamp
updated_at timestamp Auto-managed Last update timestamp

🔗 Relationships

Belongs To

Scopes

🎯 Key Features

📋 Display Order Management

// Attach image with specific display order
$item->attachImage($availableImageId, $displayOrder);

// Reorder images
$item->reorderImages([
    $imageId1 => 1,  // First position
    $imageId2 => 2,  // Second position
    $imageId3 => 3,  // Third position
]);

// Get ordered images for an item
$orderedImages = $item->images()->ordered()->get();

🔄 Image Management Operations

// Attach new image (automatically sets display order)
$item->itemImages()->create([
    'available_image_id' => $availableImageId,
    'display_order' => $item->itemImages()->max('display_order') + 1
]);

// Detach image
$item->itemImages()
    ->where('available_image_id', $availableImageId)
    ->delete();

// Move image to first position
$itemImage = $item->itemImages()->find($imageId);
$itemImage->moveToPosition(1);

🔧 Model Methods

Display Order Management

public function moveToPosition(int $position): void
public function moveUp(): void
public function moveDown(): void
public function moveToTop(): void
public function moveToBottom(): void

Query Helpers

public function scopeOrdered(Builder $query): Builder
public function scopeForItem(Builder $query, string $itemId): Builder

🌍 API Integration

Available Endpoints

Resource Structure

{
  "id": "uuid",
  "item_id": "uuid",
  "available_image_id": "uuid",
  "display_order": 1,
  "backward_compatibility": null,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "item": {
    /* ItemResource */
  },
  "available_image": {
    /* AvailableImageResource */
  }
}

⚙️ Business Logic

Unique Constraints

Validation Rules

// Store Request
[
    'available_image_id' => 'required|uuid|exists:available_images,id',
    'display_order' => 'sometimes|integer|min:1'
]

// Reorder Request
[
    'images' => 'required|array',
    'images.*' => 'uuid|exists:item_images,id'
]

Usage Examples

Basic Image Management

// Create new item with images
$item = Item::create(['internal_name' => 'Ancient Vase']);

// Attach images in order
$item->attachImage($image1Id, 1);
$item->attachImage($image2Id, 2);
$item->attachImage($image3Id, 3);

// Get all images for display
$gallery = $item->images()
    ->ordered()
    ->with('availableImage')
    ->get();

Advanced Ordering

// Reorder entire gallery
$item->reorderImages([
    $imageId3 => 1,  // Move third image to first
    $imageId1 => 2,  // Move first image to second
    $imageId2 => 3,  // Move second image to third
]);

// Insert image at specific position
$item->insertImageAt($newImageId, 2); // Insert at position 2