PhxMediaLibrary.PathGenerator.DateBased (PhxMediaLibrary v0.6.1)

Copy Markdown View Source

Date-based path generator for PhxMediaLibrary.

Organizes media files by their upload date, inserting a {year}/{month}/{day} prefix before the standard type/id/uuid hierarchy:

  • Original file: {year}/{month}/{day}/{mediable_type}/{mediable_id}/{uuid}/{filename}
  • Conversion: {year}/{month}/{day}/{mediable_type}/{mediable_id}/{uuid}/{base}_{conversion}{ext}

The date is derived from Date.utc_today() at the moment the path is generated (i.e., at upload time), so the path will reflect the upload date even if the database record is created slightly later.

Benefits

  • Easy to browse and archive files chronologically
  • Natural partitioning for backup and retention policies
  • Avoids hotspotting in storage systems with alphabetical key distribution
  • Clean lifecycle management: archive or delete entire date directories

Examples

# Assuming today is 2024-03-15
iex> media = %PhxMediaLibrary.Media{
...>   mediable_type: "posts",
...>   mediable_id: "abc-123",
...>   uuid: "550e8400-e29b-41d4-a716-446655440000",
...>   file_name: "photo.jpg"
...> }
iex> PhxMediaLibrary.PathGenerator.DateBased.relative_path(media, nil)
"2024/03/15/posts/abc-123/550e8400-e29b-41d4-a716-446655440000/photo.jpg"

iex> PhxMediaLibrary.PathGenerator.DateBased.relative_path(media, :thumb)
"2024/03/15/posts/abc-123/550e8400-e29b-41d4-a716-446655440000/photo_thumb.jpg"

Configuration

config :phx_media_library,
  path_generator: PhxMediaLibrary.PathGenerator.DateBased

Using with path_context

You can supply a custom date via path_context to backfill or migrate media without stomping on the current date. The context key :date must be a Date struct:

PhxMediaLibrary.PathGenerator.relative_path(media, :thumb, %{date: ~D[2023-01-01]})

Summary

Functions

for_new_media(attrs)

Generate a storage path for new media (before it has been persisted).

for_new_media(attrs, path_context)

Generate a storage path for new media with an optional path context.

relative_path(media, conversion \\ nil)

Generate the relative storage path for a media item.

relative_path(media, conversion, path_context)

Generate the relative storage path with an optional path context.

Functions

for_new_media(attrs)

@spec for_new_media(map()) :: String.t()

Generate a storage path for new media (before it has been persisted).

The date prefix is derived from Date.utc_today().

for_new_media(attrs, path_context)

@spec for_new_media(map(), map()) :: String.t()

Generate a storage path for new media with an optional path context.

Accepts an optional :date key in path_context to override the upload date. When absent, Date.utc_today() is used.

relative_path(media, conversion \\ nil)

@spec relative_path(PhxMediaLibrary.Media.t(), atom() | String.t() | nil) ::
  String.t()

Generate the relative storage path for a media item.

The date prefix ({year}/{month}/{day}) is derived from Date.utc_today().

relative_path(media, conversion, path_context)

@spec relative_path(PhxMediaLibrary.Media.t(), atom() | String.t() | nil, map()) ::
  String.t()

Generate the relative storage path with an optional path context.

Accepts an optional :date key in path_context to override the upload date. When absent, Date.utc_today() is used.

Example

PhxMediaLibrary.PathGenerator.DateBased.relative_path(media, nil, %{date: ~D[2023-01-01]})
# => "2023/01/01/posts/abc-123/uuid/photo.jpg"