PhoenixKit.Storage.FileInstance (phoenix_kit v1.5.1)

View Source

Schema for file variants (thumbnails, resizes, video qualities).

Each file can have multiple instances representing different versions:

  • original - The unchanged uploaded file
  • thumbnail - Small preview (150x150)
  • small - Small variant (300x300)
  • medium - Medium variant (800x600)
  • large - Large variant (1920x1080)
  • 360p - Video quality variant (640x360)
  • 720p - Video quality variant (1280x720)
  • 1080p - Video quality variant (1920x1080)
  • video_thumbnail - Thumbnail extracted from video (640x360)

All instances are stored next to the original file in the same directory.

Processing Status

  • pending - Instance not yet processed
  • processing - Currently being generated
  • completed - Successfully generated
  • failed - Generation failed

Fields

  • variant_name - Name of the variant (original, thumbnail, medium, etc.)
  • file_name - System filename (uuid_v7-variant.ext)
  • mime_type - MIME type of this variant
  • ext - File extension
  • checksum - Hash for integrity verification
  • size - Variant file size in bytes
  • width - Width in pixels (nullable)
  • height - Height in pixels (nullable)
  • processing_status - Current processing state
  • file_id - Parent file reference

Examples

# Original instance
%FileInstance{
  variant_name: "original",
  file_name: "018e3c4a-9f6b-7890-original.jpg",
  mime_type: "image/jpeg",
  ext: "jpg",
  checksum: "abc123...",
  size: 524_288,
  width: 2000,
  height: 2000,
  processing_status: "completed",
  file_id: "018e3c4a-9f6b-7890-abcd-ef1234567890"
}

# Thumbnail instance
%FileInstance{
  variant_name: "thumbnail",
  file_name: "018e3c4a-9f6b-7890-thumbnail.jpg",
  mime_type: "image/jpeg",
  ext: "jpg",
  checksum: "def456...",
  size: 8_192,  # 8 KB
  width: 150,
  height: 150,
  processing_status: "completed",
  file_id: "018e3c4a-9f6b-7890-abcd-ef1234567890"
}

# Video quality variant
%FileInstance{
  variant_name: "720p",
  file_name: "018e3c4a-9f6b-7890-720p.mp4",
  mime_type: "video/mp4",
  ext: "mp4",
  size: 5_242_880,  # 5 MB
  width: 1280,
  height: 720,
  processing_status: "processing"
}

Summary

Types

t()

Functions

changeset(instance, attrs)

Changeset for creating or updating a file instance.

completed?(arg1)

Returns whether this instance has been successfully processed.

failed?(arg1)

Returns whether this instance failed processing.

original?(arg1)

Returns whether this is the original file instance.

pending?(arg1)

Returns whether this instance is pending processing.

processing?(arg1)

Returns whether this instance is currently being processed.

Types

t()

@type t() :: %PhoenixKit.Storage.FileInstance{
  __meta__: term(),
  checksum: String.t(),
  ext: String.t(),
  file: PhoenixKit.Storage.File.t() | Ecto.Association.NotLoaded.t(),
  file_id: UUIDv7.t() | nil,
  file_name: String.t(),
  height: integer() | nil,
  id: UUIDv7.t() | nil,
  inserted_at: NaiveDateTime.t() | nil,
  locations:
    [PhoenixKit.Storage.FileLocation.t()] | Ecto.Association.NotLoaded.t(),
  mime_type: String.t(),
  processing_status: String.t(),
  size: integer(),
  updated_at: NaiveDateTime.t() | nil,
  variant_name: String.t(),
  width: integer() | nil
}

Functions

changeset(instance, attrs)

Changeset for creating or updating a file instance.

Required Fields

  • variant_name
  • file_name
  • mime_type
  • ext
  • checksum
  • size
  • file_id

Validation Rules

  • Processing status must be valid (pending, processing, completed, failed)
  • Size must be positive
  • Width/height must be positive (if provided)
  • Unique variant_name per file

completed?(arg1)

Returns whether this instance has been successfully processed.

failed?(arg1)

Returns whether this instance failed processing.

original?(arg1)

Returns whether this is the original file instance.

pending?(arg1)

Returns whether this instance is pending processing.

processing?(arg1)

Returns whether this instance is currently being processed.